npm - @cosmicdrift/kumiko-framework - Versions diffs - 0.200.0 → 0.201.0 - Mend

@cosmicdrift/kumiko-framework 0.200.0 → 0.201.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/package.json +3 -3
package/src/__tests__/entity-list-limits.integration.test.ts +84 -0
package/src/api/__tests__/api.test.ts +116 -1
package/src/api/__tests__/batch.integration.test.ts +53 -0
package/src/api/__tests__/body-limit.test.ts +16 -0
package/src/api/route-registrars.ts +4 -3
package/src/api/routes.ts +47 -1
package/src/db/__tests__/unchecked-system-db.test.ts +66 -0
package/src/db/tenant-db.ts +46 -2
package/src/engine/entity-handlers.ts +8 -1
package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/constants.ts +2 -0
package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/feature.ts +8 -0
package/src/engine/feature-ast/__tests__/patch.test.ts +98 -0
package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts +155 -0
package/src/engine/feature-ast/extractors/events.ts +5 -3
package/src/engine/feature-ast/extractors/round3.ts +5 -3
package/src/engine/feature-ast/extractors/round5.ts +5 -4
package/src/engine/feature-ast/extractors/shared.ts +29 -4
package/src/engine/feature-ast/patch.ts +28 -21
package/src/engine/feature-ast/patterns.ts +18 -0
package/src/engine/feature-ast/render.ts +19 -6
package/src/engine/index.ts +1 -0
package/src/files/__tests__/files.integration.test.ts +97 -1
package/src/files/file-routes.ts +10 -2
package/src/files/types.ts +72 -0
package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts +44 -8
package/src/pipeline/__tests__/dispatcher.test.ts +23 -4
package/src/pipeline/__tests__/redis-pipeline.integration.test.ts +116 -22
package/src/pipeline/dispatch-batch.ts +11 -5
package/src/pipeline/dispatch-shared.ts +42 -16
package/src/pipeline/idempotency.ts +91 -30

package/src/files/__tests__/files.integration.test.ts CHANGED Viewed

@@ -33,7 +33,7 @@ import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider } from "../types";
-import { parseMaxSize, validateFile } from "../types";
+import { parseMaxSize, sniffMimeType, validateFile } from "../types";
 // UUID for "this row doesn't exist" assertions. Valid v4 format so PG accepts
 // the query — the row just isn't there. Pre-v1 files-feature tests used
@@ -199,6 +199,28 @@ describe("file validation", () => {
       validateFile({ fileName: "a.jpg", mimeType: "image/jpg", size: 100 }, { accept: ["jpg"] }),
     ).toBeNull();
   });
+  test("sniffMimeType recognizes gif, webp and pdf signatures", () => {
+    expect(sniffMimeType(new TextEncoder().encode("GIF89a" + "x".repeat(20)))).toBe("image/gif");
+    const webp = new Uint8Array([
+      ...new TextEncoder().encode("RIFF"),
+      0,
+      0,
+      0,
+      0,
+      ...new TextEncoder().encode("WEBP"),
+      ...Array(20).fill(0),
+    ]);
+    expect(sniffMimeType(webp)).toBe("image/webp");
+    expect(sniffMimeType(new TextEncoder().encode("%PDF-1.4" + "x".repeat(20)))).toBe(
+      "application/pdf",
+    );
+  });
+  test("sniffMimeType returns null for unrecognized or too-short byte sequences", () => {
+    expect(sniffMimeType(new Uint8Array([0x00, 0x01, 0x02]))).toBeNull();
+    expect(sniffMimeType(new TextEncoder().encode("hello world"))).toBeNull();
+  });
 });
 // --- Integration: Upload → Download → Delete via real HTTP API ---
@@ -312,6 +334,80 @@ describe("file upload flow via API", () => {
   });
 });
