@cosmicdrift/kumiko-bundled-features 0.285.2 → 0.286.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.285.2",
+  "version": "0.286.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,7 @@
     "./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",
     "./delivery": "./src/delivery/index.ts",
     "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
@@ -129,12 +130,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.286.0",
+    "@cosmicdrift/kumiko-framework": "0.286.0",
+    "@cosmicdrift/kumiko-headless": "0.286.0",
+    "@cosmicdrift/kumiko-renderer": "0.286.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.286.0",
+    "@cosmicdrift/kumiko-types": "0.286.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +164,7 @@
   ],
   "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.286.0",
+    "@cosmicdrift/kumiko-locale-es": "0.286.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/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");
+  });
+});

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

@@ -1,132 +1,69 @@
 // Redis-backed pre-activation token store for magic-link signup.
 //
-// Token material: opaque random 256-bit from crypto.randomBytes (see
-// signup-request.write.ts → generateToken() from framework/api),
-// base64url-encoded to 43 chars. Not designed for human typing — the
-// user clicks the mail link, nobody types the token.
+// Subject is the (normalized) email — the user doesn't exist yet, so
+// there's no userId claim for an HMAC-signed token to bind to. 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 signup key prefixes onto it and normalizes the email
+// used as the subject id.
 //
-// Unlike reset/verify tokens (HMAC-signed, statelessly verifiable),
-// signup tokens need a server-side lookup: the user doesn't exist yet,
-// so there's no userId claim for the HMAC to bind to. We map token ↔
-// email bidirectionally in Redis and delete the pair on confirm.
-// Bidirectional because:
-//   - by-token: confirm-handler needs token → email
-//   - by-email: signup-request needs to know whether a token is still
-//     live for this email, so a resend can invalidate it instead of
-//     leaving two valid tokens for the same signup around
-//
-// 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-email entry stores the *hash* of the live token, not the token
-// itself, so it can only be used to invalidate (delete the matching
-// forward entry) — 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.
-//
-// No collision with reset/verify tokens: all signup keys carry the
+// No collision with reset/verify/invite tokens: all signup keys carry the
 // `signup:`-prefix.
 
-import { createHash } from "node:crypto";
 import type Redis from "ioredis";
+import { createSingleUseTokenStore } from "../shared";
 
-const TOKEN_KEY_PREFIX = "signup:by-token:";
-const EMAIL_KEY_PREFIX = "signup:by-email:";
-const BURN_KEY_PREFIX = "signup:burn:";
-
-/** Email-Normalisierung — single source für jede Lookup-Schicht (Store
- *  intern UND Caller die im Return-Body / Mail-Send eine konsistente
- *  Form brauchen). Vorher zwei Stellen mit `.toLowerCase()` — eine
- *  Quelle = kein Drift. */
+/** Email normalization — single source for every lookup layer (used
+ *  internally by the store AND by callers that need a consistent form
+ *  in the return body / mail send). Previously two places called
+ *  `.toLowerCase()` — one source means no drift. */
 export function normalizeEmail(email: string): string {
   return email.toLowerCase();
 }
 
-// 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: "signup:by-token:",
+  subjectPrefix: "signup:by-email:",
+  burnPrefix: "signup: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-email 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}`;
-}
-// @wrapper-known semantic-alias
-function emailKey(email: string): string {
-  return `${EMAIL_KEY_PREFIX}${normalizeEmail(email)}`;
-}
-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-Email-Kombi ist OK. The
- *  by-email 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-email pair is fine. */
 export async function storeSignupToken(
   redis: Redis,
   args: { email: string; token: string; ttlSeconds: number },
 ): Promise<void> {
-  await Promise.all([
-    redis.set(tokenKey(args.token), normalizeEmail(args.email), "EX", args.ttlSeconds),
-    redis.set(emailKey(args.email), hashToken(args.token), "EX", args.ttlSeconds),
-  ]);
+  return store.store(redis, {
+    subjectId: normalizeEmail(args.email),
+    token: args.token,
+    ttlSeconds: args.ttlSeconds,
+  });
 }
 
