@cosmicdrift/kumiko-bundled-features 0.311.0 → 0.313.0

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

@@ -23,13 +23,25 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineWriteHandler,
+  type HandlerContext,
   type SessionUser,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { ConflictError, InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  ConflictError,
+  InternalError,
+  reraiseAsKumikoError,
+  type WriteErrorInfo,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import { generateUniqueName } from "@cosmicdrift/kumiko-framework/random";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import {
+  findSignupHandoverProvider,
+  SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE,
+  type SignupHandoverBinding,
+} from "../../shared";
 // kumiko-lint-ignore cross-feature-import signup-confirm reads tenants.key for slug-uniqueness check (TOCTOU + DB-unique-index zusammen)
 import { tenantTable } from "../../tenant/schema/tenant";
 import { invalidSignupToken, signupEmailAlreadyRegistered } from "../errors";
@@ -38,8 +50,10 @@ import { passwordSchema } from "../password-policy";
 import { INITIAL_SIGNUP_ROLES, provisionSignupAccount } from "../seeding";
 import {
   burnSignupToken,
+  deleteSignupHandover,
   deleteSignupToken,
   getEmailForSignupToken,
+  getSignupHandover,
   unburnSignupToken,
 } from "../signup-token-store";
 
@@ -58,11 +72,57 @@ export type SignupConfirmData = {
   readonly kind: "auth-session";
   readonly session: SessionUser;
   readonly tenantKey: string;
+  // Present only when a bound tenant-handover grant existed AND its claim
+  // actually succeeded (see the handler body below).
+  readonly handover?: { readonly entityType: string; readonly id: string };
 };
 
 const SIGNUP_CONFIRM_PROVISION_REASON =
   "provisions a new tenant, its first user and membership before any tenant context exists";
 
+// UnprocessableError's `.code` is always the fixed literal "unprocessable" —
+// the distinguishing reason slug lives in `details.reason` (see
+// KumikoError's own reasonSlug getter in kumiko-error.ts). Comparing `.code`
+// directly against SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE would never
+// match; this reads the same field the framework itself uses.
+function isBenignClaimRejection(error: WriteErrorInfo): boolean {
+  return (
+    typeof error.details === "object" &&
+    error.details !== null &&
+    (error.details as Record<string, unknown>)["reason"] ===
+      SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE
+  );
+}
+
+type ClaimedHandover = { readonly entityType: string; readonly id: string };
+
+// Rides the caller's tx. A benign claim rejection (nothing was written) logs
+// and yields undefined; any other failure — including a real DB error, which
+// leaves the shared tx unusable regardless of catching it here — throws, so
+// the whole signup rolls back instead of leaving a partially moved transfer
+// graph next to a committed account.
+async function claimBoundHandover(
+  ctx: HandlerContext,
+  session: SessionUser,
+  binding: SignupHandoverBinding,
+): Promise<ClaimedHandover | undefined> {
+  const provider = findSignupHandoverProvider(ctx.registry);
+  if (!provider) {
+    ctx.log?.warn(
+      "signup-confirm: handover binding present but no signupHandover provider mounted",
+    );
+    return undefined;
+  }
+  const claim = provider.mintClaim(binding);
+  const claimResult = await ctx.writeAs(session, claim.qualifiedName, claim.payload);
+  if (claimResult.isSuccess) return { entityType: binding.entityType, id: binding.rowId };
+  if (!isBenignClaimRejection(claimResult.error)) throw reraiseAsKumikoError(claimResult.error);
+  ctx.log?.warn("signup-confirm: handover grant did not redeem", {
+    entityType: binding.entityType,
+  });
+  return undefined;
+}
+
 export function createSignupConfirmHandler() {
   return defineWriteHandler<"signup-confirm", typeof SignupConfirmSchema, SignupConfirmData>({
     name: "signup-confirm",
@@ -141,10 +201,6 @@ export function createSignupConfirmHandler() {
           throw err;
         }
 
-        // Cleanup beider Token-Lookup-Keys. Burn-Key bleibt für die
-        // restliche Burn-TTL als Replay-Schutz.
-        await deleteSignupToken(ctx.redis, { email, token: event.payload.token });
-
         // SessionUser für JWT-Mint. Roles aus INITIAL_SIGNUP_ROLES
         // damit DB-write (provisionSignupAccount) und Session-claim
         // dieselbe Quelle teilen — sonst hätten zwei Stellen "TenantAdmin"
@@ -156,6 +212,19 @@ export function createSignupConfirmHandler() {
           roles: [...INITIAL_SIGNUP_ROLES],
         };
 
+        // Claim BEFORE spending the signup token or the binding below and
+        // before `committed` flips: if the claim throws, the `finally` still
+        // unburns and the activation link stays retryable.
+        const handoverBinding = await getSignupHandover(ctx.redis, event.payload.token);
+        const handover = handoverBinding
+          ? await claimBoundHandover(ctx, session, handoverBinding)
+          : undefined;
+
+        // Drop both token lookup keys; the burn key stays for its remaining
+        // TTL as replay protection.
+        await deleteSignupToken(ctx.redis, { email, token: event.payload.token });
+        if (handoverBinding) await deleteSignupHandover(ctx.redis, event.payload.token);
+
         committed = true;
         return {
           isSuccess: true,
@@ -163,6 +232,7 @@ export function createSignupConfirmHandler() {
             kind: "auth-session",
             session,
             tenantKey,
+            ...(handover !== undefined && { handover }),
           },
         };
       } finally {

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

@@ -26,6 +26,7 @@ import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
 import * as z from "zod";
+import { findSignupHandoverProvider, type SignupHandoverBinding } from "../../shared";
 import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
 import { renderActivationEmail } from "../email-templates";
@@ -34,15 +35,30 @@ import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
 import {
   invalidateExistingSignupToken,
   normalizeEmail,
+  storeSignupHandover,
   storeSignupToken,
+  takeOverSignupHandoverForResend,
 } from "../signup-token-store";
 
 const SIGNUP_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
 
 const SignupRequestSchema = z.object({
   email: z.email(),
+  // Cross-device try-first handover (kumiko-framework#3035 follow-up,
+  // offlot-app#454) — see shared/signup-handover.ts for why the grant is
+  // verified here and rebound to the signup token instead of the client
+  // carrying it through the activation link.
+  handover: z
+    .object({
+      entityType: z.string().min(1),
+      token: z.string().min(1),
+    })
+    .optional(),
 });
 
+const HANDOVER_GRANT_VERIFY_REASON =
+  "verifies a tenant-handover grant against its root row in the source tenant (read-only anchor lookup) before binding it to the signup token";
+
 export type SignupRequestData =
   | {
       readonly kind: "signup-requested";
@@ -79,6 +95,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
     rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     description:
       "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
+    escapeHatch: { reason: HANDOVER_GRANT_VERIFY_REASON },
     handler: async (event, ctx) => {
       // Silent no-op when off, matching the route's own always-200
       // anti-enumeration contract (registerTokenRequestRoute swallows every
@@ -114,6 +131,12 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // between lookup paths that lowercase differently (or not at all).
       const email = event.payload.email;
 
+      // Read off the OLD token's binding before it's invalidated below — a
+      // resend without a fresh `handover` in the payload (the common case:
+      // the visitor just retyped their email) must still carry the earlier
+      // verified grant over to the new token instead of silently dropping it.
+      const priorBinding = await takeOverSignupHandoverForResend(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);
@@ -131,6 +154,43 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
 
       await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
 
+      // A handover grant in this request re-verifies and replaces the prior
+      // binding; anything short of a fresh, verified grant (no provider
+      // mounted, or verification failed) falls back to it instead —
+      // dropping a still-live binding on a bad request would strand the
+      // visitor's run. A throw here must never skip the mail below, or the
+      // signup itself silently breaks for a bug in a provider this handler
+      // doesn't own.
+      let binding: SignupHandoverBinding | null = priorBinding;
+      if (event.payload.handover) {
+        const { entityType, token: grantToken } = event.payload.handover;
+        const provider = findSignupHandoverProvider(ctx.registry);
+        if (!provider) {
+          ctx.log?.warn(
+            "signup-request: handover payload present but no signupHandover provider mounted",
+          );
+        } else {
+          try {
+            const verified = await provider.verifyGrant({
+              db: ctx.db.unsafeRaw(HANDOVER_GRANT_VERIFY_REASON),
+              registry: ctx.registry,
+              entityType,
+              token: grantToken,
+            });
+            if (verified) {
+              binding = verified;
+            } else {
+              ctx.log?.warn("signup-request: handover grant did not verify", { entityType });
+            }
+          } catch {
+            ctx.log?.warn("signup-request: handover grant verification threw", { entityType });
+          }
+        }
+      }
+      if (binding) {
+        await storeSignupHandover(ctx.redis, { token, binding, ttlSeconds });
+      }
+
       // normalizeEmail from the store — one source of truth for
       // normalization; the delivery recipient + lookup path consistently
       // get the same format.

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

@@ -11,7 +11,12 @@
 // `signup:`-prefix.
 
 import type Redis from "ioredis";
-import { createSingleUseTokenStore } from "../shared";
+import * as z from "zod";
+import {
+  createSingleUseTokenStore,
+  hashSingleUseToken,
+  type SignupHandoverBinding,
+} from "../shared";
 
 /** Email normalization — single source for every lookup layer (used
  *  internally by the store AND by callers that need a consistent form
@@ -67,3 +72,84 @@ export async function deleteSignupToken(
 /** 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;
+
+// Cross-device try-first handover (kumiko-framework#3035 follow-up,
+// offlot-app#454): signup-request binds a verified tenant-handover grant to
+// its own signup token, in a SIBLING Redis namespace keyed the same way
+// (sha256(token)) so it stays byte-compatible with the token store above
+// without going through it — the binding has its own lifecycle (survives a
+// resend, is read once by signup-confirm) that doesn't fit the token↔email
+// pairing. Only {entityType, rowId, sourceTenantId} is ever stored — never
+// the grant token or the email (see shared/signup-handover.ts).
+const SIGNUP_HANDOVER_KEY_PREFIX = "signup:handover:";
+
+const signupHandoverBindingSchema = z.object({
+  entityType: z.string().min(1),
+  rowId: z.string().min(1),
+  sourceTenantId: z.string().min(1),
+});
+
+function signupHandoverKeyForHash(tokenHash: string): string {
+  return `${SIGNUP_HANDOVER_KEY_PREFIX}${tokenHash}`;
+}
+
+function signupHandoverKey(token: string): string {
+  return signupHandoverKeyForHash(hashSingleUseToken(token));
+}
+
+function parseSignupHandoverBinding(raw: string): SignupHandoverBinding | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const parsed = signupHandoverBindingSchema.safeParse(json);
+  return parsed.success ? parsed.data : null;
+}
+
+/** Binds a verified grant to this signup token, TTL-matched to the token
+ *  itself so the binding never outlives (or is killed before) it. */
+export async function storeSignupHandover(
+  redis: Redis,
+  args: { token: string; binding: SignupHandoverBinding; ttlSeconds: number },
+): Promise<void> {
+  await redis.set(
+    signupHandoverKey(args.token),
+    JSON.stringify(args.binding),
+    "EX",
+    args.ttlSeconds,
+  );
+}
+
+/** Reads the binding for a still-live signup token, if any. */
+export async function getSignupHandover(
+  redis: Redis,
+  token: string,
+): Promise<SignupHandoverBinding | null> {
+  const raw = await redis.get(signupHandoverKey(token));
+  return raw === null ? null : parseSignupHandoverBinding(raw);
+}
+
+/** Carries a still-live binding over to a resend, before the old token is
+ *  invalidated: reads the old token's hash off the store's by-email entry
+ *  (never the token itself), fetches the binding under that hash, and
+ *  deletes it — the fresh token gets its own storeSignupHandover call with
+ *  the same binding right after. Null when there was no live binding. */
+export async function takeOverSignupHandoverForResend(
+  redis: Redis,
+  email: string,
+): Promise<SignupHandoverBinding | null> {
+  const oldTokenHash = await store.getTokenHashForSubject(redis, normalizeEmail(email));
+  if (oldTokenHash === null) return null;
+  const raw = await redis.get(signupHandoverKeyForHash(oldTokenHash));
+  if (raw === null) return null;
+  await redis.del(signupHandoverKeyForHash(oldTokenHash));
+  return parseSignupHandoverBinding(raw);
+}
+
+/** Cleanup after signup-confirm has read (and acted on, or logged a failed
+ *  claim for) the binding. */
+export async function deleteSignupHandover(redis: Redis, token: string): Promise<void> {
+  await redis.del(signupHandoverKey(token));
+}

package/src/auth-email-password/web/auth-client.ts

@@ -316,12 +316,18 @@ export async function confirmAccountUnlock(
 // User auf /signup/complete?token=… wo er sein Password setzt.
 export async function requestSignup(
   email: string,
+  // Cross-device try-first handover (kumiko-framework#3035 follow-up,
+  // offlot-app#454): forwards a row-bound tenant-handover grant so the
+  // server can verify + rebind it to the signup token. The grant never
+  // travels any further than this request — never in the URL, the mail,
+  // or the confirm response.
+  handover?: { readonly entityType: string; readonly token: string },
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
   const res = await fetch("/api/auth/signup-request", {
     method: "POST",
     credentials: "same-origin",
     headers: { "Content-Type": "application/json", ...csrfHeader() },
-    body: JSON.stringify({ email }),
+    body: JSON.stringify({ email, ...(handover !== undefined && { handover }) }),
   });
   if (res.ok) return { ok: true };
   return { ok: false, error: await parseTokenFailure(res) };
@@ -334,6 +340,9 @@ export async function requestSignup(
 export type SignupConfirmSuccess = {
   readonly user: { readonly id: string; readonly tenantId: string; readonly roles: string[] };
   readonly tenantKey: string;
+  // Present only when a bound handover grant existed and its claim
+  // succeeded — see signup-confirm.write.ts.
+  readonly handover?: { readonly entityType: string; readonly id: string };
 };
 
 export async function confirmSignup(

package/src/data-retention/__tests__/retention-cleanup-kms.integration.test.ts

@@ -0,0 +1,160 @@
+// Refs #2057 (partial) — hardDelete must crypto-shred the purged row's own
+// KMS subject key AFTER the forget, mirroring run-forget-cleanup.ts:477-503's
+// forget → eraseKey → nullBlindIndexesForSubject ordering. Only recordOwned
+// and self-pii subjects belong to the row being deleted; a userOwned field's
+// subject is the REFERENCED user, whose key may still protect that user's
+// other live rows elsewhere — hardDelete of one row must never erase it.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  KeyErasedError,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../feature";
+import { runRetentionCleanup } from "../run-retention-cleanup";
+
+// Entity A: `personal: { of: "id" }` → recordOwned — the row IS its own
+// subject. hardDelete must erase this key.
+const recordOwnedEntity = createEntity({
+  table: "read_c9_record_owned",
+  fields: {
+    note: createTextField({ required: true, personal: { of: "id" }, find: "none" }),
+  },
+  retention: { keepFor: "30d", strategy: "hardDelete" },
+});
+
+// Entity B: `personal: { of: "ownerUserId" }` → userOwned — the subject is
+// the REFERENCED user, not this row. hardDelete of this row must NEVER
+// erase the owner's key (they may own other, still-live rows).
+const userOwnedEntity = createEntity({
+  table: "read_c9_user_owned",
+  fields: {
+    ownerUserId: createTextField({
+      required: true,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    note: createTextField({ required: true, personal: { of: "ownerUserId" }, find: "none" }),
+  },
+  retention: { keepFor: "30d", strategy: "hardDelete" },
+});
+
+const c9Feature = defineFeature("c9-retention-kms-fixtures", (r) => {
+  r.entity("c9-record-owned", recordOwnedEntity);
+  r.entity("c9-user-owned", userOwnedEntity);
+});
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+let now: ReturnType<ReturnType<typeof getTemporal>["Now"]["instant"]>;
+let pastIso: string;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [createDataRetentionFeature(), c9Feature] });
+  for (const e of [tenantRetentionOverrideEntity, recordOwnedEntity, userOwnedEntity]) {
+    await unsafeCreateEntityTable(stack.db, e);
+  }
+  now = getTemporal().Now.instant();
+  pastIso = now.subtract({ hours: 60 * 24 }).toString(); // 60 days old, past the cutoff
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  for (const t of ["read_c9_record_owned", "read_c9_user_owned"]) {
+    await asRawClient(stack.db).unsafe(`DELETE FROM ${t}`);
+  }
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+// Ciphertext content is irrelevant to this test — it only proves which
+// subject's key eraseKey was (not) called for, not the field encryption
+// round-trip. The subject's key is pre-created here the same way the real
+// write path creates it on first encrypt (getOrCreateDek), so eraseKey's
+// effect is observable via getKey.
+async function seedRecordOwned(tenantId: string, insertedAtIso: string): Promise<string> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `INSERT INTO read_c9_record_owned (tenant_id, note, inserted_at) VALUES ($1, $2, $3::timestamptz) RETURNING id::text AS id`,
+    [tenantId, "pii:placeholder", insertedAtIso],
+  )) as { id: string }[];
+  const rowId = rows[0]?.id;
+  if (!rowId) throw new Error("seedRecordOwned: insert returned no id");
+  await kms.createKey({ kind: "record", entity: "c9-record-owned", id: rowId });
+  return rowId;
+}
+
+async function seedUserOwned(
+  tenantId: string,
+  ownerUserId: string,
+  insertedAtIso: string,
+): Promise<string> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `INSERT INTO read_c9_user_owned (tenant_id, owner_user_id, note, inserted_at) VALUES ($1, $2, $3, $4::timestamptz) RETURNING id::text AS id`,
+    [tenantId, ownerUserId, "pii:placeholder", insertedAtIso],
+  )) as { id: string }[];
+  const rowId = rows[0]?.id;
+  if (!rowId) throw new Error("seedUserOwned: insert returned no id");
+  await kms.createKey({ kind: "user", userId: ownerUserId });
+  return rowId;
+}
+
+describe("runRetentionCleanup :: hardDelete crypto-shredding (Refs #2057)", () => {
+  test("erases a recordOwned row's own key, leaves a userOwned row's owner key untouched", async () => {
+    const tenantId = testTenantId(9);
+    const ownerUserId = crypto.randomUUID();
+    const recordRowId = await seedRecordOwned(tenantId, pastIso);
+    const userRowId = await seedUserOwned(tenantId, ownerUserId, pastIso);
+
+    // Sanity: both keys exist and are readable before cleanup runs.
+    await expect(
+      kms.getKey({ kind: "record", entity: "c9-record-owned", id: recordRowId }),
+    ).resolves.toBeInstanceOf(Buffer);
+    await expect(kms.getKey({ kind: "user", userId: ownerUserId })).resolves.toBeInstanceOf(Buffer);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId,
+      tenantPreset: null,
+      now,
+    });
+
+    expect(result.hardDeleted).toBe(2);
+
+    const recordRows = await asRawClient(stack.db).unsafe(
+      `SELECT id FROM read_c9_record_owned WHERE tenant_id = $1`,
+      [tenantId],
+    );
+    expect(recordRows).toHaveLength(0);
+    await expect(
+      kms.getKey({ kind: "record", entity: "c9-record-owned", id: recordRowId }),
+    ).rejects.toThrow(KeyErasedError);
+
+    const userRows = await asRawClient(stack.db).unsafe(
+      `SELECT id FROM read_c9_user_owned WHERE tenant_id = $1`,
+      [tenantId],
+    );
+    expect(userRows).toHaveLength(0);
+    expect(userRowId).toBeTruthy();
+    // The owner's key must survive — it is not this row's own subject.
+    await expect(kms.getKey({ kind: "user", userId: ownerUserId })).resolves.toBeInstanceOf(Buffer);
+  });
+});

package/src/data-retention/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "data-retention hardDelete now erases a purged row's own KMS subject key",
+    "detail": "Refs #2057 (partial fix — the hardDelete path only). run-retention-\ncleanup's hardDelete forgot the row's event history via the executor but\nnever crypto-shredded its KMS subject key, leaving the DEK live after the\nrow was gone. It now erases the key in the same per-row sub-transaction as the\nforget (an eraseKey throw rolls the forget back too), mirroring run-\nforget-cleanup.ts's forget -> eraseKey -> nullBlindIndexesForSubject\nordering. Only the row's own recordOwned/self-pii subjects are erased;\na userOwned or tenantOwned field's subject is the REFERENCED user/tenant,\nnot this row, and may still protect other live rows elsewhere — those\nkeys are never touched. No migration needed."
+  },
   {
     "version": "0.309.0",
     "type": "breaking",