+// --- Serving hardens Content-Type against a spoofed/mismatched declared MIME ---
+describe("download Content-Type is sniffed from bytes, not trusted from the declared MIME", () => {
+  const testPngContent = new Uint8Array([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    ...Array(50).fill(0),
+  ]);
+  const testJpegContent = new Uint8Array([0xff, 0xd8, 0xff, 0xe0, ...Array(50).fill(0)]);
+  test("real PNG bytes declared as text/html are served as octet-stream, never text/html", async () => {
+    // Bun's own Request#formData() derives File#type from the *filename*
+    // extension, not from the multipart part's declared Content-Type header
+    // — so the fileName here (.html) is what actually lands as the stored
+    // mimeType; the mismatch this test needs is against the real PNG bytes.
+    const uploadRes = await uploadFile(adminUser, "sneaky.html", testPngContent, "text/html");
+    // Upload itself is not rejected — mismatch enforcement stays at the
+    // serving side, existing uploads with an off mimeType keep working.
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("application/octet-stream");
+    expect(res.headers.get("Content-Disposition")).toContain("attachment");
+  });
+  test("actual HTML bytes are never served as text/html or image/svg+xml", async () => {
+    const htmlBytes = new TextEncoder().encode(
+      "<html><body><script>alert(document.domain)</script></body></html>",
+    );
+    const uploadRes = await uploadFile(adminUser, "evil.html", htmlBytes, "text/html");
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).not.toBe("text/html");
+    expect(res.headers.get("Content-Type")).not.toBe("image/svg+xml");
+    expect(res.headers.get("Content-Type")).toBe("application/octet-stream");
+    expect(res.headers.get("Content-Disposition")).toContain("attachment");
+  });
+  test("an SVG upload — bytes and declared MIME both image/svg+xml — is still downgraded to octet-stream, never served inline", async () => {
+    const svgBytes = new TextEncoder().encode(
+      '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>',
+    );
+    const uploadRes = await uploadFile(adminUser, "logo.svg", svgBytes, "image/svg+xml");
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).not.toBe("image/svg+xml");
+    expect(res.headers.get("Content-Type")).toBe("application/octet-stream");
+  });
+  test("regression: a real allowed image type with a correctly declared MIME still serves with the matching sniffed Content-Type", async () => {
+    const uploadRes = await uploadFile(adminUser, "photo.jpg", testJpegContent, "image/jpeg");
+    expect(uploadRes.status).toBe(201);
+    const { id } = await uploadRes.json();
+    const res = await getFile(adminUser, id);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/jpeg");
+  });
+});
 // --- Cross-user access within a tenant (attached file owner-scope) ---
 describe("attached file owner-scope", () => {

package/src/files/file-routes.ts CHANGED Viewed

@@ -18,7 +18,7 @@ import { createFileContext } from "./file-handle";
 import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
-import { buildStorageKey, validateFile } from "./types";
+import { buildStorageKey, resolveServedContentType, validateFile } from "./types";
 // Decision returned by a FileAccessGuard — distinct from boolean so callers
 // can't accidentally negate or default it.
@@ -234,11 +234,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const storageProvider = await options.resolveProvider(user.tenantId);
     const data = await storageProvider.read(fileRef.storageKey);
+    // The stored mimeType is client-declared (file.type off the upload) and
+    // never verified against the bytes — serving it as-is would let a
+    // client label real HTML/SVG as e.g. image/png to slip active content
+    // out under a trusted-looking Content-Type. Sniff the actual bytes
+    // instead; anything that isn't a known-safe binary signature (including
+    // svg/html, which have none) goes out as application/octet-stream.
+    const contentType = resolveServedContentType(data, fileRef.mimeType);
     return new Response(Buffer.from(data), {
       headers: {
-        "Content-Type": fileRef.mimeType,
+        "Content-Type": contentType,
         "Content-Disposition": buildContentDispositionHeader(fileRef.fileName),
         "Content-Length": String(fileRef.size),
+        "X-Content-Type-Options": "nosniff",
       },
     });
   });

package/src/files/types.ts CHANGED Viewed

@@ -52,6 +52,78 @@ const EXTENSION_MIME_WHITELIST: Record<string, readonly string[]> = {
   md: ["text/markdown", "text/plain"],
 } satisfies Record<string, readonly string[]>;
+// Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
+// a reliable binary signature. Used at SERVE time — never trust the stored/
+// client-declared mimeType for Content-Type on its own, sniff the actual
+// bytes instead. Types without a stable signature (svg, txt, csv, json, md)
+// and anything that matches none of these fall back to
+// application/octet-stream in resolveServedContentType below — this also
+// guarantees text/html and image/svg+xml are never served inline, even for
+// an honestly-declared upload.
+const MAGIC_BYTE_SIGNATURES: ReadonlyArray<{
+  readonly mimeType: string;
+  readonly matches: (bytes: Uint8Array) => boolean;
+}> = [
+  {
+    mimeType: "image/png",
+    matches: (bytes) => startsWithBytes(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  },
+  { mimeType: "image/jpeg", matches: (bytes) => startsWithBytes(bytes, [0xff, 0xd8, 0xff]) },
+  {
+    mimeType: "image/gif",
+    matches: (bytes) => startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a"),
+  },
+  {
+    mimeType: "image/webp",
+    matches: (bytes) => startsWithAscii(bytes, "RIFF") && startsWithAscii(bytes, "WEBP", 8),
+  },
+  { mimeType: "application/pdf", matches: (bytes) => startsWithAscii(bytes, "%PDF-") },
+];
+function startsWithBytes(bytes: Uint8Array, signature: readonly number[]): boolean {
+  if (bytes.length < signature.length) return false;
+  return signature.every((byte, i) => bytes[i] === byte);
+}
+function startsWithAscii(bytes: Uint8Array, ascii: string, offset = 0): boolean {
+  if (bytes.length < offset + ascii.length) return false;
+  for (let i = 0; i < ascii.length; i++) {
+    if (bytes[offset + i] !== ascii.charCodeAt(i)) return false;
+  }
+  return true;
+}
+export function sniffMimeType(bytes: Uint8Array): string | null {
+  for (const signature of MAGIC_BYTE_SIGNATURES) {
+    if (signature.matches(bytes)) return signature.mimeType;
+  }
+  return null;
+}
+// image/jpg is not a registered IANA type but EXTENSION_MIME_WHITELIST above
+// accepts it as a jpg alias — sniffMimeType only ever returns the canonical
+// image/jpeg, so without this a legitimately-declared "image/jpg" upload
+// would mismatch its own sniffed type and get needlessly downgraded.
+const DECLARED_MIME_ALIASES: Readonly<Record<string, string>> = {
+  "image/jpg": "image/jpeg",
+};
+// The Content-Type a served file's bytes are safe to go out with. Bytes that
+// don't sniff as one of the known-safe binary signatures (including
+// svg/html/text formats, which have no reliable magic bytes) always
+// downgrade to application/octet-stream. Bytes that DO sniff safely still
+// downgrade unless the sniffed type matches what was declared at upload —
+// a mismatch (e.g. real PNG bytes uploaded as "text/html") is itself a
+// spoofing signal and is never trusted enough to pick a Content-Type from,
+// even one that would otherwise be harmless.
+export function resolveServedContentType(bytes: Uint8Array, declaredMimeType: string): string {
+  const sniffed = sniffMimeType(bytes);
+  if (!sniffed) return "application/octet-stream";
+  const normalizedDeclared = declaredMimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+  const declared = DECLARED_MIME_ALIASES[normalizedDeclared] ?? normalizedDeclared;
+  return sniffed === declared ? sniffed : "application/octet-stream";
+}
 export function validateFile(
   metadata: FileMetadata,
   options: FileValidationOptions,

package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts CHANGED Viewed

@@ -14,7 +14,14 @@ const systemScopedFeature = defineFeature("ctxsystemdb-system", (r) => {
     z.object({}),
     async (query, ctx) => {
       if (!ctx.systemDb)
-        return { present: false as const, tenantIdMatches: false, dbThrows: false };
+        return {
+          present: false as const,
+          tenantIdMatches: false,
+          dbThrows: false,
+          dbOutsideTransactionPresent: false,
+          dbOutsideTransactionThrows: false,
+          outsideTransactionTenantIdMatches: false,
+        };
       // ctx.db is fail-closed for r.systemScope() handlers — dispatch-shared.ts
       // builds `as HandlerContext`, so a mis-wired property wouldn't be caught
       // by tsc. Prove it at runtime: assertTenantMatch must hand back a
@@ -27,10 +34,31 @@ const systemScopedFeature = defineFeature("ctxsystemdb-system", (r) => {
       } catch {
         dbThrows = true;
       }
+      // Same fail-closed proof for ctx.dbOutsideTransaction — the second,
+      // previously-unguarded door #2118 closes. Its guarded escape hatch is
+      // ctx.systemDb.outsideTransaction, not ctx.systemDb itself. The guard
+      // is a Proxy (truthy), so `?.` here would mask the two regressions
+      // this test needs to tell apart: "field silently undefined" vs. "field
+      // holds a working, unfiltered db" both look identical under `?.`.
+      // Check presence without touching a proxy property (`!==` on the field
+      // itself doesn't trap), then force the property read separately.
+      const dbOutsideTransactionPresent = ctx.dbOutsideTransaction !== undefined;
+      let dbOutsideTransactionThrows = false;
+      try {
+        void ctx.dbOutsideTransaction!.tenantId;
+      } catch {
+        dbOutsideTransactionThrows = true;
+      }
+      const checkedOutsideTx = ctx.systemDb.outsideTransaction.assertTenantMatch(
+        query.user.tenantId,
+      );
       return {
         present: true as const,
         tenantIdMatches: checked.tenantId === query.user.tenantId,
         dbThrows,
+        dbOutsideTransactionPresent,
+        dbOutsideTransactionThrows,
+        outsideTransactionTenantIdMatches: checkedOutsideTx.tenantId === query.user.tenantId,
       };
     },
     { access: { roles: ["Admin"] } },
@@ -44,6 +72,7 @@ const tenantScopedFeature = defineFeature("ctxsystemdb-tenant", (r) => {
     async (query, ctx) => ({
       present: ctx.systemDb !== undefined,
       dbWorks: ctx.db.tenantId === query.user.tenantId,
+      dbOutsideTransactionWorks: ctx.dbOutsideTransaction?.tenantId === query.user.tenantId,
     }),
     { access: { roles: ["Admin"] } },
   );
@@ -61,24 +90,31 @@ afterAll(async () => {
 });
 describe("ctx.systemDb", () => {
-  test("is present for r.systemScope() handlers; ctx.db is fail-closed there", async () => {
+  test("is present for r.systemScope() handlers; ctx.db and ctx.dbOutsideTransaction are both fail-closed there", async () => {
     const result = await stack.http.queryOk<{
       present: boolean;
       tenantIdMatches: boolean;
       dbThrows: boolean;
+      dbOutsideTransactionPresent: boolean;
+      dbOutsideTransactionThrows: boolean;
+      outsideTransactionTenantIdMatches: boolean;
     }>("ctxsystemdb-system:query:check", {}, admin);
     expect(result.present).toBe(true);
     expect(result.tenantIdMatches).toBe(true);
     expect(result.dbThrows).toBe(true);
+    expect(result.dbOutsideTransactionPresent).toBe(true);
+    expect(result.dbOutsideTransactionThrows).toBe(true);
+    expect(result.outsideTransactionTenantIdMatches).toBe(true);
   });
-  test("is absent for non-system-scoped handlers; ctx.db works normally there", async () => {
-    const result = await stack.http.queryOk<{ present: boolean; dbWorks: boolean }>(
-      "ctxsystemdb-tenant:query:check",
-      {},
-      admin,
-    );
+  test("is absent for non-system-scoped handlers; ctx.db and ctx.dbOutsideTransaction work normally there", async () => {
+    const result = await stack.http.queryOk<{
+      present: boolean;
+      dbWorks: boolean;
+      dbOutsideTransactionWorks: boolean;
+    }>("ctxsystemdb-tenant:query:check", {}, admin);
     expect(result.present).toBe(false);
     expect(result.dbWorks).toBe(true);
+    expect(result.dbOutsideTransactionWorks).toBe(true);
   });
 });

package/src/pipeline/__tests__/dispatcher.test.ts CHANGED Viewed

@@ -1019,13 +1019,32 @@ describe("dispatcher context.geoTzProvider (680/1)", () => {
 // --- Mock helpers ---
 function createMockIdempotencyGuard() {
-  const cache = new Map<string, string>();
+  const results = new Map<string, string>();
+  const pendingTokens = new Map<string, string>();
+  let nextToken = 0;
   return {
     async check(tenantId: string, userId: string, requestId: string) {
-      return cache.get(`${tenantId}:${userId}:${requestId}`) ?? null;
+      const key = `${tenantId}:${userId}:${requestId}`;
+      const cached = results.get(key);
+      if (cached !== undefined) return { status: "cached" as const, result: cached };
+      const token = `token-${nextToken++}`;
+      pendingTokens.set(key, token);
+      return { status: "acquired" as const, token };
     },
-    async store(tenantId: string, userId: string, requestId: string, result: unknown) {
-      cache.set(`${tenantId}:${userId}:${requestId}`, JSON.stringify(result));
+    async store(
+      tenantId: string,
+      userId: string,
+      requestId: string,
+      token: string,
+      result: unknown,
+    ) {
+      const key = `${tenantId}:${userId}:${requestId}`;
+      // Mirrors the real guard's CAS: only persist if we still hold the token
+      // this run acquired.
+      if (pendingTokens.get(key) !== token) return;
+      pendingTokens.delete(key);
+      results.set(key, JSON.stringify(result));
     },
   };
 }

package/src/pipeline/__tests__/redis-pipeline.integration.test.ts CHANGED Viewed

@@ -22,37 +22,44 @@ describe("idempotency guard", () => {
   const tenantA = "00000000-0000-4000-8000-00000000000a";
   const userA = "00000000-0000-4000-8000-0000000000a1";
-  test("returns null for new request", async () => {
+  test("returns acquired for new request", async () => {
     const guard = createIdempotencyGuard(testRedis.redis);
     const result = await guard.check(tenantA, userA, "req-new-123");
-    expect(result).toBeNull();
+    expect(result.status).toBe("acquired");
   });
   test("returns cached result for duplicate request", async () => {
     const guard = createIdempotencyGuard(testRedis.redis);
     const requestId = "req-dup-456";
-    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { id: 1 } });
+    const acquired = await guard.check(tenantA, userA, requestId);
+    if (acquired.status !== "acquired") throw new Error("expected to acquire the lock");
+    await guard.store(tenantA, userA, requestId, acquired.token, {
+      isSuccess: true,
+      data: { id: 1 },
+    });
     const cached = await guard.check(tenantA, userA, requestId);
-    expect(cached).not.toBeNull();
-    if (!cached) throw new Error("expected cached value");
-    expect(JSON.parse(cached)).toEqual({ isSuccess: true, data: { id: 1 } });
+    expect(cached.status).toBe("cached");
+    if (cached.status !== "cached") throw new Error("expected cached value");
+    expect(JSON.parse(cached.result)).toEqual({ isSuccess: true, data: { id: 1 } });
   });
   test("expires after TTL", async () => {
     const guard = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 1 });
     const requestId = "req-ttl-789";
-    await guard.store(tenantA, userA, requestId, { done: true });
+    const acquired = await guard.check(tenantA, userA, requestId);
+    if (acquired.status !== "acquired") throw new Error("expected to acquire the lock");
+    await guard.store(tenantA, userA, requestId, acquired.token, { done: true });
     // Should exist immediately
-    expect(await guard.check(tenantA, userA, requestId)).not.toBeNull();
+    expect((await guard.check(tenantA, userA, requestId)).status).toBe("cached");
     // Wait for expiry
     await new Promise((r) => setTimeout(r, 1100));
-    expect(await guard.check(tenantA, userA, requestId)).toBeNull();
+    expect((await guard.check(tenantA, userA, requestId)).status).toBe("acquired");
   });
   test("parallel check(): second caller waits for the first's store() instead of racing", async () => {
@@ -65,7 +72,8 @@ describe("idempotency guard", () => {
     // Request #1 starts — claims the in-progress lock.
     const first = await guard.check(tenantA, userA, requestId);
-    expect(first).toBeNull(); // got the lock
+    expect(first.status).toBe("acquired");
+    if (first.status !== "acquired") throw new Error("expected to acquire the lock");
     // Request #2 runs concurrently — must block until #1 stores a result.
     const secondPromise = guard.check(tenantA, userA, requestId);
@@ -80,12 +88,17 @@ describe("idempotency guard", () => {
     expect(quickResult.done).toBe(false);
     // Request #1 finishes.
-    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { id: 99 } });
+    await guard.store(tenantA, userA, requestId, first.token, {
+      isSuccess: true,
+      data: { id: 99 },
+    });
-    // Request #2 should now see the stored result, not null — no duplicate work.
+    // Request #2 should now see the stored result, not a fresh acquisition —
+    // no duplicate work.
     const second = await secondPromise;
-    expect(second).not.toBeNull();
-    expect(JSON.parse(second as string)).toEqual({ isSuccess: true, data: { id: 99 } });
+    expect(second.status).toBe("cached");
+    if (second.status !== "cached") throw new Error("expected cached value");
+    expect(JSON.parse(second.result)).toEqual({ isSuccess: true, data: { id: 99 } });
   });
   test("crashed handler: pending marker expires, next caller reclaims the lock", async () => {
@@ -97,11 +110,11 @@ describe("idempotency guard", () => {
     const requestId = "req-crashed";
     const first = await guard.check(tenantA, userA, requestId);
-    expect(first).toBeNull(); // we acquired the lock, then "crash" — never call store()
+    expect(first.status).toBe("acquired"); // we acquired the lock, then "crash" — never call store()
     // After the pending-TTL lapses, a retry should be allowed to take over.
     const second = await guard.check(tenantA, userA, requestId);
-    expect(second).toBeNull(); // reclaimed
+    expect(second.status).toBe("acquired"); // reclaimed
   });
   test("same requestId from different tenant/user does not hit the same cache entry", async () => {
@@ -112,22 +125,103 @@ describe("idempotency guard", () => {
     // Tenant A / user A owns the request and stores its result.
     const firstCheck = await guard.check(tenantA, userA, requestId);
-    expect(firstCheck).toBeNull();
-    await guard.store(tenantA, userA, requestId, { isSuccess: true, data: { tenant: "A" } });
+    expect(firstCheck.status).toBe("acquired");
+    if (firstCheck.status !== "acquired") throw new Error("expected to acquire the lock");
+    await guard.store(tenantA, userA, requestId, firstCheck.token, {
+      isSuccess: true,
+      data: { tenant: "A" },
+    });
     // Same requestId, different tenant+user: must be treated as a fresh
     // request, not see tenant A's cached/pending state.
     const otherTenantCheck = await guard.check(tenantB, userB, requestId);
-    expect(otherTenantCheck).toBeNull();
+    expect(otherTenantCheck.status).toBe("acquired");
     // Different user, same tenant: also isolated.
     const otherUserCheck = await guard.check(tenantA, userB, requestId);
-    expect(otherUserCheck).toBeNull();
+    expect(otherUserCheck.status).toBe("acquired");
     // Tenant A's own result is still retrievable and unaffected.
     const ownResult = await guard.check(tenantA, userA, requestId);
-    expect(ownResult).not.toBeNull();
-    expect(JSON.parse(ownResult as string)).toEqual({ isSuccess: true, data: { tenant: "A" } });
+    expect(ownResult.status).toBe("cached");
+    if (ownResult.status !== "cached") throw new Error("expected cached value");
+    expect(JSON.parse(ownResult.result)).toEqual({ isSuccess: true, data: { tenant: "A" } });
+  });
+  test("bug 1 — wait shorter than the pending lock no longer forces a duplicate re-run", async () => {
+    // Same inverted ratio as the pre-fix defaults (waitTimeoutMs < pendingTtl),
+    // scaled to sub-second so the test stays fast. Pre-fix, the internal
+    // waitTimeoutMs was trusted as-is: the waiter gives up at 100ms and
+    // reports "acquired" even though request #1 is still legitimately
+    // running and stores its result 200ms later — the double-execute bug.
+    // Post-fix, waitTimeoutMs is clamped to stay above pendingTtl, so the
+    // waiter keeps polling and observes the real result instead.
+    const guard = createIdempotencyGuard(testRedis.redis, {
+      pendingTtlSeconds: 1,
+      waitTimeoutMs: 100,
+      pollIntervalMs: 20,
+    });
+    const requestId = "req-bug1-inverted-timeout";
+    const first = await guard.check(tenantA, userA, requestId);
+    expect(first.status).toBe("acquired");
+    if (first.status !== "acquired") throw new Error("expected to acquire the lock");
+    // Request #1 is "slow" — stores well after the old 100ms wait window,
+    // but well within pendingTtl (1s).
+    const storeAfterDelay = (async () => {
+      await new Promise((r) => setTimeout(r, 300));
+      await guard.store(tenantA, userA, requestId, first.token, {
+        isSuccess: true,
+        data: { id: "slow-handler" },
+      });
+    })();
+    const second = await guard.check(tenantA, userA, requestId);
+    await storeAfterDelay;
+    // Must observe request #1's real result — never a second "acquired".
+    expect(second.status).toBe("cached");
+    if (second.status !== "cached") throw new Error("expected cached value, not a re-run");
+    expect(JSON.parse(second.result)).toEqual({ isSuccess: true, data: { id: "slow-handler" } });
+  });
+  test("bug 2 (window B) — a reclaimed lock's fresh result survives the original owner's stale store()", async () => {
+    const guard = createIdempotencyGuard(testRedis.redis, {
+      pendingTtlSeconds: 1, // expire fast so we can force a reclaim quickly
+      waitTimeoutMs: 6_000,
+      pollIntervalMs: 20,
+    });
+    const requestId = "req-bug2-window-b";
+    // Original owner acquires, then "hangs" (never stores) past pendingTtl.
+    const original = await guard.check(tenantA, userA, requestId);
+    expect(original.status).toBe("acquired");
+    if (original.status !== "acquired") throw new Error("expected to acquire the lock");
+    // Let the lock expire, then a second run reclaims it and finishes fast.
+    await new Promise((r) => setTimeout(r, 1100));
+    const reclaimer = await guard.check(tenantA, userA, requestId);
+    expect(reclaimer.status).toBe("acquired");
+    if (reclaimer.status !== "acquired") throw new Error("expected to reclaim the lock");
+    await guard.store(tenantA, userA, requestId, reclaimer.token, {
+      isSuccess: true,
+      data: { owner: "reclaimer" },
+    });
+    // The original (now-stale) run finally "finishes" and tries to store its
+    // own, outdated result using its original token.
+    await guard.store(tenantA, userA, requestId, original.token, {
+      isSuccess: true,
+      data: { owner: "original-stale" },
+    });
+    // The reclaimer's fresh result must survive — the stale store() must be
+    // a no-op, not a silent overwrite.
+    const final = await guard.check(tenantA, userA, requestId);
+    expect(final.status).toBe("cached");
+    if (final.status !== "cached") throw new Error("expected cached value");
+    expect(JSON.parse(final.result)).toEqual({ isSuccess: true, data: { owner: "reclaimer" } });
   });
 });

package/src/pipeline/dispatch-batch.ts CHANGED Viewed

@@ -29,20 +29,26 @@ export async function runBatch(
   // Idempotency: if the same requestId has already been processed, return the
   // cached result without re-executing. The cache holds the full BatchResult.
+  // idempotencyToken is only set when we actually acquired the lock — the
+  // corrupted-cache fallthrough below leaves it unset, so finalize() skips
+  // store() rather than writing over an entry it never owned.
+  let idempotencyToken: string | undefined;
   if (requestId && idempotency) {
-    const cached = await idempotency.check(user.tenantId, user.id, requestId);
-    if (cached) {
-      const parsed = parseJsonSafe<BatchResult | null>(cached, null);
+    const checked = await idempotency.check(user.tenantId, user.id, requestId);
+    if (checked.status === "cached") {
+      const parsed = parseJsonSafe<BatchResult | null>(checked.result, null);
       if (parsed) return parsed;
       // corrupted cache entry — treat as miss, let the request re-run
+    } else {
+      idempotencyToken = checked.token;
     }
   }
   // Wrap return paths: cache the final result under requestId so retries get
   // the same answer (both success and failure results are cached).
   const finalize = async (result: BatchResult): Promise<BatchResult> => {
-    if (requestId && idempotency) {
-      await idempotency.store(user.tenantId, user.id, requestId, result);
+    if (requestId && idempotency && idempotencyToken) {
+      await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
     }
     return result;
   };