-/** Lookup: Email für einen Token. Null wenn Token nicht (mehr) existiert
- *  (abgelaufen, schon konsumiert, oder ungültig). */
-export async function getEmailForSignupToken(redis: Redis, token: string): Promise<string | null> {
-  return redis.get(tokenKey(token));
-}
+/** Lookup: email for a token. Null if the token no longer exists
+ *  (expired, already consumed, or invalid). */
+export const getEmailForSignupToken = store.getSubjectForToken;
 
-/** Deletes a still-live signup token for this email, if one exists — both
- *  the forward entry (built from the hash already stored in the by-email
- *  entry, never recovers the raw token) and the by-email entry itself.
- *  Returns whether a live token existed. Used by signup-request on every
- *  request; a fresh token + by-email entry follows right after, so this
- *  is "at most one live token per email." Deleting the by-email entry
- *  here too (not just the forward key) avoids leaving a dangling hash
- *  pointing at nothing if the request crashes before storeSignupToken. */
+/** Deletes a still-live signup token for this email, if one exists. Used
+ *  by signup-request on every request; a fresh token + by-email entry
+ *  follows right after, so this is "at most one live token per email." */
 export async function invalidateExistingSignupToken(redis: Redis, email: string): Promise<boolean> {
-  const existingHash = await redis.get(emailKey(email));
-  if (existingHash === null) return false;
-  await Promise.all([redis.del(forwardKeyForHash(existingHash)), redis.del(emailKey(email))]);
-  return true;
+  return store.invalidateExistingBySubject(redis, normalizeEmail(email));
 }
 
-/** Single-Use-Burn: wenn zwei Tabs gleichzeitig den Confirm-Link klicken,
- *  gewinnt der erste, der zweite kriegt "already-used". TTL = 1 Stunde
- *  (kurz genug damit der Burn-Key Redis nicht dauerhaft belastet, lang
- *  genug damit Replays in normalen Race-Windows abgefangen werden). */
-export async function burnSignupToken(
-  redis: Redis,
-  token: string,
-): Promise<"burned" | "already-used"> {
-  // SET NX EX — atomic check-and-set. Returnt "OK" wenn Key neu, null
-  // wenn schon da.
-  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 confirm link at the same time,
+ *  the first one wins, the second gets "already-used". */
+export const burnSignupToken = store.burn;
 
-/** Cleanup nach erfolgreichem Confirm — beide Lookup-Keys löschen.
- *  Burn-Key bleibt (verhindert Replay innerhalb der Burn-TTL). */
+/** Cleanup after a successful confirm — deletes both lookup keys.
+ *  The burn key stays (prevents replay within the burn TTL). */
 export async function deleteSignupToken(
   redis: Redis,
   args: { email: string; token: string },
 ): Promise<void> {
-  await Promise.all([redis.del(tokenKey(args.token)), redis.del(emailKey(args.email))]);
+  return store.deleteBoth(redis, { subjectId: normalizeEmail(args.email), token: args.token });
 }
 
-/** Burn-Release für Failed-Confirm-Pfade (DB-Error etc.) damit ein
- *  legitimer Retry nicht durch einen stale Burn-Marker geblockt wird. */
-export async function unburnSignupToken(redis: Redis, token: string): Promise<void> {
-  await redis.del(burnKey(token));
-}
+/** Burn release for failed-confirm paths (DB error etc.) so a legitimate
+ *  retry isn't blocked by a stale burn marker. */
+export const unburnSignupToken = store.unburn;

package/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.286.0",
+    "type": "improvement",
+    "title": "mfa-verify-attempts now delegates to shared/lockout-counter",
+    "detail": "No behavior change — same exported function/type names and Redis key prefixes as before the extraction."
+  },
   {
     "version": "0.259.0",
     "type": "improvement",