@cosmicdrift/kumiko-bundled-features 0.285.2 → 0.287.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.285.2",
+  "version": "0.287.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -93,6 +93,9 @@
     "./auth-email-password/seeding": "./src/auth-email-password/seeding.ts",
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
     "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
+    "./shared/single-use-token-store": "./src/shared/single-use-token-store.ts",
+    "./shared/signed-token": "./src/shared/signed-token.ts",
+    "./shared/row-bound-grant": "./src/shared/row-bound-grant.ts",
     "./delivery": "./src/delivery/index.ts",
     "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
@@ -129,12 +132,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.285.2",
-    "@cosmicdrift/kumiko-framework": "0.285.2",
-    "@cosmicdrift/kumiko-headless": "0.285.2",
-    "@cosmicdrift/kumiko-renderer": "0.285.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.285.2",
-    "@cosmicdrift/kumiko-types": "0.285.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.287.0",
+    "@cosmicdrift/kumiko-framework": "0.287.0",
+    "@cosmicdrift/kumiko-headless": "0.287.0",
+    "@cosmicdrift/kumiko-renderer": "0.287.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.287.0",
+    "@cosmicdrift/kumiko-types": "0.287.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +166,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.285.2",
-    "@cosmicdrift/kumiko-locale-es": "0.285.2"
+    "@cosmicdrift/kumiko-locale-de": "0.287.0",
+    "@cosmicdrift/kumiko-locale-es": "0.287.0",
+    "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "lockout-store and signup/invite-token-store now delegate to shared/lockout-counter and shared/single-use-token-store",
+    "detail": "No behavior change — same exported function/type names and Redis key prefixes as before the extraction."
+  },
   {
     "version": "0.218.0",
     "type": "improvement",

package/src/auth-email-password/invite-token-store.ts

@@ -1,127 +1,78 @@
 // Redis-backed token store for the tenant-invite magic-link flow.
 //
-// Subject is the invitation row ID (DB-row owner: tenant-feature). We
-// map token → invitationId in Redis, using the token as an opaque
-// random string from generateToken (256-bit base64url, randomBytes).
+// Subject is the invitation row ID (DB-row owner: tenant-feature). The
+// store mechanics (bidirectional token↔subject mapping, sha256-hashed
+// keys, single-use burn) live in shared/single-use-token-store.ts — this
+// file only wires the invite key prefixes onto it.
 //
-// Unlike signup-token-store we don't map bidirectionally for reuse —
-// resend-idempotency lives at the invitation-row level (an admin
-// inviting the same email twice reuses the existing row and mints a
-// fresh token; invite-create looks up the *previous* token's hash via
-// a second key to invalidate it before storing the new one).
-//
-// Bidirectional is still useful for cancel: the admin knows row.id and
-// needs the forward key to delete. Hence a second key,
-// invite:by-id:<invitationId>, holding the hash of the live token.
-// Cancel deletes both.
-//
-// Every key is derived from sha256(token), never the raw token —
-// Redis key names, MONITOR output, replica traffic, and memory/backup
-// dumps never carry the bearer secret in the clear (#2174). The
-// by-id entry stores the *hash* of the live token, not the token
-// itself, so it can only be used to invalidate — never to recover or
-// resend the original token. A resend therefore always mints a fresh
-// token and invalidates the previous one, rather than reusing the
-// same link.
+// Unlike signup-token-store we don't rely on the store's reverse lookup for
+// reuse-detection: resend-idempotency lives at the invitation-row level (an
+// admin inviting the same email twice reuses the existing row and mints a
+// fresh token; invite-create looks up the *previous* token's hash via the
+// by-id entry to invalidate it before storing the new one). The by-id entry
+// is still useful for cancel: the admin knows row.id and needs the forward
+// key to delete it.
 //
 // Bug pattern: TTL lives only in Redis. DB-row.expiresAt is UI display
 // only. On an expired token, invite-accept doesn't find it → invalid-
-// invite-token. The DB row stays status="pending" — a cleanup job
-// marks it "expired" (separate concern, tracked in U.3-cleanup).
+// invite-token. The DB row stays status="pending" — a cleanup job marks it
+// "expired" (separate concern, tracked in U.3-cleanup).
 //
-// No collision with signup/reset/verify tokens: all invite keys carry
-// the `invite:`-prefix.
+// No collision with signup/reset/verify tokens: all invite keys carry the
+// `invite:`-prefix.
 
-import { createHash } from "node:crypto";
 import type Redis from "ioredis";
+import { createSingleUseTokenStore } from "../shared";
 
-const TOKEN_KEY_PREFIX = "invite:by-token:";
-const ID_KEY_PREFIX = "invite:by-id:";
-const BURN_KEY_PREFIX = "invite:burn:";
-
-// Same sha256-hex pattern as hashPatToken (personal-access-tokens/hash.ts)
-// and preauthTokenKeyOf (framework/api/auth-routes.ts): the token is
-// high-entropy, so a single fast hash is enough — no brute-force surface
-// that would justify a slow password-hash.
-function hashToken(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
-}
+const store = createSingleUseTokenStore({
+  tokenPrefix: "invite:by-token:",
+  subjectPrefix: "invite:by-id:",
+  burnPrefix: "invite:burn:",
+});
 
-function tokenKey(token: string): string {
-  return `${TOKEN_KEY_PREFIX}${hashToken(token)}`;
-}
-// Builds the forward key from an already-hashed value (e.g. read back from
-// the by-id entry) — does NOT hash again. Keeping this separate from
-// tokenKey() (which hashes a raw token) makes a double-hash mistake visible
-// at the call site instead of silently no-op'ing a delete.
-function forwardKeyForHash(tokenHash: string): string {
-  return `${TOKEN_KEY_PREFIX}${tokenHash}`;
-}
-function idKey(invitationId: string): string {
-  return `${ID_KEY_PREFIX}${invitationId}`;
-}
-function burnKey(token: string): string {
-  return `${BURN_KEY_PREFIX}${hashToken(token)}`;
-}
-
-/** Speichert das Pair bidirektional und setzt TTL auf beiden Keys.
- *  Idempotent — re-write derselben Token-Invitation-Kombi ist OK
- *  (refresh TTL für Resend). The by-id value is the token's hash, not
- *  the token — see file header. */
+/** Stores the pair bidirectionally and sets TTL on both keys.
+ *  Idempotent — re-writing the same token-invitation pair is fine
+ *  (refreshes the TTL for resend). */
 export async function storeInviteToken(
   redis: Redis,
   args: { invitationId: string; token: string; ttlSeconds: number },
 ): Promise<void> {
-  await Promise.all([
-    redis.set(tokenKey(args.token), args.invitationId, "EX", args.ttlSeconds),
-    redis.set(idKey(args.invitationId), hashToken(args.token), "EX", args.ttlSeconds),
-  ]);
+  return store.store(redis, {
+    subjectId: args.invitationId,
+    token: args.token,
+    ttlSeconds: args.ttlSeconds,
+  });
 }
 
-/** Lookup: invitationId für Token. Null wenn Token nicht (mehr) existiert
- *  (abgelaufen, schon konsumiert, oder ungültig). */
-export async function getInvitationIdForToken(redis: Redis, token: string): Promise<string | null> {
-  return redis.get(tokenKey(token));
-}
+/** Lookup: invitationId for a token. Null if the token no longer exists
+ *  (expired, already consumed, or invalid). */
+export const getInvitationIdForToken = store.getSubjectForToken;
 
-/** Deletes a still-live invite token for this invitation, if one exists —
- *  both the forward entry (built from the hash stored in the by-id entry,
- *  never the raw token) and the by-id entry itself. Returns whether a live
- *  token existed. Two callers: invite-create on every resend (a fresh
- *  token + by-id entry follows right after, so this is "at most one live
- *  token per invitation"), and cancel-invitation (no replacement follows,
- *  so this is full cleanup). */
+/** Deletes a still-live invite token for this invitation, if one exists.
+ *  Two callers: invite-create on every resend (a fresh token + by-id entry
+ *  follows right after, so this is "at most one live token per
+ *  invitation"), and cancel-invitation (no replacement follows, so this is
+ *  full cleanup). */
 export async function invalidateExistingInviteToken(
   redis: Redis,
   invitationId: string,
 ): Promise<boolean> {
-  const existingHash = await redis.get(idKey(invitationId));
-  if (existingHash === null) return false;
-  await Promise.all([redis.del(forwardKeyForHash(existingHash)), redis.del(idKey(invitationId))]);
-  return true;
+  return store.invalidateExistingBySubject(redis, invitationId);
 }
 
-/** Single-Use-Burn. Wenn zwei Tabs gleichzeitig den Accept-Link klicken,
- *  gewinnt der erste, der zweite kriegt "already-used". TTL = 1h. */
-export async function burnInviteToken(
-  redis: Redis,
-  token: string,
-): Promise<"burned" | "already-used"> {
-  const result = await redis.set(burnKey(token), "1", "EX", 3600, "NX");
-  return result === "OK" ? "burned" : "already-used";
-}
+/** Single-use burn. If two tabs click the accept link at the same time,
+ *  the first one wins, the second gets "already-used". TTL = 1h. */
+export const burnInviteToken = store.burn;
 
-/** Cleanup nach erfolgreichem Accept ODER Cancel — beide Lookup-Keys
- *  löschen. Burn-Key bleibt für die restliche Burn-TTL als Replay-Schutz. */
+/** Cleanup after a successful accept OR cancel — deletes both lookup
+ *  keys. The burn key stays for the remaining burn TTL as replay protection. */
 export async function deleteInviteToken(
   redis: Redis,
   args: { invitationId: string; token: string },
 ): Promise<void> {
-  await Promise.all([redis.del(tokenKey(args.token)), redis.del(idKey(args.invitationId))]);
+  return store.deleteBoth(redis, { subjectId: args.invitationId, token: args.token });
 }
 
-/** Burn-Release für Failed-Accept-Pfade (DB-Error etc.) damit ein
- *  legitimer Retry nicht durch einen stale Burn-Marker geblockt wird. */
-export async function unburnInviteToken(redis: Redis, token: string): Promise<void> {
-  await redis.del(burnKey(token));
-}
+/** Burn release for failed-accept paths (DB error etc.) so a legitimate
+ *  retry isn't blocked by a stale burn marker. */
+export const unburnInviteToken = store.unburn;

package/src/auth-email-password/lockout-store.ts

@@ -12,112 +12,23 @@
 // active counter — an attacker could exploit the gap, though the IP-level
 // rate-limiter (framework rate-limit) is the parallel defense for that
 // case anyway.
+//
+// The counter mechanics (race-free INCR/NX, TTL rules, monotonic-counter
+// semantics) live in shared/lockout-counter.ts — this file only wires the
+// account-lockout key prefixes onto it. See that file for why a lock
+// re-arms immediately after expiry, and why a successful login (or the
+// account-unlock magic-link flow, #1266, see
+// handlers/confirm-account-unlock.write.ts) is what resets the streak.
 
-import type Redis from "ioredis";
+import { createLockoutCounter, type LockoutCounterState } from "../shared";
 
-export type LockoutState = {
-  readonly failureCount: number;
-  // Epoch milliseconds when the account auto-unlocks. null while the
-  // counter is still below threshold.
-  readonly lockedUntil: number | null;
-};
+export type LockoutState = LockoutCounterState;
 
-// Two keys per user so each can carry its own TTL:
-//   - count-key: 24h, carries the streak. Monotonic — once threshold is
-//     crossed it STAYS crossed until a successful login 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 user has been locked, the
-// NEXT wrong password after the lock expires re-locks immediately — the
-// INCR still returns a value ≥ threshold, so the SET NX re-arms the lock.
-// A successful login is one way to reset the streak; the other is the
-// account-unlock magic-link flow (#1266, see
-// handlers/confirm-account-unlock.write.ts), a deliberate escape hatch for
-// a legitimate user who can't currently produce the right password (e.g.
-// they forgot it too) but can prove mailbox ownership. Intentional:
-// brute-force resistance favours strictness over UX for anonymous login
-// attempts, while the unlock flow keeps the DoS from being permanent.
 const COUNT_KEY_PREFIX = "kumiko:auth:lockout:count:";
 const UNTIL_KEY_PREFIX = "kumiko:auth:lockout:until:";
 
-function countKey(userId: string): string {
-  return `${COUNT_KEY_PREFIX}${userId}`;
-}
-function untilKey(userId: string): string {
-  return `${UNTIL_KEY_PREFIX}${userId}`;
-}
-
-export async function getLockoutState(redis: Redis, userId: string): Promise<LockoutState | null> {
-  const [countRaw, untilRaw] = await redis.mget(countKey(userId), untilKey(userId));
-  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 wrong-
-// password 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.
-export async function recordFailedAttempt(
-  redis: Redis,
-  userId: string,
-  maxFailedAttempts: number,
-  lockoutDurationMinutes: number,
-): Promise<LockoutState> {
-  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(userId));
-  if (count === 1) {
-    // First failure → set the TTL. INCR doesn't set one; a counter without
-    // TTL would leak forever for users that never return.
-    await redis.expire(countKey(userId), 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(userId),
-      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
-      // getLockoutState would see.
-      const existing = await redis.get(untilKey(userId));
-      lockedUntil = existing !== null ? Number(existing) : null;
-    }
-  }
-
-  return { failureCount: count, lockedUntil };
-}
+const counter = createLockoutCounter(COUNT_KEY_PREFIX, UNTIL_KEY_PREFIX);
 
-// Called on successful login, and on a confirmed account-unlock token
-// (#1266). Idempotent — deleting missing keys is a no-op, so a replayed
-// unlock link just re-clears harmlessly.
-export async function clearLockoutState(redis: Redis, userId: string): Promise<void> {
-  await redis.del(countKey(userId), untilKey(userId));
-}
+export const getLockoutState = counter.getState;
+export const recordFailedAttempt = counter.recordFailedAttempt;
+export const clearLockoutState = counter.clearState;

package/src/auth-email-password/signed-token.ts

@@ -1,86 +1,4 @@
-// HMAC-signed single-purpose tokens for out-of-band auth flows
-// (password-reset, email-verification, future: magic-link).
-//
-// Format: <userId>.<expiresAtMs>.<hmac-base64url>
-//
-// The `purpose` is mixed INTO the HMAC input so a token minted for one
-// purpose (e.g. password-reset) can't be replayed against an endpoint that
-// expects another (e.g. verify-email), even if the caller knows the
-// userId and a valid expiry. Purpose is NOT carried in the token body —
-// verify() takes the purpose as argument and recomputes.
-//
-// Timing-safe comparison on verify so a valid-length forgery can't leak
-// signal through a short-circuit.
-
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { Temporal } from "temporal-polyfill";
-
-export type VerifyResult =
-  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
-  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
-
-function sign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
-}
-
-function payload(purpose: string, userId: string, expiresAtMs: number): string {
-  return `${purpose}:${userId}.${expiresAtMs}`;
-}
-
-export function signToken(
-  userId: string,
-  purpose: string,
-  ttlMinutes: number,
-  secret: string,
-  now: Temporal.Instant = Temporal.Now.instant(),
-): { token: string; expiresAt: Temporal.Instant } {
-  const expiresAt = now.add({ minutes: ttlMinutes });
-  const expiresAtMs = expiresAt.epochMilliseconds;
-  const signature = sign(payload(purpose, userId, expiresAtMs), secret);
-  return {
-    token: `${userId}.${expiresAtMs}.${signature}`,
-    expiresAt,
-  };
-}
-
-export function verifyToken(
-  token: string,
-  purpose: string,
-  secret: string,
-  now: Temporal.Instant = Temporal.Now.instant(),
-): VerifyResult {
-  const parts = token.split(".");
-  if (parts.length !== 3) return { ok: false, reason: "malformed" };
-  const [userId, expiresAtRaw, providedSig] = parts;
-  if (!userId || !expiresAtRaw || !providedSig) return { ok: false, reason: "malformed" };
-
-  const expiresAtMs = Number(expiresAtRaw);
-  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) {
-    return { ok: false, reason: "malformed" };
-  }
-
-  const expected = sign(payload(purpose, userId, expiresAtMs), secret);
-  const expectedBuf = Buffer.from(expected, "base64url");
-  const providedBuf = Buffer.from(providedSig, "base64url");
-  // Length mismatch fails BEFORE timingSafeEqual, which throws on different
-  // lengths — but that throw itself leaks via timing. Explicit length check
-  // keeps the path uniform.
-  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
-
-  if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
-    return { ok: false, reason: "expired" };
-  }
-
-  // expiresAtMs surfaces so callers (burn-store TTL, telemetry, …) don't
-  // have to re-parse the token themselves.
-  return { ok: true, userId, expiresAtMs };
-}
-
-// Canonical purposes baked into the framework. Features that introduce new
-// flows extend this set (or just pass an inline string).
-export const TokenPurpose = {
-  passwordReset: "reset",
-  emailVerification: "verify",
-  accountUnlock: "unlock",
-} as const;
+// Moved to shared/signed-token.ts — the mechanism was never specific to
+// email/password auth (user-data-rights and any row-bound grant use it too).
+// Re-exported so this feature's barrel and external importers keep working.
+export * from "../shared/signed-token";

package/src/auth-email-password/signup-token-store.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeEmail, storeSignupToken } from "./signup-token-store";
+
+// Only integration tests (signup-flow.integration.test.ts) exercised this
+// module before — none assert on the raw Redis key, so a case-sensitivity
+// regression in the by-email key wouldn't be caught: two signups from
+// "User@Example.com" and "user@example.com" would silently get separate
+// live-token entries instead of the second invalidating the first.
+function fakeRedis() {
+  const calls: { method: string; args: unknown[] }[] = [];
+  const redis = {
+    set: async (...args: unknown[]) => {
+      calls.push({ method: "set", args });
+      return "OK";
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: minimal ioredis stand-in for key-string assertions
+  } as any;
+  return { redis, calls };
+}
+
+describe("storeSignupToken", () => {
+  test("builds the by-email key from the normalized (lowercased) email", async () => {
+    const { redis, calls } = fakeRedis();
+    await storeSignupToken(redis, { email: "User@Example.com", token: "tok-1", ttlSeconds: 60 });
+    const subjectKey = calls[1]?.args[0];
+    expect(subjectKey).toBe(`signup:by-email:${normalizeEmail("User@Example.com")}`);
+    expect(subjectKey).toBe("signup:by-email:user@example.com");
+  });
+});