@cosmicdrift/kumiko-bundled-features 0.285.2 → 0.287.0

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

@@ -16,11 +16,25 @@ export { entitiesOf } from "./entities-of";
 export { isWithinGracePeriod } from "./grace-period";
 export { hasWhereRule } from "./has-where-rule";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter";
 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/lockout-counter.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { createLockoutCounter } from "./lockout-counter";
+
+// Production Redis has active lockout/mfa-verify entries under these exact
+// keys — only asserting the generated Redis key strings (not just behavior
+// through a mocked client) catches a prefix typo that would silently make
+// existing entries unreachable. The two prefix pairs below are byte-copies
+// of the ones lockout-store.ts and mfa-verify-attempts.ts wire onto this
+// factory; only integration tests exercised this logic before (which never
+// assert on the raw key string), so this is new coverage.
+// countKey/untilKey are not exported by the factory (only the bound
+// operations are) — verify the key shape indirectly through a fake Redis
+// client that records the keys it's called with.
+function fakeRedis() {
+  const calls: { method: string; args: unknown[] }[] = [];
+  const redis = {
+    mget: async (...args: unknown[]) => {
+      calls.push({ method: "mget", args });
+      return [null, null];
+    },
+    incr: async (...args: unknown[]) => {
+      calls.push({ method: "incr", args });
+      return 1;
+    },
+    expire: async (...args: unknown[]) => {
+      calls.push({ method: "expire", args });
+      return 1;
+    },
+    set: async (...args: unknown[]) => {
+      calls.push({ method: "set", args });
+      return "OK";
+    },
+    get: async (...args: unknown[]) => {
+      calls.push({ method: "get", args });
+      return null;
+    },
+    del: async (...args: unknown[]) => {
+      calls.push({ method: "del", args });
+      return 1;
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: minimal ioredis stand-in for key-string assertions
+  } as any;
+  return { redis, calls };
+}
+
+describe("account-lockout Redis key strings", () => {
+  const counter = createLockoutCounter("kumiko:auth:lockout:count:", "kumiko:auth:lockout:until:");
+
+  test("getState reads the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.getState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "mget",
+      args: ["kumiko:auth:lockout:count:u1", "kumiko:auth:lockout:until:u1"],
+    });
+  });
+
+  test("clearState deletes the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.clearState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "del",
+      args: ["kumiko:auth:lockout:count:u1", "kumiko:auth:lockout:until:u1"],
+    });
+  });
+});
+
+describe("mfa-verify Redis key strings", () => {
+  const counter = createLockoutCounter(
+    "kumiko:auth:mfa-verify:count:",
+    "kumiko:auth:mfa-verify:until:",
+  );
+
+  test("getState reads the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.getState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "mget",
+      args: ["kumiko:auth:mfa-verify:count:u1", "kumiko:auth:mfa-verify:until:u1"],
+    });
+  });
+
+  test("clearState deletes the byte-identical count/until keys", async () => {
+    const { redis, calls } = fakeRedis();
+    await counter.clearState(redis, "u1");
+    expect(calls[0]).toEqual({
+      method: "del",
+      args: ["kumiko:auth:mfa-verify:count:u1", "kumiko:auth:mfa-verify:until:u1"],
+    });
+  });
+});

package/src/shared/lockout-counter.ts

