@cosmicdrift/kumiko-bundled-features 0.288.0 → 0.290.0

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,
         },
       };
     },

package/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -25,6 +25,25 @@ export type StartGracePeriodResult =
 //
 // The user row is tenant-agnostic (account-wide deletion), so it is read via
 // ctx.db.global(userTable); only the grace period duration is tenant-configured.
+// That read only supplies email/locale for the caller's notification — it is
+// NOT the transition's guard. The guard is `expect: { status: Active }` on
+// the lifecycle write itself (#3024): the executor re-checks it against a
+// fresh row right before writing, so a concurrent caller that already moved
+// the user off Active is rejected even though this read saw Active.
+//
+// `additionalExpect` lets a caller fold its own precondition into the SAME
+// atomic write — the confirm-by-token path uses it to spend a row-bound
+// grant's anchor (pendingDeletionRequestId) in the same statement that flips
+// status, per shared/row-bound-grant.ts's "write in the same statement that
+// spends the anchor" contract. The write also always clears
+// pendingDeletionRequestId: a request-by-email token is meant for one
+// confirm only, and leaving the id in place would let it re-arm later if
+// something ever moves the user back to Active without going through
+// cancel-deletion's explicit null (restrict/lift-restriction can't today,
+// since status is a single field and Restricted/DeletionRequested are
+// mutually exclusive — but nulling it here doesn't depend on that staying
+// true). No-op for the authenticated request-deletion path, which never set
+// a pendingDeletionRequestId to begin with.
 //
 // `gracePeriod` and `lifecycleRunner` are resolved by the caller: both
 // require an escalation (reading the tenant compliance profile, appending to
@@ -35,6 +54,7 @@ export async function startDeletionGracePeriod(
   userId: string,
   gracePeriod: DurationSpec,
   lifecycleRunner: DbRunner,
+  additionalExpect?: Readonly<Record<string, string | number | boolean | null>>,
 ): Promise<StartGracePeriodResult> {
   const userRow = await ctx.db
     .global(userTable)
@@ -47,7 +67,17 @@ export async function startDeletionGracePeriod(
       }),
     };
   }
-  if (userRow["status"] !== USER_STATUS.Active) {
+
+  const T = getTemporal();
+  const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
+
+  const { applied } = await updateUserLifecycle(
+    lifecycleRunner,
+    userId,
+    { status: USER_STATUS.DeletionRequested, gracePeriodEnd, pendingDeletionRequestId: null },
+    { expect: { status: USER_STATUS.Active, ...additionalExpect } },
+  );
+  if (!applied) {
     return {
       ok: false,
       error: new UnprocessableError("user_not_in_active_state", {
@@ -56,14 +86,6 @@ export async function startDeletionGracePeriod(
     };
   }
 
-  const T = getTemporal();
-  const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
-
-  await updateUserLifecycle(lifecycleRunner, userId, {
-    status: USER_STATUS.DeletionRequested,
-    gracePeriodEnd,
-  });
-
   return {
     ok: true,
     gracePeriodEnd,

package/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -21,30 +21,68 @@ import { USER_STATUS, userEntity, userTable } from "../../user";
 // kann abweichen).
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 
+export type UpdateUserLifecycleOptions = {
+  // Declarative "genau einmal"-precondition (#3024): the update only applies
+  // if the row still holds these field values at write time. Forwarded
+  // as-is to the executor's `expect:` — see event-store-executor-write.ts
+  // for the atomicity story. Omitted: behaves exactly as before (unconditional
+  // overwrite, skipOptimisticLock). Scalars only — see the executor's
+  // `expect:` doc for why (`!==` comparison, no object/Date/Instant values).
+  readonly expect?: Readonly<Record<string, string | number | boolean | null>>;
+};
+
 // `conn` is ctx.db.unsafeRaw(reason) (regular handlers) or the open tx
 // (forget-cleanup sub-tx) — keeps the event append atomic with the write.
+//
+// Returns `{ applied: false }` instead of throwing only when `options.expect`
+// was set AND the executor rejected the write because the precondition no
+// longer held (precondition_failed) or a concurrent writer won the race on
+// the same stream version (version_conflict) — both mean "someone else's
+// transition already landed", the expected outcome for a caller that opted
+// into `expect`. Any other failure, or a failure with no `expect` set (every
+// pre-#3024 caller), still throws — those callers never checked a return
+// value, so silently dropping their write would be silent data loss.
 export async function updateUserLifecycle(
   conn: DbRunner,
   userId: string,
   changes: Record<string, unknown>,
-): Promise<void> {
+  options?: UpdateUserLifecycleOptions,
+): Promise<{ readonly applied: boolean }> {
   // user ist systemStream (#497): der Executor-Choke-Point addressiert den
   // Stream immer auf SYSTEM_TENANT_ID — ein Rescope auf die row-tenant_id
   // waere wirkungslos. "system"-Mode, damit loadById auch Legacy-Rows findet,
   // deren tenant_id noch vor dem #762-Backfill-Rebuild steht.
+  // skipOptimisticLock stays true (kept correct, not just carried over): it
+  // was set from this function's very first version (#494) because every
+  // caller here is a server-side business transition (restrict/lift-
+  // restriction/grace-period/cancel/forget), never a client edit-conflict UI
+  // round-trip — none of them read-then-hold a row version to pass as
+  // `payload.version`, so the executor's version gate would reject every
+  // call outright without it (`update()` requires `payload.version` unless
+  // skipOptimisticLock is set). #3024 replaces the safety that decision gave
+  // up with the purpose-built `expect:` precondition above, checked fresh at
+  // write time — the mechanism now genuinely matches the caller's shape
+  // (a business-field guard) instead of a repurposed version check.
   const tenantDb = createTenantDb(conn, SYSTEM_TENANT_ID, "system");
   const result = await userExecutor.update(
     { id: userId, changes },
     createSystemUser(SYSTEM_TENANT_ID),
     tenantDb,
-    { skipOptimisticLock: true },
+    { skipOptimisticLock: true, ...(options?.expect && { expect: options.expect }) },
   );
 
-  if (!result.isSuccess) {
-    throw new InternalError({
-      message: `user lifecycle update failed for ${userId}: ${result.error.code}`,
-    });
+  if (result.isSuccess) return { applied: true };
+
+  if (
+    options?.expect &&
+    (result.error.code === "precondition_failed" || result.error.code === "version_conflict")
+  ) {
+    return { applied: false };
   }
+
+  throw new InternalError({
+    message: `user lifecycle update failed for ${userId}: ${result.error.code}`,
+  });
 }
 
 // #494 Bestandsdaten-Reconcile: Rows, deren Lifecycle-State der alte