@cosmicdrift/kumiko-bundled-features 0.287.0 → 0.289.0

package/src/tenant-handover/handlers/claim.write.ts

@@ -0,0 +1,143 @@
+import {
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { redeemRowBoundGrant } from "../../shared";
+import { TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE, TENANT_HANDOVER_CLAIMED_EVENT_QN } from "../events";
+import { tenantHandoverPurpose } from "../grant";
+import { moveRootRow, moveTransferGraph } from "../move-entity-graph";
+import { resolveTransferableRoot } from "../transfer-graph";
+
+export type ClaimTenantHandoverOptions = {
+  readonly grantSecret?: string;
+};
+
+// Every rejection before the grant is even peeked is a bare 422 — same
+// no-oracle stance as row-bound-grant.ts. `entityType` itself is not secret
+// (the app's own domain vocabulary), so failing fast on an unknown or
+// undeclared root type is a plain config error, not a leak.
+function notTransferable(entityType: string): ReturnType<typeof writeFailure> {
+  return writeFailure(
+    new UnprocessableError("entity_not_transferable", {
+      i18nKey: "errors.tenantHandover.entityNotTransferable",
+      details: { entityType },
+    }),
+  );
+}
+
+// The try-before-signup ownership handover (kumiko-framework#3035): claims an
+// anonymous run into the caller's own tenant, legitimized by a row-bound
+// grant the anonymous flow minted (see ../grant.ts). Idempotent — a second
+// call with the same token fails the same way a forged one would, because
+// the grant's anchor (the run's tenantId) has already moved.
+export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOptions = {}) {
+  return defineWriteHandler({
+    name: "claim",
+    schema: z.object({ token: z.string().min(1), entityType: z.string().min(1) }),
+    access: { roles: ["Member", "User", "TenantAdmin", "SystemAdmin"] },
+    escapeHatch: {
+      reason:
+        "the ownership change moves rows OUT of a source tenant this caller has no membership " +
+        "in — the framework's declared cross-tenant operation for try-before-signup, not a " +
+        "per-consumer acknowledgeCrossTenant workaround",
+    },
+    agent: { expose: false },
+    rateLimit: { per: "user", limit: 10, windowSeconds: 60 },
+    handler: async (event, ctx) => {
+      const rootEntity = resolveTransferableRoot(ctx.registry, event.payload.entityType);
+      if (!rootEntity) return notTransferable(event.payload.entityType);
+
+      const rootTable = entityTableFromRegistry(ctx.registry, event.payload.entityType, rootEntity);
+      const rootTableName = extractTableName(rootTable);
+      const rootIdCol = physicalColumnName(rootTable, "id");
+      const rootTenantCol = physicalColumnName(rootTable, "tenantId");
+
+      const db = ctx.db.unsafeRaw(
+        "tenant-handover claim: cross-tenant read + ownership write, legitimized by the " +
+          "row-bound grant redeemed below",
+      );
+      const destinationTenantId = event.user.tenantId;
+
+      let sourceTenantId: string | undefined;
+      let movedEntities: Readonly<Record<string, number>> = {};
+
+      const redeemed = await redeemRowBoundGrant({
+        token: event.payload.token,
+        purpose: tenantHandoverPurpose(event.payload.entityType),
+        secret: opts.grantSecret,
+        loadAnchor: async (subject) => {
+          const rows = await executeRawQuery<{ tenantId: string }>(
+            db,
+            `SELECT "${rootTenantCol}" AS "tenantId" FROM "${rootTableName}" WHERE "${rootIdCol}" = $1`,
+            [subject],
+          );
+          return rows[0]?.tenantId ?? null;
+        },
+        commitAnchor: async (subject, expectedAnchor) => {
+          const moved = await moveRootRow({
+            db,
+            tableName: rootTableName,
+            idCol: rootIdCol,
+            tenantCol: rootTenantCol,
+            rowId: subject,
+            sourceTenantId: expectedAnchor,
+            destinationTenantId,
+          });
+          if (!moved) return false;
+
+          sourceTenantId = expectedAnchor;
+          movedEntities = await moveTransferGraph({
+            db,
+            registry: ctx.registry,
+            rootEntityName: event.payload.entityType,
+            rootRowId: subject,
+            sourceTenantId: expectedAnchor,
+            destinationTenantId,
+          });
+
+          // Own aggregate, decoupled from the transferred root's stream (see
+          // events.ts) — a fresh id needs no predecessor version and can't
+          // conflict with a concurrent write on the entity it describes.
+          await ctx.unsafeAppendEvent({
+            aggregateId: generateId(),
+            aggregateType: TENANT_HANDOVER_CLAIM_AGGREGATE_TYPE,
+            type: TENANT_HANDOVER_CLAIMED_EVENT_QN,
+            payload: {
+              entityType: event.payload.entityType,
+              rootRowId: subject,
+              sourceTenantId: expectedAnchor,
+              destinationTenantId,
+              movedEntities,
+            },
+          });
+
+          return true;
+        },
+      });
+
+      // sourceTenantId is only ever undefined here if commitAnchor never ran
+      // or returned false before setting it — both already covered by
+      // `redeemed.ok`. The explicit check narrows the type without a cast.
+      if (!redeemed.ok || sourceTenantId === undefined) {
+        return writeFailure(new UnprocessableError("invalid_or_expired_grant"));
+      }
+
+      return {
+        isSuccess: true as const,
+        data: {
+          entityType: event.payload.entityType,
+          id: redeemed.subject,
+          sourceTenantId,
+          destinationTenantId,
+          movedEntities,
+        },
+      };
+    },
+  });
+}

