@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.287.0

package/src/file-derivatives/feature.ts

@@ -9,6 +9,7 @@
 import { cachedResponse, computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
 import {
   defineFeature,
+  EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
   type FeatureDefinition,
@@ -78,7 +79,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
 
   return defineFeature(FEATURE_NAME, (r) => {
     r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it.",
+      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -108,6 +109,13 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
         // entityType.
       },
     });
+    r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
+      onRegister: () => {
+        // No side-effects at register-time — resolution happens in
+        // variant(), keyed by the FileRef's entityType, before the spec
+        // hash is computed.
+      },
+    });
 
     // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
     // registers publicVariantQuery into the feature's dispatch table as a

package/src/shared/__tests__/row-bound-grant.integration.test.ts

@@ -0,0 +1,184 @@
+// Row-bound grants end-to-end over real /api/write calls without a session:
+// the shape a consumer builds on (anonymous caller created a row, now performs
+// exactly one narrow further write on it). The unit tests fake the anchor
+// store; this one uses a real conditional UPDATE against Postgres, which is
+// the only way to show that `commitAnchor` can actually be atomic and that two
+// simultaneous redemptions of the same grant leave exactly one winner.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { executeRawQuery } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { setupTestStack, type TestStack, testTenantId } from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { redeemRowBoundGrant, signRowBoundGrant } from "../row-bound-grant";
+
+const TABLE = "row_bound_grant_demo";
+const SECRET = "row-bound-grant-integration-secret";
+const PURPOSE = "demo-enrich";
+const ENRICH = "grantdemo:write:enrich";
+const ROW_ID = "11111111-1111-4111-8111-111111111111";
+const ANCHOR = "22222222-2222-4222-8222-222222222222";
+
+// Two /api/write calls fired together still run to completion one after the
+// other, so a plain Promise.all would never open the window a conditional
+// UPDATE exists for. This holds every redeemer between reading the anchor and
+// spending it until `expected` of them have read it — the interleaving itself,
+// deterministic instead of a sleep. The timeout keeps a serialising stack from
+// hanging the suite: it fails the assertion instead.
+function createRaceGate(expected: number, timeoutMs = 2_000) {
+  let arrived = 0;
+  let open: () => void = () => {};
+  const opened = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  return {
+    async wait(): Promise<void> {
+      arrived += 1;
+      if (arrived >= expected) open();
+      await Promise.race([opened, Bun.sleep(timeoutMs)]);
+    },
+  };
+}
+
+let raceGate: { wait: () => Promise<void> } | null = null;
+
+const RAW_REASON =
+  "the grant holder has no session, so the anchor spend is a conditional UPDATE " +
+  "outside the entity write map";
+
+const grantDemoFeature = defineFeature("grantdemo", (r) => {
+  r.writeHandler(
+    "enrich",
+    z.object({ token: z.string().min(1), note: z.string().min(1) }),
+    async (event, ctx) => {
+      const db = ctx.db.unsafeRaw(RAW_REASON);
+      const redeemed = await redeemRowBoundGrant({
+        token: event.payload.token,
+        purpose: PURPOSE,
+        secret: SECRET,
+        loadAnchor: async (subject) => {
+          const rows = await executeRawQuery<{ anchor: string | null }>(
+            db,
+            `SELECT anchor FROM ${TABLE} WHERE id = $1`,
+            [subject],
+          );
+          await raceGate?.wait();
+          return rows[0]?.anchor ?? null;
+        },
+        commitAnchor: async (subject, expected) => {
+          const rows = await executeRawQuery<{ id: string }>(
+            db,
+            `UPDATE ${TABLE} SET anchor = NULL, note = $3 WHERE id = $1 AND anchor = $2 RETURNING id`,
+            [subject, expected, event.payload.note],
+          );
+          return rows.length === 1;
+        },
+      });
+      if (!redeemed.ok) return writeFailure(new UnprocessableError("invalid_or_expired_grant"));
+      return { isSuccess: true as const, data: { id: redeemed.subject } };
+    },
+    {
+      access: { roles: ["anonymous"] },
+      escapeHatch: {
+        reason:
+          "the row is written by an anonymous grant holder through raw SQL, so the write " +
+          "cannot go through the entity write map of a tenant-scoped user",
+      },
+    },
+  );
+});
+
+let stack: TestStack;
+
+function grantFor(anchor: string): string {
+  return signRowBoundGrant({
+    subject: ROW_ID,
+    purpose: PURPOSE,
+    anchor,
+    ttlMinutes: 30,
+    secret: SECRET,
+  }).token;
+}
+
+function enrich(token: string, note: string) {
+  return stack.http.raw("POST", "/api/write", { type: ENRICH, payload: { token, note } });
+}
+
+async function readRow(): Promise<{ anchor: string | null; note: string | null } | undefined> {
+  const rows = await executeRawQuery<{ anchor: string | null; note: string | null }>(
+    stack.db,
+    `SELECT anchor, note FROM ${TABLE} WHERE id = $1`,
+    [ROW_ID],
+  );
+  return rows[0];
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [grantDemoFeature],
+    anonymousAccess: { defaultTenantId: testTenantId(1) },
+  });
+  await executeRawQuery(
+    stack.db,
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (id uuid PRIMARY KEY, anchor uuid, note text)`,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  raceGate = null;
+  await executeRawQuery(stack.db, `DELETE FROM ${TABLE}`);
+  await executeRawQuery(stack.db, `INSERT INTO ${TABLE} (id, anchor, note) VALUES ($1, $2, NULL)`, [
+    ROW_ID,
+    ANCHOR,
+  ]);
+});
+
+describe("row-bound grant over anonymous HTTP", () => {
+  test("a valid grant performs the one write and spends the anchor", async () => {
+    const res = await enrich(grantFor(ANCHOR), "first");
+
+    expect(res.status).toBe(200);
+    expect(await readRow()).toEqual({ anchor: null, note: "first" });
+  });
+
+  test("replaying the same grant fails and leaves the row alone", async () => {
+    const token = grantFor(ANCHOR);
+    expect((await enrich(token, "first")).status).toBe(200);
+
+    const replay = await enrich(token, "second");
+
+    expect(replay.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: null, note: "first" });
+  });
+
+  test("two simultaneous redemptions of one grant leave exactly one winner", async () => {
+    const token = grantFor(ANCHOR);
+    raceGate = createRaceGate(2);
+
+    const results = await Promise.all([enrich(token, "a"), enrich(token, "b")]);
+
+    expect(results.map((r) => r.status).sort()).toEqual([200, 422]);
+    const row = await readRow();
+    expect(row?.anchor).toBeNull();
+    expect(["a", "b"]).toContain(row?.note ?? "");
+  });
+
+  test("a grant for a superseded anchor fails without spending the live one", async () => {
+    const res = await enrich(grantFor("33333333-3333-4333-8333-333333333333"), "stale");
+
+    expect(res.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: ANCHOR, note: null });
+  });
+
+  test("a garbage token is a 422, not a 500 from the row lookup", async () => {
+    const res = await enrich("not.a.token", "junk");
+
+    expect(res.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: ANCHOR, note: null });
+  });
+});

package/src/shared/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "row-bound grants: one short-lived, single-use capability for anonymous writes on one row",
+    "detail": "`signed-token.ts` moves from `auth-email-password/` to `shared/` — the mechanism\nwas never email/password specific (user-data-rights already used it). The old\npath re-exports it, so no importer breaks. New subpaths:\n`./shared/signed-token` and `./shared/row-bound-grant`.\n`shared/row-bound-grant.ts` is the new piece. It folds the row's *current*\nanchor (a request id, a status, a version — anything that moves on when the row\nis consumed) into the HMAC purpose on both mint and redeem, so a replayed token\nstops working the moment the row moves on. Single-use semantics without a burn\nkey and without Redis. Minting and redeeming share one purpose-building\nfunction, because an unanchored purpose silently degrades into a bearer token\nvalid for the whole TTL.\nAnchoring alone only closes the replay window once the row has moved on, so\nspending the anchor is part of the primitive, not homework for the caller:\n`redeemRowBoundGrant` takes a mandatory `commitAnchor(subject, expectedAnchor)`\nthat must move the row on atomically (a conditional UPDATE) and report whether\nthis caller won. It runs strictly after verification, so nobody can invalidate a\nrow by naming it with a junk token, and the loser of a race gets the same\nrejection as a forged grant. Skipping it is possible but has to be declared with\na reason (`{ unsafeSkip: { reason } }`), the way the framework handles\n`escapeHatch` — an undeclared skip is how a single-use grant quietly becomes a\nbearer token for the length of its TTL.\nEvery rejection returns a bare `{ ok: false }` with no reason, so a caller\ncannot accidentally turn an anonymous endpoint into a row-existence oracle.\n`user-data-rights`' deletion token now runs on the helper and its hand-rolled\n`peekDeletionTokenUserId` is gone. The tokens stay byte-compatible — a test\npins the wire format against the pre-refactor formula. It declares an\n`unsafeSkip` for the spend: `pendingDeletionRequestId` may only change through\n`updateUserLifecycle`, so a conditional UPDATE there would lose the field on a\nprojection rebuild. Behaviour of that flow is unchanged.\nNote for callers: the subject is not secret. `signToken` puts it in the token\nbody in the clear, so a grant on a row exposes that row's id to whoever holds\nthe link. Where the id itself must stay hidden, use an opaque handle\n(`./shared/single-use-token-store`) instead."
+  }
+]

package/src/shared/index.ts

@@ -20,9 +20,21 @@ export { createLockoutCounter, type LockoutCounterState } from "./lockout-counte
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { joinRowParentIsVisible, parentRowIsVisible } from "./parent-visibility";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
+export {
+  type RowBoundGrantResult,
+  redeemRowBoundGrant,
+  signRowBoundGrant,
+} from "./row-bound-grant";
 export { sessionField } from "./session-field";
 export { sessionLocaleField } from "./session-locale-field";
 export { sessionTimezoneField } from "./session-timezone-field";
+export {
+  peekTokenSubject,
+  signToken,
+  TokenPurpose,
+  type VerifyResult,
+  verifyToken,
+} from "./signed-token";
 export { createSingleUseTokenStore } from "./single-use-token-store";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";

package/src/shared/row-bound-grant.test.ts

@@ -0,0 +1,294 @@
+import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { redeemRowBoundGrant, signRowBoundGrant } from "./row-bound-grant";
+
+const SECRET = "test-secret-value";
+const PURPOSE = "waitlist-enrich";
+const SUBJECT = "row-42";
+const NOW = Temporal.Instant.fromEpochMilliseconds(1_700_000_000_000);
+
+function grantFor(anchor: string, ttlMinutes = 30): string {
+  return signRowBoundGrant({
+    subject: SUBJECT,
+    purpose: PURPOSE,
+    anchor,
+    ttlMinutes,
+    secret: SECRET,
+    now: NOW,
+  }).token;
+}
+
+function anchorIs(anchor: string | null): (subject: string) => Promise<string | null> {
+  return async () => anchor;
+}
+
+const SKIP_COMMIT = { unsafeSkip: { reason: "test covers verification only" } } as const;
+
+// Stands in for a conditional UPDATE ... WHERE anchor = expected: the first
+// caller to spend the live anchor wins, everyone after it gets false.
+function spendableAnchor(initial: string) {
+  let current: string | null = initial;
+  return {
+    load: async () => current,
+    commit: async (_subject: string, expected: string) => {
+      if (current !== expected) return false;
+      current = null;
+      return true;
+    },
+  };
+}
+
+describe("redeemRowBoundGrant", () => {
+  test("accepts a grant whose row still carries the anchor it was minted for", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.subject).toBe(SUBJECT);
+  });
+
+  test("passes the token's subject to loadAnchor so the row is looked up by it", async () => {
+    const seen: string[] = [];
+
+    await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: async (subject) => {
+        seen.push(subject);
+        return "pending";
+      },
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(seen).toEqual([SUBJECT]);
+  });
+
+  test("rejects a replayed grant once the row moved on to another anchor", async () => {
+    const token = grantFor("pending");
+
+    const first = await redeemRowBoundGrant({
+      token,
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+    const replayed = await redeemRowBoundGrant({
+      token,
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("enriched"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(first.ok).toBe(true);
+    expect(replayed.ok).toBe(false);
+  });
+
+  test("rejects when the row has no anchor at all", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs(null),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects instead of surfacing a throwing row lookup", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: async () => {
+        throw new Error("invalid input syntax for type uuid");
+      },
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects an expired grant", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending", 30),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW.add({ minutes: 31 }),
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects a grant redeemed against a different purpose", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: "waitlist-delete",
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects a tampered signature", async () => {
+    const [subject, expiresAt] = grantFor("pending").split(".");
+
+    const result = await redeemRowBoundGrant({
+      token: `${subject}.${expiresAt}.YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY`,
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects a grant minted with a different secret", async () => {
+    const foreign = signRowBoundGrant({
+      subject: SUBJECT,
+      purpose: PURPOSE,
+      anchor: "pending",
+      ttlMinutes: 30,
+      secret: "someone-elses-secret",
+      now: NOW,
+    }).token;
+
+    const result = await redeemRowBoundGrant({
+      token: foreign,
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("rejects without touching the row when no secret is configured", async () => {
+    let looked = false;
+
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: undefined,
+      loadAnchor: async () => {
+        looked = true;
+        return "pending";
+      },
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(looked).toBe(false);
+  });
+
+  test("rejects a malformed token without touching the row", async () => {
+    let looked = false;
+
+    const result = await redeemRowBoundGrant({
+      token: "not-a-token",
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: async () => {
+        looked = true;
+        return "pending";
+      },
+      commitAnchor: SKIP_COMMIT,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(looked).toBe(false);
+  });
+
+  test("only one of two simultaneous redemptions of the same grant wins", async () => {
+    const row = spendableAnchor("pending");
+    const token = grantFor("pending");
+    const redeem = () =>
+      redeemRowBoundGrant({
+        token,
+        purpose: PURPOSE,
+        secret: SECRET,
+        loadAnchor: row.load,
+        commitAnchor: row.commit,
+        now: NOW,
+      });
+
+    const [first, second] = await Promise.all([redeem(), redeem()]);
+
+    expect([first.ok, second.ok].filter(Boolean)).toHaveLength(1);
+  });
+
+  test("does not spend the anchor for a token that fails verification", async () => {
+    const row = spendableAnchor("pending");
+
+    const rejected = await redeemRowBoundGrant({
+      token: grantFor("some-other-anchor"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: row.load,
+      commitAnchor: row.commit,
+      now: NOW,
+    });
+    const legitimate = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: row.load,
+      commitAnchor: row.commit,
+      now: NOW,
+    });
+
+    expect(rejected.ok).toBe(false);
+    expect(legitimate.ok).toBe(true);
+  });
+
+  test("refuses an unsafeSkip without a reason", async () => {
+    const redeem = redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: { unsafeSkip: { reason: "  " } },
+      now: NOW,
+    });
+
+    expect(redeem).rejects.toThrow(/non-empty reason/);
+  });
+
+  test("rejects when the anchor can no longer be spent", async () => {
+    const result = await redeemRowBoundGrant({
+      token: grantFor("pending"),
+      purpose: PURPOSE,
+      secret: SECRET,
+      loadAnchor: anchorIs("pending"),
+      commitAnchor: async () => false,
+      now: NOW,
+    });
+
+    expect(result.ok).toBe(false);
+  });
+});

package/src/shared/row-bound-grant.ts

@@ -0,0 +1,115 @@
+// A short-lived grant that lets a caller without a session perform exactly
+// one named operation on exactly one row — the shape behind
+// user-data-rights' confirm-deletion-by-token and any "you just created this
+// row, now enrich it" flow.
+//
+// The row's own anchor (a value that moves on when the row is consumed: a
+// request id, a status, a version) is mixed INTO the HMAC purpose rather
+// than carried in the token. Verification recomputes it from the row's
+// CURRENT anchor, so a replayed token dies the moment the row moves on —
+// single-use semantics without a burn key or Redis. Minting and redeeming
+// share one purpose-building function so the two can't drift apart; that
+// coupling is the whole point of this module, since an unanchored purpose
+// silently degrades to a bearer token valid for the full TTL.
+//
+// Anchoring alone closes the replay window only AFTER the row has moved on.
+// Two requests redeeming the same grant simultaneously both read the live
+// anchor and both verify, so spending it is a separate, mandatory step:
+// `commitAnchor` must move the row on atomically (a conditional update on
+// the anchor) and report whether this caller was the one who did. Skipping
+// it is possible but has to be declared with a reason, the way the framework
+// handles escapeHatch — an undeclared skip is how a single-use grant quietly
+// becomes a bearer token for the length of its TTL. Put the actual write into
+// the same statement that spends the anchor: a write issued after `ok: true`
+// can lose its work to a crash while the grant is already burned.
+//
+// The subject is NOT secret: signToken puts it in the token body in the
+// clear. A grant on a row therefore exposes that row's id to whoever holds
+// the link. Where the id itself must stay hidden, use an opaque handle
+// (single-use-token-store) instead.
+
+import type { Temporal } from "temporal-polyfill";
+import { peekTokenSubject, signToken, verifyToken } from "./signed-token";
+
+export type RowBoundGrantResult =
+  | { readonly ok: true; readonly subject: string; readonly expiresAtMs: number }
+  | { readonly ok: false };
+
+// Atomically spends the anchor: must return true only for the single caller
+// that moved the row on from `expectedAnchor`, false for everyone else. A
+// plain "read, check, then write" is not enough — two requests redeeming the
+// same grant at once both read the live anchor and both pass.
+export type AnchorCommit =
+  | ((subject: string, expectedAnchor: string) => Promise<boolean>)
+  | { readonly unsafeSkip: { readonly reason: string } };
+
+const FAILED: RowBoundGrantResult = { ok: false };
+
+function anchoredPurpose(purpose: string, anchor: string): string {
+  return `${purpose}:${anchor}`;
+}
+
+export function signRowBoundGrant(args: {
+  readonly subject: string;
+  readonly purpose: string;
+  readonly anchor: string;
+  readonly ttlMinutes: number;
+  readonly secret: string;
+  readonly now?: Temporal.Instant;
+}): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  return signToken(
+    args.subject,
+    anchoredPurpose(args.purpose, args.anchor),
+    args.ttlMinutes,
+    args.secret,
+    args.now,
+  );
+}
+
+// Every rejection returns the same bare `{ ok: false }` — no reason, by
+// design. A caller that could tell "bad signature" from "no such row" would
+// hand an attacker a row-existence oracle on an endpoint that is open to
+// anonymous callers.
+export async function redeemRowBoundGrant(args: {
+  readonly token: string;
+  readonly purpose: string;
+  readonly secret: string | undefined;
+  readonly loadAnchor: (subject: string) => Promise<string | null>;
+  readonly commitAnchor: AnchorCommit;
+  readonly now?: Temporal.Instant;
+}): Promise<RowBoundGrantResult> {
+  if (!args.secret) return FAILED;
+
+  const subject = peekTokenSubject(args.token);
+  if (!subject) return FAILED;
+
+  // The subject is unverified attacker input at this point, so a lookup that
+  // throws on it (e.g. a non-uuid value against a uuid column) must not
+  // surface as a 500.
+  let anchor: string | null;
+  try {
+    anchor = await args.loadAnchor(subject);
+  } catch {
+    return FAILED;
+  }
+  if (!anchor) return FAILED;
+
+  const verified = verifyToken(
+    args.token,
+    anchoredPurpose(args.purpose, anchor),
+    args.secret,
+    args.now,
+  );
+  if (!verified.ok) return FAILED;
+
+  // Spending happens after verification, never before: a caller that burned
+  // the anchor on an unverified token could invalidate any row it can name.
+  if (typeof args.commitAnchor === "function") {
+    const spent = await args.commitAnchor(subject, anchor);
+    if (!spent) return FAILED;
+  } else if (!args.commitAnchor.unsafeSkip.reason.trim()) {
+    throw new Error("row-bound grant: unsafeSkip needs a non-empty reason");
+  }
+
+  return { ok: true, subject, expiresAtMs: verified.expiresAtMs };
+}

package/src/{auth-email-password/__tests__ → shared}/signed-token.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { Temporal } from "temporal-polyfill";
-import { signToken, TokenPurpose, verifyToken } from "../signed-token";
+import { signToken, TokenPurpose, verifyToken } from "./signed-token";
 
 const SECRET = "test-hmac-secret-32-bytes-minimum!!";
 const USER_ID = "11111111-1111-4111-8111-111111111111";