@cosmicdrift/kumiko-bundled-features 0.204.1 → 0.206.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.204.1",
+  "version": "0.206.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>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.204.1",
-    "@cosmicdrift/kumiko-framework": "0.204.1",
-    "@cosmicdrift/kumiko-headless": "0.204.1",
-    "@cosmicdrift/kumiko-renderer": "0.204.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.204.1",
-    "@cosmicdrift/kumiko-types": "0.204.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.206.0",
+    "@cosmicdrift/kumiko-framework": "0.206.0",
+    "@cosmicdrift/kumiko-headless": "0.206.0",
+    "@cosmicdrift/kumiko-renderer": "0.206.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.206.0",
+    "@cosmicdrift/kumiko-types": "0.206.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/auth-email-password/__tests__/invite-flow.integration.test.ts

@@ -250,22 +250,42 @@ describe("invite-create", () => {
     expect(rows[0]?.["tenantId"]).toBe(TENANT_A_ID);
   });
 
-  test("Resend: zweiter invite für selbe email → existing row updated, gleicher token", async () => {
+  test("Resend: second invite for the same email reuses the row but mints a new token and invalidates the previous one (#2174)", async () => {
     const firstToken = await inviteEmail(BOB_EMAIL, "Admin");
     const secondToken = await inviteEmail(BOB_EMAIL, "Editor");
 
-    expect(secondToken).toBe(firstToken);
+    expect(secondToken).not.toBe(firstToken);
 
-    // Eine Row, role updated
+    // Same row, role updated
     const rows = await selectMany(stack.db, tenantInvitationsTable, { email: BOB_EMAIL });
     expect(rows).toHaveLength(1);
     expect(rows[0]?.["role"]).toBe("Editor");
 
     // inviteEmail() only reads emailTransport.sent.at(-1) — a silent second-
-    // dispatch failure would still leave sent.length===1 and .at(-1) pointing
-    // at the FIRST mail, making secondToken===firstToken pass for the wrong
-    // reason. Assert an actual second dispatch happened.
+    // dispatch failure would still leave sent.length===1, making the
+    // not-equal check above pass for the wrong reason. Assert an actual
+    // second dispatch happened.
     expect(emailTransport.sent).toHaveLength(2);
+
+    // The first mail's link must actually stop working (not just look
+    // different) — this is what catches a double-hash bug in invalidation.
+    const firstRes = await authedRaw(
+      "POST",
+      "/api/auth/invite-accept",
+      { token: firstToken },
+      bobSession(),
+    );
+    expect(firstRes.status).toBe(422);
+    const firstBody = (await firstRes.json()) as { error?: { details?: { reason?: string } } };
+    expect(firstBody.error?.details?.reason).toBe(AuthErrors.invalidInviteToken);
+
+    const secondRes = await authedRaw(
+      "POST",
+      "/api/auth/invite-accept",
+      { token: secondToken },
+      bobSession(),
+    );
+    expect(secondRes.status).toBe(200);
   });
 });
 

package/src/auth-email-password/__tests__/signup-flow.integration.test.ts

@@ -6,8 +6,9 @@
 // Pinst:
 //   1. POST signup-request mit valid email → 200, Activation-Mail via
 //      delivery (channel-email in-memory transport) mit Token-URL.
-//   2. Resend-Idempotenz: zweiter Request für selbe email → gleicher
-//      Token in Mail (existing token in Redis wird re-genutzt).
+//   2. Resend: second request for the same email → a NEW token, and
+//      the previous token is invalidated (#2174 — Redis never stores
+//      the raw token as a value, so it can't be recovered/reused).
 //   3. POST signup-confirm mit captured Token + Password → 200, Cookies
 //      gesetzt (kumiko_auth + kumiko_csrf), Body mit user + tenantKey,
 //      DB hat user (emailVerified=true) + tenant + Admin-membership.
@@ -206,14 +207,26 @@ describe("POST /api/auth/signup-request", () => {
     expect(sent.html).toContain(`${APP_ACTIVATION_URL}?token=`);
   });
 
