fix(core): don't assume a 64-character idempotency key is pre-hashed on reset

`resetIdempotencyKey` treated any 64-character string as an already-computed
hash and sent it to the API verbatim. That short-circuit ran before the scope
logic, so a user key that is itself a 64-character digest had an explicitly
passed `scope` silently discarded and was sent un-hashed, matching no run.

A 64-character string is now only passed through when there is evidence it is
already a hash: the idempotency key catalog recognises it (so it came from
`idempotencyKeys.create()`), or no `scope` was passed and the length is the
only signal available. An explicit `scope` is an explicit request to derive
the hash, so it is always honoured.

This keeps both existing behaviours intact: a key from `idempotencyKeys.create()`
is still forwarded unchanged, and 64-character key material passed straight to
`trigger()` and reset without a scope is still sent verbatim. `isIdempotencyKey`
is deliberately untouched, since the trigger path is self-consistent and
changing it would invalidate already-stored keys.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.changeset/reset-idempotency-key-64-char.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+`idempotencyKeys.reset()` now works when your idempotency key is itself 64 characters long (for example if you use a hash of your own as the key). Previously any 64-character key was assumed to be already hashed, so passing one along with a `scope` silently ignored the scope and the reset never found a matching run. Keys returned by `idempotencyKeys.create()` continue to be reset exactly as before.

packages/core/src/v3/idempotencyKeys.test.ts

@@ -1,9 +1,14 @@
-import { describe, it, expect } from "vitest";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { apiClientManager } from "./apiClientManager-api.js";
 import {
   createIdempotencyKey,
   getIdempotencyKeyOptions,
+  resetIdempotencyKey,
   resetIdempotencyKeyCatalog,
 } from "./idempotencyKeys.js";
+import { digestSHA256 } from "./utils/crypto.js";
 
 describe("idempotencyKeys metadata retention", () => {
   it("retains key/scope options for every key created in a run, even beyond 1000", async () => {
@@ -40,3 +45,96 @@ describe("idempotencyKeys metadata retention", () => {
     expect(getIdempotencyKeyOptions(key)).toBeUndefined();
   });
 });
+
+describe("resetIdempotencyKey", () => {
+  // A user key that is itself a 64-character digest, which is indistinguishable by
+  // length from a key returned by `idempotencyKeys.create()`.
+  const digestShapedKey = "a".repeat(64);
+
+  let server: Server;
+  let resetKeys: string[] = [];
+
+  /** The value `resetIdempotencyKey` put on the wire. */
+  async function resetAndCaptureKey(
+    ...args: Parameters<typeof resetIdempotencyKey>
+  ): Promise<string> {
+    resetKeys = [];
+    await resetIdempotencyKey(...args);
+    expect(resetKeys).toHaveLength(1);
+    return resetKeys[0]!;
+  }
+
+  beforeEach(async () => {
+    resetIdempotencyKeyCatalog();
+
+    server = createServer((req, res) => {
+      req.resume();
+      req.on("end", () => {
+        const match = /^\/api\/v1\/idempotencyKeys\/(.+)\/reset$/.exec(req.url ?? "");
+        if (!match) {
+          res.writeHead(404).end();
+          return;
+        }
+
+        resetKeys.push(decodeURIComponent(match[1]!));
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ id: "run_reset" }));
+      });
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+
+    apiClientManager.setGlobalAPIClientConfiguration({
+      baseURL: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+      accessToken: "tr_test_key",
+    });
+  });
+
+  afterEach(async () => {
+    apiClientManager.disable();
+    resetIdempotencyKeyCatalog();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it("hashes 64-character key material when an explicit scope is passed", async () => {
+    const created = await createIdempotencyKey(digestShapedKey, { scope: "global" });
+
+    // The reset happens in a different process from the trigger (e.g. from a
+    // lifecycle hook), so the catalog no longer knows the key.
+    resetIdempotencyKeyCatalog();
+
+    expect(await resetAndCaptureKey("my-task", digestShapedKey, { scope: "global" })).toBe(created);
+  });
+
+  it("hashes 64-character key material for run scope when an explicit scope is passed", async () => {
+    const parentRunId = "run_abc123";
+    const expected = await digestSHA256(`${digestShapedKey}-${parentRunId}`);
+
+    expect(
+      await resetAndCaptureKey("my-task", digestShapedKey, { scope: "run", parentRunId })
+    ).toBe(expected);
+  });
+
+  it("sends a key created with idempotencyKeys.create() unchanged", async () => {
+    const created = await createIdempotencyKey("my-key", { scope: "global" });
+
+    expect(await resetAndCaptureKey("my-task", created)).toBe(created);
+    // An explicit scope must not hash an already-created key a second time.
+    expect(await resetAndCaptureKey("my-task", created, { scope: "global" })).toBe(created);
+  });
+
+  it("sends a 64-character key unchanged when no scope is passed", async () => {
+    // Passing 64-character material straight to `trigger()` stores it un-hashed, so
+    // resetting it without a scope must keep sending it verbatim.
+    expect(await resetAndCaptureKey("my-task", digestShapedKey)).toBe(digestShapedKey);
+  });
+
+  it("hashes key material that is not 64 characters", async () => {
+    const created = await createIdempotencyKey("my-key", { scope: "global" });
+    resetIdempotencyKeyCatalog();
+
+    expect(await resetAndCaptureKey("my-task", "my-key", { scope: "global" })).toBe(created);
+  });
+});

packages/core/src/v3/idempotencyKeys.ts

@@ -234,19 +234,28 @@ export async function resetIdempotencyKey(
 ): Promise<{ id: string }> {
   const client = apiClientManager.clientOrThrow();
 
-  // If the key is already a 64-char hash, use it directly
+  // A 64-character string is ambiguous: it can be a hash returned by
+  // `idempotencyKeys.create()`, or it can be the caller's own key material (using
+  // a digest of some identity as the key is common). Send it through untouched
+  // only when we have evidence it is already a hash:
+  //
+  //   - the catalog recognises it, so it came from `idempotencyKeys.create()`, or
+  //   - no `scope` was passed, so there is nothing to derive a hash from and the
+  //     length is the only signal available.
+  //
+  // An explicit `scope` is an explicit request to derive the hash, so we never
+  // short-circuit past it. Previously any 64-character key material was assumed to
+  // be pre-hashed and sent as-is, which matched no run.
   if (typeof idempotencyKey === "string" && idempotencyKey.length === 64) {
-    return client.resetIdempotencyKey(taskIdentifier, idempotencyKey, requestOptions);
-  }
+    const isCreatedKey = getIdempotencyKeyOptions(idempotencyKey) !== undefined;
 
-  // Try to extract options from an IdempotencyKey created with idempotencyKeys.create()
-  const attachedOptions =
-    typeof idempotencyKey === "string" ? getIdempotencyKeyOptions(idempotencyKey) : undefined;
+    if (isCreatedKey || options?.scope === undefined) {
+      return client.resetIdempotencyKey(taskIdentifier, idempotencyKey, requestOptions);
+    }
+  }
 
-  const scope = attachedOptions?.scope ?? options?.scope ?? "run";
-  const keyArray = Array.isArray(idempotencyKey)
-    ? idempotencyKey
-    : [attachedOptions?.key ?? String(idempotencyKey)];
+  const scope = options?.scope ?? "run";
+  const keyArray = Array.isArray(idempotencyKey) ? idempotencyKey : [idempotencyKey];
 
   // Build scope suffix based on scope type
   let scopeSuffix: string[] = [];