package/src/tenant-handover/index.ts

@@ -0,0 +1,9 @@
+export {
+  createTenantHandoverFeature,
+  type TenantHandoverFeatureOptions,
+} from "./feature";
+export { signTenantHandoverGrant, tenantHandoverPurpose } from "./grant";
+export {
+  type ClaimTenantHandoverOptions,
+  createClaimTenantHandoverHandler,
+} from "./handlers/claim.write";

package/src/tenant-handover/move-entity-graph.ts

@@ -0,0 +1,228 @@
+// The actual ownership change (kumiko-framework#3035): raw SQL against the
+// event store + read-model tables, because moving a row across the tenant
+// boundary is exactly the kind of write the framework's entity write map
+// cannot express (it is single-tenant-scoped by design — that boundary is
+// the whole point of `assertTenantMatch`). This is the framework's OWN
+// declared operation, not a consumer's `acknowledgeCrossTenant` escape.
+//
+// Every statement here runs inside the calling write handler's own
+// transaction (HandlerContext.db is transaction-scoped for the handler's
+// full duration — confirmed by dispatch-batch.ts's runBatch: a write handler
+// returning writeFailure throws BatchRollback inside the wrapping
+// `transaction()` call, rolling back everything the handler already did).
+// `moveRootRow` — called as row-bound-grant's `commitAnchor` — is therefore
+// the ONLY statement that must itself combine the anchor-spend with the
+// first write (#3023's hard rule: a write issued after `ok: true` can lose
+// its work to a crash while the grant is already burned). Everything after
+// it rides the same transaction: if a later step throws (an undeclared
+// child entity, kumiko-framework#3035's named-error requirement), the WHOLE
+// transaction — root row included — rolls back, so a caller can safely
+// retry the same token after fixing the app's `transferable` declarations.
+
+import {
+  type DbRunner,
+  entityTableFromRegistry,
+  executeRawQuery,
+  extractTableName,
+  physicalColumnName,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { resolveChildCandidates } from "./transfer-graph";
+
+const FILE_REFS_TABLE = "file_refs";
+const EVENTS_TABLE = "kumiko_events";
+const SNAPSHOTS_TABLE = "kumiko_snapshots";
+
+// The commitAnchor statement itself: spends the anchor (WHERE tenant_id =
+// expected) AND performs the ownership write (SET tenant_id = destination)
+// in one UPDATE — see file header. Returns whether THIS caller won.
+export async function moveRootRow(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly rowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<boolean> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $2 ` +
+      `WHERE "${args.idCol}" = $1 AND "${args.tenantCol}" = $3 ` +
+      `RETURNING "${args.idCol}" AS id`,
+    [args.rowId, args.destinationTenantId, args.sourceTenantId],
+  );
+  return rows.length === 1;
+}
+
+async function moveEventHistory(args: {
+  readonly db: DbRunner;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<void> {
+  // skip: an empty id list has nothing to move — both callers already
+  // filter to a non-empty list before calling, this only guards a future
+  // caller that forgets to.
+  if (args.aggregateIds.length === 0) return;
+  await executeRawQuery(
+    args.db,
+    `UPDATE ${EVENTS_TABLE} SET tenant_id = $1 ` +
+      `WHERE tenant_id = $2 AND aggregate_type = $3 AND aggregate_id = ANY($4)`,
+    [args.destinationTenantId, args.sourceTenantId, args.aggregateType, args.aggregateIds],
+  );
+  // Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+  // dropped rather than rewritten, forcing a full replay from the just-moved
+  // events on next read instead of carrying the snapshot's own generation
+  // bookkeeping across the tenant boundary.
+  await executeRawQuery(
+    args.db,
+    `DELETE FROM ${SNAPSHOTS_TABLE} WHERE tenant_id = $1 AND aggregate_id = ANY($2)`,
+    [args.sourceTenantId, args.aggregateIds],
+  );
+}
+
+async function moveFileRefs(args: {
+  readonly db: DbRunner;
+  readonly entityType: string;
+  readonly entityIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<number> {
+  if (args.entityIds.length === 0) return 0;
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE ${FILE_REFS_TABLE} SET tenant_id = $1 ` +
+      `WHERE tenant_id = $2 AND entity_type = $3 AND entity_id = ANY($4) RETURNING id`,
+    [args.destinationTenantId, args.sourceTenantId, args.entityType, args.entityIds],
+  );
+  return rows.length;
+}
+
+// `idCol` is a `parentRef.entityIdField` — by convention a text column (see
+// tags' tag-assignment entity: "Host entity ids are uuid/text; 128 covers
+// uuid plus non-uuid text keys"), never enforced as a type. A future
+// uuid-typed entityIdField would need the same CASE-guarded comparison
+// parent-ref-clause.ts uses for reads, to avoid a 22P02 on a non-uuid value
+// instead of silently matching zero rows.
+async function moveChildRows(args: {
+  readonly db: DbRunner;
+  readonly tableName: string;
+  readonly typeCol: string;
+  readonly idCol: string;
+  readonly tenantCol: string;
+  readonly pkCol: string;
+  readonly rootEntityType: string;
+  readonly rootRowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<readonly string[]> {
+  const rows = await executeRawQuery<{ id: string }>(
+    args.db,
+    `UPDATE "${args.tableName}" SET "${args.tenantCol}" = $1 ` +
+      `WHERE "${args.typeCol}" = $2 AND "${args.idCol}" = $3 AND "${args.tenantCol}" = $4 ` +
+      `RETURNING "${args.pkCol}" AS id`,
+    [args.destinationTenantId, args.rootEntityType, args.rootRowId, args.sourceTenantId],
+  );
+  return rows.map((row) => row.id);
+}
+
+// Everything the root ownership write does NOT cover: the root's own event
+// history + attached files, plus every parentRef-linked child's rows, event
+// history, and attached files. Returns a count per moved entity name (the
+// write handler turns this into the audit entry) — `fileRef` is a single
+// pooled count across root + every child, since it is not itself part of the
+// declared transfer graph (see files-tenant-data's own handover coverage for
+// why file BYTES never move, only the fileRef row's ownership).
+export async function moveTransferGraph(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly rootEntityName: string;
+  readonly rootRowId: string;
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<Readonly<Record<string, number>>> {
+  const { db, registry, rootEntityName, rootRowId, sourceTenantId, destinationTenantId } = args;
+  const movedCounts: Record<string, number> = { [rootEntityName]: 1 };
+  const trackFileMove = (count: number) => {
+    // skip: nothing moved (this entity had no attached files) — the audit
+    // payload should list `fileRef` only when a file actually moved, not a
+    // stray zero entry for every root/child that happens to have none.
+    if (count === 0) return;
+    movedCounts["fileRef"] = (movedCounts["fileRef"] ?? 0) + count;
+  };
+
+  await moveEventHistory({
+    db,
+    aggregateType: rootEntityName,
+    aggregateIds: [rootRowId],
+    sourceTenantId,
+    destinationTenantId,
+  });
+  trackFileMove(
+    await moveFileRefs({
+      db,
+      entityType: rootEntityName,
+      entityIds: [rootRowId],
+      sourceTenantId,
+      destinationTenantId,
+    }),
+  );
+
+  for (const candidate of resolveChildCandidates(registry, rootEntityName)) {
+    const parentRef = candidate.entity.parentRef;
+    if (!parentRef) continue; // resolveChildCandidates already filtered on this — narrows for TS
+    const table = entityTableFromRegistry(registry, candidate.entityName, candidate.entity);
+    const tableName = extractTableName(table);
+    const typeCol = physicalColumnName(table, parentRef.entityTypeField);
+    const idCol = physicalColumnName(table, parentRef.entityIdField);
+    const tenantCol = physicalColumnName(table, "tenantId");
+    const pkCol = physicalColumnName(table, "id");
+
+    const childIds = await moveChildRows({
+      db,
+      tableName,
+      typeCol,
+      idCol,
+      tenantCol,
+      pkCol,
+      rootEntityType: rootEntityName,
+      rootRowId,
+      sourceTenantId,
+      destinationTenantId,
+    });
+    if (childIds.length === 0) continue;
+
+    // Moved first, validated second — safe only because everything here
+    // shares the root UPDATE's transaction (see file header): throwing now
+    // rolls this move back together with the root's, not just this one.
+    if (candidate.entity.transferable !== true) {
+      throw new UnprocessableError("entity_not_transferable", {
+        i18nKey: "errors.tenantHandover.entityNotTransferable",
+        details: { entityName: candidate.entityName },
+      });
+    }
+
+    movedCounts[candidate.entityName] = childIds.length;
+    await moveEventHistory({
+      db,
+      aggregateType: candidate.entityName,
+      aggregateIds: childIds,
+      sourceTenantId,
+      destinationTenantId,
+    });
+    trackFileMove(
+      await moveFileRefs({
+        db,
+        entityType: candidate.entityName,
+        entityIds: childIds,
+        sourceTenantId,
+        destinationTenantId,
+      }),
+    );
+  }
+
+  return movedCounts;
+}

package/src/tenant-handover/transfer-graph.ts

@@ -0,0 +1,44 @@
+// Resolves the declared transfer graph for a root entity type: the root
+// itself, plus every registered entity whose `parentRef` can name it as a
+// host (kumiko-framework#3035, framework CLAUDE.md premise 4 — the graph
+// depth is read off the existing parentRef declaration, never a hand-
+// maintained per-app list). parentRef is one level deep by construction (the
+// boot validator at engine/boot-validator/parent-ref.ts rejects a host that
+// itself declares a parentRef), so this resolves in one registry pass.
+
+import type { EntityDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+export type TransferChildCandidate = {
+  readonly entityName: string;
+  readonly entity: EntityDefinition;
+};
+
+export function resolveTransferableRoot(
+  registry: Registry,
+  entityType: string,
+): EntityDefinition | undefined {
+  const entity = registry.getAllEntities().get(entityType);
+  return entity?.transferable === true ? entity : undefined;
+}
+
+// Broad on purpose: a candidate's `parentRef.allowedTypes` is a declaration
+// of which host TYPES it accepts, not proof any row of it currently points
+// at THIS root instance. The caller queries actual rows per candidate and
+// only enforces `transferable` on candidates that turn out to have matching
+// rows — narrowing here to "has rows" would need the very query the caller
+// is about to run anyway, and would make an unrelated candidate with
+// `allowedTypes: undefined` (any host) silently invisible instead of
+// query-checked.
+export function resolveChildCandidates(
+  registry: Registry,
+  rootEntityType: string,
+): readonly TransferChildCandidate[] {
+  const candidates: TransferChildCandidate[] = [];
+  for (const [entityName, entity] of registry.getAllEntities()) {
+    const parentRef = entity.parentRef;
+    if (!parentRef) continue;
+    if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(rootEntityType)) continue;
+    candidates.push({ entityName, entity });
+  }
+  return candidates;
+}

package/src/tenant-lifecycle/stages.ts

@@ -99,6 +99,8 @@ async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
       }),
       registry: ctx.registry,
       tenantId: ctx.tenantId,
+      fileProviderResolver: ctx.fileProviderResolver,
+      log: ctx.log,
     };
     await destroy(hookCtx);
   }