@@ -0,0 +1,108 @@
+// Generic Redis-backed failed-attempt counter with auto-expiring lockout.
+// Extracted from auth-email-password/lockout-store.ts and
+// auth-mfa/mfa-verify-attempts.ts (infra#446) — both were byte-identical
+// INCR/NX logic, differing only in their Redis key prefixes.
+
+import type Redis from "ioredis";
+
+export type LockoutCounterState = {
+  readonly failureCount: number;
+  // Epoch milliseconds when the account/attempt auto-unlocks. null while the
+  // counter is still below threshold.
+  readonly lockedUntil: number | null;
+};
+
+// Two keys per subject so each can carry its own TTL:
+//   - count-key: 24h, carries the streak. Monotonic — once threshold is
+//     crossed it STAYS crossed until the caller explicitly clears it.
+//   - until-key: exactly the lockout duration, auto-expires when the lock
+//     ends (Redis TTL replaces a "timer" that would otherwise need a job).
+//
+// Consequence of the monotonic counter: once a subject has been locked, the
+// NEXT failure after the lock expires re-locks immediately — the INCR still
+// returns a value ≥ threshold, so the SET NX re-arms the lock. Clearing the
+// streak is the caller's responsibility (e.g. a successful login, or a
+// dedicated unlock flow) — intentional: brute-force resistance favours
+// strictness over UX for anonymous attempts.
+export function createLockoutCounter(countKeyPrefix: string, untilKeyPrefix: string) {
+  function countKey(subjectId: string): string {
+    return `${countKeyPrefix}${subjectId}`;
+  }
+  function untilKey(subjectId: string): string {
+    return `${untilKeyPrefix}${subjectId}`;
+  }
+
+  async function getState(redis: Redis, subjectId: string): Promise<LockoutCounterState | null> {
+    const [countRaw, untilRaw] = await redis.mget(countKey(subjectId), untilKey(subjectId));
+    if (countRaw === null) return null;
+    const failureCount = Number(countRaw);
+    if (!Number.isFinite(failureCount)) return null;
+    const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
+    return {
+      failureCount,
+      lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
+    };
+  }
+
+  // Race-free: INCR is atomic at the Redis level, so N concurrent failed
+  // attempts produce exactly N increments — no GET-SET window to lose an
+  // increment through. The NX on the until-key likewise guarantees only one
+  // attempt out of a concurrent batch sets the lock timestamp; subsequent
+  // concurrent attempts find the key already set and leave it alone, so the
+  // lock window stays anchored to the first-to-cross, not the last.
+  async function recordFailedAttempt(
+    redis: Redis,
+    subjectId: string,
+    maxFailedAttempts: number,
+    lockoutDurationMinutes: number,
+  ): Promise<LockoutCounterState> {
+    const lockDurationMs = lockoutDurationMinutes * 60 * 1000;
+    // TTL on the count-key: 24h covers "I fat-fingered yesterday". The
+    // lockout duration is on the until-key; the count-key outlives it so an
+    // expired lock leaves a counter ≥ threshold — that's what makes the next
+    // miss immediately re-lock (strict-semantic; see the type-comment above).
+    const ttlSec = Math.max(lockoutDurationMinutes * 60, 24 * 3600);
+
+    const count = await redis.incr(countKey(subjectId));
+    if (count === 1) {
+      // First failure → set the TTL. INCR doesn't set one; a counter without
+      // TTL would leak forever for subjects that never return.
+      await redis.expire(countKey(subjectId), ttlSec);
+    }
+
+    let lockedUntil: number | null = null;
+    if (count >= maxFailedAttempts) {
+      const computedUntil = Date.now() + lockDurationMs;
+      // NX: only set if no lock is currently armed. A second concurrent attempt
+      // arriving after the first crossed the threshold must NOT reset the
+      // timer — the lock window should align with the attempt that crossed,
+      // not the one that happened a millisecond later.
+      const setOk = await redis.set(
+        untilKey(subjectId),
+        String(computedUntil),
+        "PX",
+        lockDurationMs,
+        "NX",
+      );
+      if (setOk === "OK") {
+        lockedUntil = computedUntil;
+      } else {
+        // Another concurrent attempt already locked — read the authoritative
+        // timestamp so the returned state matches what a follow-up
+        // getState would see.
+        const existing = await redis.get(untilKey(subjectId));
+        lockedUntil = existing !== null ? Number(existing) : null;
+      }
+    }
+
+    return { failureCount: count, lockedUntil };
+  }
+
+  // Idempotent — deleting missing keys is a no-op, so a replayed clear just
+  // re-clears harmlessly.
+  async function clearState(redis: Redis, subjectId: string): Promise<void> {
+    await redis.del(countKey(subjectId), untilKey(subjectId));
+  }
+
+  return { getState, recordFailedAttempt, clearState };
+}