-  test("Resend: zweiter Request für selbe email → gleicher token in Mail", async () => {
+  test("Resend: second request for the same email mints a new token and invalidates the previous one", async () => {
     await postSignupRequest("resend@example.com");
     await postSignupRequest("resend@example.com");
 
     expect(emailTransport.sent).toHaveLength(2);
     const [first, second] = emailTransport.sent;
     if (!first || !second) throw new Error("missing mails");
-    expect(extractTokenFromMail(second.html)).toBe(extractTokenFromMail(first.html));
+    const firstToken = extractTokenFromMail(first.html);
+    const secondToken = extractTokenFromMail(second.html);
+    expect(secondToken).not.toBe(firstToken);
+
+    // The first mail's link must actually stop working (not just look
+    // different) — this is what catches a double-hash bug in invalidation.
+    const firstConfirm = await postSignupConfirm(firstToken, "irrelevant-pw-1234");
+    expect(firstConfirm.status).toBe(422);
+    const firstBody = (await firstConfirm.json()) as { error?: { details?: { reason?: string } } };
+    expect(firstBody.error?.details?.reason).toBe(AuthErrors.invalidSignupToken);
+
+    const secondConfirm = await postSignupConfirm(secondToken, "fresh-secure-pw-1234");
+    expect(secondConfirm.status).toBe(200);
   });
 
   test("malformed body → 200 (silent success, anti-enumeration)", async () => {

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -6,10 +6,11 @@
 // wie reset/verify/signup. Der Token geht NICHT an den Admin zurück (er soll
 // die Annahme nicht impersonieren können).
 //
-// Resend-Idempotenz: Re-Invite für gleiche (tenantId, email) während
-// pending → existing row + token re-genutzt + TTL refresh + zweite Mail
-// mit GLEICHEM Link. Bei status="cancelled" oder "accepted": existing
-// row updated zurück auf status=pending + neuer token.
+// Re-invite for the same (tenantId, email): the existing row is reused
+// regardless of its prior status (pending/cancelled/accepted), reset to
+// status=pending, and a fresh token is minted every time — any token
+// still live for that invitation is invalidated first, so the previous
+// mail's link stops working (see invite-token-store.ts).
 //
 // Always-200 für unbekannten User: bei invitee-Email die nicht in users
 // existiert wird trotzdem ein Invite erstellt — Branch-3-Accept-Flow
@@ -38,7 +39,7 @@ import {
 import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
 import { renderInviteEmail } from "../email-templates";
-import { getTokenForInvitation, storeInviteToken } from "../invite-token-store";
+import { invalidateExistingInviteToken, storeInviteToken } from "../invite-token-store";
 import { dispatchMagicLinkMail } from "../magic-link-mail";
 
 const INVITE_NOTIFICATION_TYPE = "auth-email-password:invite";
@@ -114,10 +115,10 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
       if (existing) {
         invitationId = existing["id"] as string; // @cast-boundary db-row
         const existingVersion = existing["version"] as number; // @cast-boundary db-row
-        // Resend-Idempotenz: Token aus Redis re-use wenn noch lebend.
-        // Sonst neuen mintinen (alter ist abgelaufen).
-        const existingToken = await getTokenForInvitation(ctx.redis, invitationId);
-        token = existingToken ?? generateToken();
+        // At most one live invite token per invitation: invalidate
+        // whatever's there before minting the new one.
+        await invalidateExistingInviteToken(ctx.redis, invitationId);
+        token = generateToken();
 
         const updateResult = await executor.update(
           {

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -7,11 +7,10 @@
 // existiert der User noch nicht). Ob die Email bereits ein Konto hat,
 // entscheidet bewusst der Confirm-Schritt, nicht dieser.
 //
-// Resend-Idempotenz: wenn für die Email bereits ein lebender Token in
-// Redis liegt, geben wir denselben Token zurück (und refreshen TTL auf
-// beiden Keys). Der User bekommt dann eine zweite Mail mit dem GLEICHEN
-// Activation-Link. Erste Mail bleibt gültig — kein "old link broken"-
-// annoyance.
+// Resend: if a token is still live for this email, we invalidate it and
+// mint a fresh one — the user gets a second mail with a NEW activation
+// link, and the first link stops working. Deliberate: at most one live
+// signup token per email at any time (see signup-token-store.ts).
 //
 // Always-200 (enumeration-safe): das Response sieht für jede Email gleich
 // aus, egal ob sie schon registriert ist oder nicht. Eine Email KANN bereits
@@ -32,7 +31,11 @@ import type { AuthMailLocale } from "../email-templates";
 import { renderActivationEmail } from "../email-templates";
 import { dispatchMagicLinkMail } from "../magic-link-mail";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
-import { getTokenForSignupEmail, normalizeEmail, storeSignupToken } from "../signup-token-store";
+import {
+  invalidateExistingSignupToken,
+  normalizeEmail,
+  storeSignupToken,
+} from "../signup-token-store";
 
 const SIGNUP_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
 
@@ -104,10 +107,9 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // lowercased haben.
       const email = event.payload.email;
 
-      // Resend-Idempotenz: wenn ein Token für diese Email noch lebt,
-      // re-use ihn und refreshe beide Keys. Der User kriegt eine zweite
-      // Mail mit dem GLEICHEN Link.
-      const existingToken = await getTokenForSignupEmail(ctx.redis, email);
+      // At most one live signup token per email: invalidate whatever's
+      // there before minting the new one (see signup-token-store.ts).
+      await invalidateExistingSignupToken(ctx.redis, email);
       // 32 random bytes = 256 bits unguessable randomness, base64url
       // encoded zu 43 chars. Math.random war früher ein Bug:
       // xorshift128+ hat ~128 Bit State der nach ~5 beobachteten
@@ -115,7 +117,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // signup-requests triggern und die Tokens fremder User
       // vorhersagen. generateToken nutzt randomBytes aus node:crypto,
       // dieselbe Quelle wie CSRF/Session-Tokens.
-      const token = existingToken ?? generateToken();
+      const token = generateToken();
 
       const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
       const expiresAtIso = expiresAt.toString();

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

@@ -1,53 +1,80 @@
-// Redis-backed Token-Store für Tenant-Invite-Magic-Link-Flow.
+// Redis-backed token store for the tenant-invite magic-link flow.
 //
-// Subject ist die Invitation-Row-ID (DB-row owner: tenant-feature). Wir
-// mappen Token → invitationId in Redis und nutzen den Token als opaque
-// random string aus generateToken (256 bit base64url, randomBytes).
+// 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).
 //
-// Anders als signup-token-store mappen wir hier NICHT bidirektional
-// — Resend-Idempotenz lebt auf der Invitation-Row-Ebene (Admin invitet
-// dieselbe email zweimal → existing row + token wird re-genutzt; das
-// invite-create-handler holt den existing token aus Redis via
-// invitationId-Lookup auf einem zweiten Key).
+// 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).
 //
-// Bidirektional ist trotzdem nützlich für Cancel: Admin cancelt → row.id
-// bekannt, ich brauche den token um Redis-Key zu löschen. Daher: zweiter
-// Key invite:by-id:<invitationId> → token. Cancel löscht beide.
+// 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.
 //
-// Bug-Pattern: TTL liegt nur in Redis. DB-row.expiresAt ist UI-Anzeige.
-// Bei expired-token: invite-accept findet den Token nicht → invalid-
-// invite-token. DB-row bleibt mit status="pending" — Cleanup-Job
-// markiert sie zu "expired" (separater Concern, kommt im U.3-Cleanup).
+// 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.
 //
-// Keine Kollision mit signup/reset/verify-Tokens: alle Invite-Keys haben
-// `invite:`-Prefix.
+// 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).
+//
+// No collision with signup/reset/verify tokens: all invite keys carry
+// the `invite:`-prefix.
 
+import { createHash } from "node:crypto";
 import type Redis from "ioredis";
 
 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");
+}
+
 function tokenKey(token: string): string {
-  return `${TOKEN_KEY_PREFIX}${token}`;
+  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}${token}`;
+  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). */
+ *  (refresh TTL für Resend). The by-id value is the token's hash, not
+ *  the token — see file header. */
 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), args.token, "EX", args.ttlSeconds),
+    redis.set(idKey(args.invitationId), hashToken(args.token), "EX", args.ttlSeconds),
   ]);
 }
 
@@ -57,13 +84,21 @@ export async function getInvitationIdForToken(redis: Redis, token: string): Prom
   return redis.get(tokenKey(token));
 }
 
-/** Lookup: Existierender Token für eine invitationId — für Resend-
- *  Idempotenz (Admin invitet dieselbe email zweimal → re-use token). */
-export async function getTokenForInvitation(
+/** 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). */
+export async function invalidateExistingInviteToken(
   redis: Redis,
   invitationId: string,
-): Promise<string | null> {
-  return redis.get(idKey(invitationId));
+): 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;
 }
 
 /** Single-Use-Burn. Wenn zwei Tabs gleichzeitig den Accept-Link klicken,

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

@@ -1,31 +1,33 @@
-// Redis-backed Pre-Activation-Token-Store für Magic-Link-Signup.
+// Redis-backed pre-activation token store for magic-link signup.
 //
-// Token-Material: opaque random 256-bit aus crypto.randomBytes
-// (siehe signup-request.write.ts → generateToken() aus framework/api).
-// Base64url-codiert zu 43 chars. NICHT no-confusable und NICHT für
-// menschliches Tippen — der User klickt den Mail-Link, niemand tippt
-// den Token ab.
+// 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.
 //
-// Anders als reset/verify-Tokens (HMAC-signed, stateless verifizierbar)
-// brauchen Signup-Tokens einen serverside Lookup: der User existiert
-// noch nicht, also gibt's keinen userId-claim den der HMAC binden
-// könnte. Wir mappen daher Token ↔ Email bidirektional in Redis und
-// löschen das Pair beim Confirm. Bidirektional weil:
-//   - by-token: confirm-handler braucht Token → Email
-//   - by-email: signup-request muss bei Resend einen existierenden
-//     Token wiederverwenden statt einen zweiten parallel laufen zu
-//     lassen (sonst hätte der User zwei Mails mit zwei verschiedenen
-//     Tokens, beide gültig, beide könnten zu zwei separaten Tenants
-//     führen wenn er beide klickt — unnötiges Risiko)
+// 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
 //
-// TTL-Refresh bei Resend: wenn der Token noch lebt, refreshen wir
-// einfach beide Keys auf die volle TTL — der User bekommt eine neue
-// Mail mit dem GLEICHEN Token, alte Mail bleibt gültig (idempotent
-// für den User).
+// 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.
 //
-// Keine Kollision mit reset/verify-Tokens: alle Signup-Keys haben
-// `signup:`-Prefix.
+// No collision with reset/verify tokens: all signup keys carry the
+// `signup:`-prefix.
 
+import { createHash } from "node:crypto";
 import type Redis from "ioredis";
 
 const TOKEN_KEY_PREFIX = "signup:by-token:";
@@ -40,26 +42,42 @@ 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");
+}
+
 function tokenKey(token: string): string {
-  return `${TOKEN_KEY_PREFIX}${token}`;
+  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}${token}`;
+  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. */
+ *  Idempotent — re-write derselben Token-Email-Kombi ist OK. The
+ *  by-email value is the token's hash, not the token — see file header. */
 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), args.token, "EX", args.ttlSeconds),
+    redis.set(emailKey(args.email), hashToken(args.token), "EX", args.ttlSeconds),
   ]);
 }
 
@@ -69,10 +87,19 @@ export async function getEmailForSignupToken(redis: Redis, token: string): Promi
   return redis.get(tokenKey(token));
 }
 
-/** Lookup: Existierenden Token für eine Email — falls noch valid und
- *  noch nicht konsumiert. Für Resend-Idempotenz im signup-request-Handler. */
-export async function getTokenForSignupEmail(redis: Redis, email: string): Promise<string | null> {
-  return redis.get(emailKey(email));
+/** 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. */
+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;
 }
 
 /** Single-Use-Burn: wenn zwei Tabs gleichzeitig den Confirm-Link klicken,

package/src/inbound-mail-foundation/__tests__/inbound-mail-foundation.integration.test.ts

@@ -323,11 +323,11 @@ describe("scenario 2b: ingest-message — Thread-Rollup selbstkorrigierend statt
   });
 });
 
-describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #1229)", () => {
+describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #1229, closed by #2155)", () => {
   // Probabilistic — looped per house convention (mehrere Durchläufe, z.B.
-  // 20x): the version-conflict race between two step-5 thread-rollup
-  // appends only fires on genuine transaction-timing interleaving, which
-  // a single run can't force deterministically.
+  // 20x): whether a concurrent thread-rollup commit lands inside the
+  // step-5 critical section depends on real transaction-timing
+  // interleaving, which a single run can't force deterministically.
   const ITERATIONS = 20;
   const CONCURRENCY = 3;
 
@@ -352,10 +352,10 @@ describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #
         ),
       );
 
-      // No writer's transaction fails with a 500 from the thread-rollup
-      // version conflict — each of the CONCURRENCY distinct messages is
-      // its own aggregate, so step 4 never races; only step 5 (shared
-      // threadAggId) does, and the bounded retry loop must absorb it.
+      // No writer's transaction fails with a 500 — each of the CONCURRENCY
+      // distinct messages is its own aggregate, so step 4 never races; step
+      // 5 (shared threadAggId) is serialized by the pg_advisory_xact_lock,
+      // so there's nothing here for the bounded retry loop to absorb.
       for (const res of responses) {
         expect(res.status).toBe(200);
         const body = (await res.json()) as { isSuccess: boolean; data: { duplicate: boolean } };
@@ -366,8 +366,9 @@ describe("scenario 2c: ingest-message — concurrent thread-rollup race (issue #
       const threadAggId = mailThreadAggregateId(admin.tenantId, `mid:${rootMessageIdHeader}`);
       const threadRows = await selectMany(db, mailThreadsProjectionTable, { id: threadAggId });
       expect(threadRows).toHaveLength(1);
-      // Every message's contribution landed — no drift from a silently
-      // stale-read-and-succeed append (the bug the retry loop replaces).
+      // Every message's contribution landed — the advisory lock closes the
+      // TOCTOU gap between countWhere and append that used to let a stale
+      // messageCount succeed without ever surfacing as a version conflict.
       expect(threadRows[0]?.["messageCount"]).toBe(CONCURRENCY);
     }
   });

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -25,6 +25,7 @@ import {
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
@@ -101,6 +102,10 @@ function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: strin
 }
 
 const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
+// pg_advisory_xact_lock namespace (int4) for the step-5 thread-rollup lock
+// — 'inbm' as ASCII, keeps it disjoint from the framework's other fixed
+// single-int advisory-lock keys (schema bootstrap, es-ops boot).
+const THREAD_ROLLUP_LOCK_NAMESPACE = 0x696e626d;
 export const ingestMessageHandler: WriteHandlerDef = {
   name: "ingest-message",
   schema: ingestMessageSchema,
@@ -230,35 +235,23 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    encrypted once up front (constant across retries, doesn't
     //    depend on the thread's prior state).
     //
-    //    messageCount deliberately does NOT come from a previously loaded
-    //    threadEvents snapshot (previousCount+1): two concurrent ingests
-    //    on the same thread (Watch-Push vs. Poll-Reconciliation overlap,
-    //    or two different messages of the same thread arriving at once)
-    //    can both read the same stream version before either commits.
-    //    tryAppendEvent's fresh version-read at append time makes the
-    //    loser's append fail with a VersionConflictError ONLY when the
-    //    other TX's commit lands between this reload and the append's own
-    //    version check — so we retry: reload the thread stream, recompute
-    //    the live row-count and lastMessageAt, and append again. If the
-    //    other TX instead commits in the gap between the countWhere below
-    //    and the append's version-read, the version check sees the
-    //    already-bumped stream and appends without conflict — but with the
-    //    stale row-count this countWhere captured before the concurrent
-    //    insert. That write still lands (messageCount can undercount by
-    //    one round), it is not eliminated by this retry loop; the next
-    //    ingest on the thread re-counts and self-corrects. Unlike step 4,
-    //    a lost version-conflict race here must NOT be treated as a no-op
+    //    messageCount is a live COUNT, not previousCount+1, so two
+    //    concurrent ingests on the same thread (Watch-Push vs.
+    //    Poll-Reconciliation overlap, or two different messages of the
+    //    same thread arriving at once) converge on the true count.
+    //    acquireNamespacedAdvisoryLock below (issue #2155) serializes this whole
+    //    countWhere+append section per threadAggId — transaction-scoped,
+    //    so it survives tryAppendEvent's inner SAVEPOINT and releases at
+    //    the enclosing TX's commit/rollback. Without it, a concurrent
+    //    commit landing between countWhere and tryAppendEvent's own fresh
+    //    version-read makes the append succeed with a stale count instead
+    //    of a VersionConflictError, so the retry loop below never sees it
+    //    as a conflict to retry (#1229's original gap). Unlike step 4, a
+    //    lost version-conflict race here must NOT be treated as a no-op
     //    duplicate — skipping would leave this message's contribution to
     //    messageCount/lastMessageAt out of the thread forever. Exhausting
     //    all attempts throws, rolling back the whole TX (including the
-    //    step-4 message append) for a clean re-ingest on the next poll —
-    //    never return success with a stale snapshot.
-    //
-    //    A true race-free read+append (e.g. SELECT ... FOR UPDATE or an
-    //    advisory lock on threadAggId) would close the countWhere→append
-    //    gap above and is deliberately not part of this fix — two writers
-    //    (watch + poll) make self-correcting drift an acceptable trade for
-    //    now.
+    //    step-4 message append) for a clean re-ingest.
     // ---------------------------------------------------------------
     const threadPlainPii = { tenantId, subject: payload.subject };
     const encryptedThreadFields = piiKms
@@ -274,6 +267,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
         )
       : threadPlainPii;
 
+    await acquireNamespacedAdvisoryLock(ctx.db.raw, THREAD_ROLLUP_LOCK_NAMESPACE, threadAggId);
+
     let threadAppendOk = false;
     for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
       const threadEvents = await ctx.loadAggregate(threadAggId);

package/src/tenant/handlers/cancel-invitation.write.ts

@@ -16,10 +16,7 @@ import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError, NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 // kumiko-lint-ignore cross-feature-import cancel needs invite-token-store for Redis cleanup
-import {
-  deleteInviteToken,
-  getTokenForInvitation,
-} from "../../auth-email-password/invite-token-store";
+import { invalidateExistingInviteToken } from "../../auth-email-password/invite-token-store";
 import {
   INVITATION_STATUS,
   tenantInvitationEntity,
@@ -82,13 +79,7 @@ export const cancelInvitationWrite = defineWriteHandler({
     // unavailable or the token already expired: not a problem, the DB
     // row is the single source of truth for the UI.
     if (ctx.redis) {
-      const token = await getTokenForInvitation(ctx.redis, event.payload.invitationId);
-      if (token) {
-        await deleteInviteToken(ctx.redis, {
-          invitationId: event.payload.invitationId,
-          token,
-        });
-      }
+      await invalidateExistingInviteToken(ctx.redis, event.payload.invitationId);
     }
 
     return { isSuccess: true, data: { id: event.payload.invitationId, alreadyDone: false } };

package/src/user/__tests__/email-unique-blind-index.integration.test.ts

@@ -0,0 +1,140 @@
+// fw#2134 — user:create's email-uniqueness check used to be a pure
+// pre-flight fetchOne (TOCTOU: two concurrent creates can both pass the
+// pre-flight and both insert, see handlers/create.write.ts). This proves
+// the DB-level fix directly against the executor (bypassing the handler's
+// pre-flight entirely) — a unique index over email's blind-index column
+// rejects the loser of a genuine race, and the framework's F8 pg-23505
+// mapping turns that into a clean 409 unique_violation, not a 500.
+//
+// createTestDb wires no blind-index key by default (see
+// blind-index.integration.test.ts) — without configureBlindIndexKey the
+// email_bidx column stays NULL for every row, the partial bidx unique
+// index never applies, and a race "passing" here would prove nothing. So
+// this test configures one explicitly and then proves the loser was
+// actually rejected on the bidx constraint (not the plaintext-fallback
+// index) by asserting the constraint name and reading email_bidx back off
+// the surviving row.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  computeBlindIndex,
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  decodeBlindIndexKey,
+  InMemoryKmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestDb,
+  type TestDb,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { userEntity, userTable } from "../schema/user";
+
+const TEST_KEY_B64 = Buffer.alloc(32, 9).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+let testDb: TestDb;
+const executor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, userEntity, "user");
+  await createEventsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_users RESTART IDENTITY CASCADE`,
+  );
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+  configureBlindIndexKey(TEST_KEY_B64);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+describe("fw#2134 — email unique constraint on the blind-index column", () => {
+  test("two concurrent creates with the same email: exactly one wins, loser fails on the bidx constraint", async () => {
+    const email = "race@example.com";
+    const tdb = createTenantDb(testDb.db, SYSTEM_TENANT_ID, "system");
+    const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+
+    const [first, second] = await Promise.all([
+      executor.create({ email, displayName: "Racer One" }, systemUser, tdb),
+      executor.create({ email, displayName: "Racer Two" }, systemUser, tdb),
+    ]);
+
+    const winner = first.isSuccess ? first : second;
+    const loser = first.isSuccess ? second : first;
+    if (loser.isSuccess || !winner.isSuccess) {
+      throw new Error("expected exactly one winner and one loser out of the two racing creates");
+    }
+
+    expect(loser.error.code).toBe("unique_violation");
+    expect(loser.error.httpStatus).toBe(409);
+    const details = loser.error.details as { constraintName?: string };
+    expect(details.constraintName).toBe("read_users_email_unique_bidx");
+
+    // Proves the race was actually decided by the blind-index constraint,
+    // not the plaintext-fallback index: the surviving row's bidx column
+    // carries the deterministic HMAC of the email.
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT "email_bidx" FROM "read_users" WHERE "id" = $1::uuid`,
+      [winner.data.id],
+    )) as ReadonlyArray<{ email_bidx: string | null }>;
+    expect(rows[0]?.email_bidx).toBe(computeBlindIndex(TEST_KEY, email));
+
+    // DB-proof: only one row actually survives under that blind index.
+    const survivors = (await asRawClient(testDb.db).unsafe(
+      `SELECT count(*)::int AS n FROM "read_users" WHERE "email_bidx" = $1`,
+      [computeBlindIndex(TEST_KEY, email)],
+    )) as ReadonlyArray<{ n: number }>;
+    expect(survivors[0]?.n).toBe(1);
+  });
+
+  test("a soft-deleted user still holds its email: constraint agrees with the pre-existing pre-flight behavior", async () => {
+    // Soft-delete only flips isDeleted/deletedAt (apply-entity-event.ts) —
+    // it never touches email/email_bidx, so the row still occupies the
+    // unique slot. This isn't new behavior from fw#2134: the handler's
+    // pre-flight fetchOne is a raw, unfiltered query (see create.write.ts)
+    // and already saw soft-deleted rows before this fix. This test pins
+    // that the new DB constraint doesn't diverge from that — only the
+    // GDPR "forgotten" hard-delete (see forget-cleanup) actually frees the
+    // email slot.
+    const email = "soft-deleted@example.com";
+    const tdb = createTenantDb(testDb.db, SYSTEM_TENANT_ID, "system");
+    const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+
+    const created = await executor.create(
+      { email, displayName: "Departing User" },
+      systemUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("expected create to succeed");
+
+    const deleted = await executor.delete({ id: created.data.id }, systemUser, tdb);
+    if (!deleted.isSuccess) throw new Error("expected soft-delete to succeed");
+
+    const reCreated = await executor.create({ email, displayName: "Squatter" }, systemUser, tdb);
+    if (reCreated.isSuccess) {
+      throw new Error("expected re-create with the same email to be rejected while soft-deleted");
+    }
+    expect(reCreated.error.code).toBe("unique_violation");
+    const details = reCreated.error.details as { constraintName?: string };
+    expect(details.constraintName).toBe("read_users_email_unique_bidx");
+  });
+});

package/src/user/__tests__/user.integration.test.ts

@@ -107,6 +107,37 @@ describe("scenario 1: create + me", () => {
     );
     expectErrorIncludes(error, UserErrors.emailAlreadyExists);
   });
+
+  // fw#2134 — the pre-flight fetchOne alone can't decide a genuine race
+  // (both requests can see "no duplicate" before either commits); this
+  // fires two real concurrent HTTP creates and checks the loser still
+  // gets a clean 4xx, never an unhandled 500. The DB-constraint-level
+  // proof (which layer actually catches the race, and that it's the
+  // blind-index column doing it) lives in
+  // email-unique-blind-index.integration.test.ts — this test's job is
+  // narrower: no request may 500 no matter who wins.
+  test("two concurrent creates with the same email: loser gets a clean 4xx, not a 500", async () => {
+    const email = "concurrent@example.com";
+    const [resA, resB] = await Promise.all([
+      stack.http.write(UserHandlers.create, { email, displayName: "Racer A" }, systemAdmin),
+      stack.http.write(UserHandlers.create, { email, displayName: "Racer B" }, systemAdmin),
+    ]);
+
+    const bodyA = (await resA.json()) as { isSuccess: boolean };
+    const bodyB = (await resB.json()) as { isSuccess: boolean };
+    const successes = [bodyA, bodyB].filter((b) => b.isSuccess === true);
+    const failures = [
+      { status: resA.status, body: bodyA },
+      { status: resB.status, body: bodyB },
+    ].filter((r) => r.body.isSuccess === false);
+
+    expect(successes).toHaveLength(1);
+    expect(failures).toHaveLength(1);
+    const loser = failures[0];
+    if (!loser) throw new Error("expected exactly one failing response");
+    expect(loser.status).toBeGreaterThanOrEqual(400);
+    expect(loser.status).toBeLessThan(500);
+  });
 });
 
 // --- Scenario 2: field-level read access hides passwordHash ---

package/src/user/handlers/create.write.ts

@@ -1,7 +1,12 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError, InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  InternalError,
+  type WriteErrorInfo,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { z } from "zod";
 import { UserErrors } from "../constants";
@@ -11,12 +16,16 @@ const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user
 
 // Only the Auth features (running as SYSTEM) or a SystemAdmin may create users.
 //
-// Email uniqueness is checked via a pre-flight query — the framework has no
-// `unique:` field flag yet. This check is race-prone: two concurrent requests
-// can both see "no duplicate" and both insert. Acceptable MVP behavior since
-// user creation is low-frequency and gated by privileged roles; the DB will
-// still surface a pg unique violation once we add the constraint.
-// TODO: replace with a real `unique:` field flag + DB constraint.
+// Email uniqueness has two layers (fw#2134):
+//  1. A pre-flight fetchOne — fast-fails with a friendly error on the
+//     common case, but is race-prone on its own: two concurrent requests
+//     can both see "no duplicate" and both proceed to crud.create.
+//  2. The real guard is the unique index over email's blind-index column
+//     (schema/user.ts). A losing concurrent create hits that constraint
+//     and crud.create returns a UniqueViolationError (framework's F8
+//     pg-23505 mapping) instead of throwing — remapped below to the same
+//     emailAlreadyExists shape the pre-flight path returns, so callers see
+//     one consistent error regardless of which layer caught the race.
 export const createWrite = defineWriteHandler({
   name: "user:create",
   schema: z.object({
@@ -56,6 +65,43 @@ export const createWrite = defineWriteHandler({
       );
     }
 
-    return crud.create(event.payload, event.user, db);
+    const result = await crud.create(event.payload, event.user, db);
+    if (!result.isSuccess && isEmailUniqueViolation(result.error)) {
+      return writeFailure(
+        new ConflictError({
+          message: "email already exists",
+          i18nKey: "user.errors.emailAlreadyExists",
+          details: {
+            reason: UserErrors.emailAlreadyExists,
+            field: "email",
+            constraintName: constraintNameOf(result.error),
+          },
+        }),
+      );
+    }
+    return result;
   },
 });
+
+// schema/user.ts's `read_users_email_unique` (+ its generated `_bidx`
+// pendant) is the actual race-safety net behind the pre-flight check
+// above — a losing concurrent create surfaces here as a generic
+// UniqueViolationError (framework F8 pg-23505 mapping). Only the email
+// constraint gets remapped; any other unique_violation on this entity
+// passes through unchanged.
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function constraintNameOf(error: WriteErrorInfo): string | undefined {
+  if (!isRecord(error.details)) return undefined;
+  const constraintName = error.details["constraintName"];
+  return typeof constraintName === "string" ? constraintName : undefined;
+}
+
+function isEmailUniqueViolation(error: WriteErrorInfo): boolean {
+  return (
+    error.code === "unique_violation" &&
+    (constraintNameOf(error)?.startsWith("read_users_email_unique") ?? false)
+  );
+}

package/src/user/schema/user.ts

@@ -169,6 +169,17 @@ export const userEntity = createEntity({
       access: { write: access.privileged },
     }),
   },
+  // fw#2134 — email is `pii: true, lookupable: true`, so the column holds
+  // per-row ciphertext: a plain unique index on it can't catch duplicates.
+  // `unique: true` over a lookupable column makes buildEntityTable /
+  // deriveEntityTableMeta emit a second, partial unique index over the
+  // deterministic `emailBidx` companion column (WHERE email_bidx IS NOT
+  // NULL — erased/key-less rows stay excluded), which is what actually
+  // closes the TOCTOU race between two concurrent user:create calls.
+  // Global (not tenant-scoped): user is a tenant-agnostic identity
+  // aggregate (systemStream: true) — a composite (tenantId, email) would
+  // leave the same email resolvable twice.
+  indexes: [{ columns: ["email"], unique: true, name: "read_users_email_unique" }],
 });
 
 export const userTable = buildEntityTable("user", userEntity);