package/src/user-data-rights/__tests__/anonymous-deletion.integration.test.ts

@@ -179,18 +179,53 @@ describe("anonymous deletion flow", () => {
     expect(second.status).toBe(422);
     expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
 
-    // #354/2: der anonyme Endpoint gibt einen generischen reason zurück und
-    // leakt NICHT den konkreten User-Status (currentStatus), den ein
-    // Token-Inhaber sonst proben könnte.
+    // #354/2 + #3024: the anonymous endpoint returns the same generic reason
+    // for EVERY error path as an invalid token — since the grace-period
+    // transition now lives inside commitDeletion (the anchor spend), there is
+    // no separate res.ok branch left that could leak the concrete user status
+    // (currentStatus).
     const body = (await second.json()) as {
       error: { details?: { reason?: string } };
     };
-    expect(body.error.details?.reason).toBe("cannot_process_deletion");
+    expect(body.error.details?.reason).toBe("invalid_or_expired_token");
     const serialized = JSON.stringify(body.error);
     expect(serialized).not.toContain("currentStatus");
     expect(serialized).not.toContain(USER_STATUS.DeletionRequested);
   });
 
+  test("concurrent confirm-by-token (#3024): two simultaneous redemptions of the same token leave exactly one winner", async () => {
+    // Real concurrency case, real HTTP calls via setupTestStack, no sleep —
+    // the interleaving width varies between runs, hence 20 repetitions
+    // instead of a single run (probabilistic test).
+    for (let i = 0; i < 20; i++) {
+      await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+      await seedAlice();
+      verifyCalls.length = 0;
+      await stack.http.raw("POST", "/api/write", {
+        type: REQUEST_BY_EMAIL,
+        payload: { email: ALICE_EMAIL },
+      });
+      const token = tokenFromLastVerifyCall();
+
+      const [first, second] = await Promise.all([
+        stack.http.raw("POST", "/api/write", { type: CONFIRM_BY_TOKEN, payload: { token } }),
+        stack.http.raw("POST", "/api/write", { type: CONFIRM_BY_TOKEN, payload: { token } }),
+      ]);
+
+      expect([first.status, second.status].sort()).toEqual([200, 422]);
+      // Exactly ONE lifecycle transition: the row lands at DeletionRequested,
+      // not in a last-write-wins in-between state from two applied writes.
+      expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
+
+      const loser = first.status === 422 ? first : second;
+      const body = (await loser.json()) as { error: { details?: { reason?: string } } };
+      expect(body.error.details?.reason).toBe("invalid_or_expired_token");
+      const serialized = JSON.stringify(body.error);
+      expect(serialized).not.toContain("currentStatus");
+      expect(serialized).not.toContain(USER_STATUS.DeletionRequested);
+    }
+  });
+
   test("replay-after-cancel (#354/1): Token nach cancel-deletion re-armt NICHT → 422, bleibt Active", async () => {
     await seedAlice();
     await stack.http.raw("POST", "/api/write", {

package/src/user-data-rights/__tests__/deletion-token-compat.test.ts

@@ -20,6 +20,7 @@ describe("deletion token wire format", () => {
       token: legacy,
       secret: SECRET,
       loadPendingRequestId: async () => REQUEST_ID,
+      commitDeletion: async () => true,
     });
 
     expect(result.ok).toBe(true);

package/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Deletion tokens are genuinely single-use, and a losing redeem no longer leaks status",
+    "detail": "`redeemDeletionToken` previously carried an `unsafeSkip` and a separate status check before the lifecycle write, so two concurrent redemptions of the same token could both get through. The lifecycle transition now rides the executor's `expect:` precondition inside the anchor spend, so exactly one redemption wins.\nExternally visible: the loser of a concurrent redeem now receives the same generic `invalid_or_expired_token` reason on the anonymous path as an unknown token, instead of `cannot_process_deletion`. That was the point — the old reason distinguished \"known token, wrong state\" from \"unknown token\" to an unauthenticated caller. Integrators matching on the old string on that endpoint should expect the generic one.\n`pendingDeletionRequestId` is now cleared on confirm as well, closing a pre-existing gap. `skipOptimisticLock: true` stays in the lifecycle path and now carries the reason it is correct there: callers structurally never hold a row version to pass through."
+  },
   {
     "version": "0.287.0",
     "type": "improvement",

package/src/user-data-rights/deletion-token.ts

@@ -33,6 +33,14 @@ export function redeemDeletionToken(args: {
   readonly token: string;
   readonly secret: string | undefined;
   readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
+  // Spends the anchor AND performs the actual lifecycle transition in one
+  // atomic step (#3024) — the caller (confirm-deletion-by-token) folds the
+  // Active→DeletionRequested write itself in here via `updateUserLifecycle`'s
+  // `expect: { status: Active, pendingDeletionRequestId }`, so a write issued
+  // after `ok: true` can't lose its work to a crash while the grant is
+  // already burned (see shared/row-bound-grant.ts). Returns whether this
+  // caller was the one who moved the row on.
+  readonly commitDeletion: (userId: string, requestId: string) => Promise<boolean>;
   readonly now?: Temporal.Instant;
 }): Promise<RowBoundGrantResult> {
   return redeemRowBoundGrant({
@@ -40,17 +48,7 @@ export function redeemDeletionToken(args: {
     purpose: DELETION_REQUEST_PURPOSE,
     secret: args.secret,
     loadAnchor: args.loadPendingRequestId,
-    commitAnchor: {
-      unsafeSkip: {
-        reason:
-          "pendingDeletionRequestId may only be changed through updateUserLifecycle — a " +
-          "conditional UPDATE would bypass the user.updated event and lose the field on a " +
-          "projection rebuild (see update-user-lifecycle.ts). The concurrent-redeem window " +
-          "this leaves open predates row-bound grants: startDeletionGracePeriod already " +
-          "read-then-writes the Active check. Closing it needs an atomic lifecycle " +
-          "transition, which is its own change.",
-      },
-    },
+    commitAnchor: args.commitDeletion,
     now: args.now,
   });
 }

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -40,17 +40,23 @@ async function readPendingDeletionRequestId(
   }
 }
 
-// Anonymer Apex-Flow Schritt 2: Verify-Link-Target. Verifiziert das
-// HMAC-Token, extrahiert die userId und startet die Grace-Period über die
-// geteilte Logik.
+// Anonymous apex flow step 2: verify-link target. Verifies the HMAC token,
+// extracts the userId, and flips the grace period through the shared logic —
+// in ONE atomic step with the anchor spend (#3024): commitDeletion carries
+// the actual grace-period transition, so a crash after the spend can no
+// longer lose the write step.
 //
-// Replay-Schutz (#354/1): die requestId der Row ist Teil des Verify-Keys. Wir
-// lesen sie über die (unverifizierte, nur-Lookup) userId aus dem Token, lehnen
-// einen fehlenden Eintrag ab und verifizieren das Token gegen die CURRENT
-// requestId. Ein zweites Confirm auf einen noch-pending User trifft zudem
-// non-active → cannot_process_deletion. Nach einem cancel-deletion (status →
-// Active, pendingDeletionRequestId → null) schlägt ein nachgespieltes Token an
-// der genullten/erneuerten requestId fehl — kein re-arm mehr.
+// Replay protection (#354/1): the row's requestId is part of the verify key.
+// We read it via the (unverified, lookup-only) userId from the token, reject
+// a missing entry, and verify the token against the CURRENT requestId. After
+// a cancel-deletion (status → Active, pendingDeletionRequestId → null), a
+// replayed token fails against the nulled/renewed requestId — no re-arm.
+//
+// Concurrency (#3024): two simultaneous confirms of the same token both read
+// the same requestId and both verify the HMAC — commitDeletion spends the
+// anchor AND writes the transition atomically (expect: status===Active &&
+// pendingDeletionRequestId===requestId), so exactly one wins. The loser gets
+// the same generic 422 as an invalid token — no status leak (#354/2).
 export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByTokenOptions = {}) {
   return defineWriteHandler({
     name: "confirm-deletion-by-token",
@@ -66,16 +72,6 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     agent: { expose: false },
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      // The row's requestId is part of the verify key, so a token from a
-      // cancelled or superseded cycle fails. Every error path ends in the same
-      // generic 422.
-      const verified = await redeemDeletionToken({
-        token: event.payload.token,
-        secret: opts.deletionTokenSecret,
-        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
-      });
-      if (!verified.ok) return writeFailure(invalidToken());
-
       // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
       // the compliance-profile shape.
       const profile = (await ctx.queryAs(
@@ -83,26 +79,40 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
         "compliance-profiles:query:for-tenant",
         {},
       )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
-      const res = await startDeletionGracePeriod(
-        ctx,
-        verified.subject,
-        profile.profile.userRights.gracePeriod,
-        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
-      );
-      if (!res.ok) {
-        // Generischer 422 statt res.error: dieser Endpoint ist anonym-öffentlich,
-        // res.error trägt den konkreten User-Status (currentStatus aus
-        // user_not_in_active_state) und würde einem Token-Inhaber das Proben des
-        // Account-Status erlauben (#354/2). Der authentifizierte request-deletion-
-        // Pfad zeigt dem User legitim seinen eigenen Status.
-        return writeFailure(new UnprocessableError("cannot_process_deletion"));
-      }
+
+      let gracePeriodEndIso: string | undefined;
+
+      // The row's requestId is part of the verify key, so a token from a
+      // cancelled or superseded cycle fails. Every error path ends in the same
+      // generic 422 — commitDeletion folding the grace-period write into the
+      // anchor-spend means there's no separate res.ok branch left to leak a
+      // concrete status through.
+      const verified = await redeemDeletionToken({
+        token: event.payload.token,
+        secret: opts.deletionTokenSecret,
+        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
+        commitDeletion: async (userId, requestId) => {
+          const res = await startDeletionGracePeriod(
+            ctx,
+            userId,
+            profile.profile.userRights.gracePeriod,
+            ctx.db.unsafeRaw(
+              "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream",
+            ),
+            { pendingDeletionRequestId: requestId },
+          );
+          if (!res.ok) return false;
+          gracePeriodEndIso = res.gracePeriodEnd.toString();
+          return true;
+        },
+      });
+      if (!verified.ok || gracePeriodEndIso === undefined) return writeFailure(invalidToken());
 
       return {
         isSuccess: true as const,
         data: {
           status: USER_STATUS.DeletionRequested,
-          gracePeriodEnd: res.gracePeriodEnd.toString(),
+          gracePeriodEnd: gracePeriodEndIso,
         },
       };
     },