@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/shared/identity-v3-hash.ts

@@ -0,0 +1,97 @@
+// ASP.NET Core Identity V3 password-hash verifier.
+//
+// Why this lives in Kumiko: legacy migrations from .NET stacks (BMC: 22k
+// users with Identity-V3 passwordHash) need login to keep working without
+// forcing every user through a password-reset flow. New hashes are still
+// argon2 — Identity-V3 is verify-only.
+//
+// Format specification (from ASP.NET Core Identity source —
+// `Microsoft.AspNetCore.Identity.PasswordHasher`, `IdentityV3` mode):
+//
+//   Byte 0:        format marker (0x01 = V3)
+//   Bytes 1..4:    PRF as uint32 big-endian
+//                    1 = HMACSHA256
+//                    2 = HMACSHA512
+//                    (BMC uses 1; we accept both since the format does)
+//   Bytes 5..8:    iteration count as uint32 big-endian
+//   Bytes 9..12:   salt length in bytes as uint32 big-endian
+//   Bytes 13..:    salt + derived subkey, concatenated
+//
+//   The whole blob is base64-encoded. Typical BMC hash starts with
+//   "AQAAAAEAACcQ..." which decodes to:
+//     0x01 (V3) | 0x00000001 (HMACSHA256) | 0x00002710 (10000 iter) | …
+//
+// We never produce these — `hashPassword()` (argon2id) is the canonical
+// path. After a successful Identity-V3 login the application can re-hash
+// the password into argon2 on the next change-password event; that's
+// out-of-scope here.
+
+import { pbkdf2Sync, timingSafeEqual } from "node:crypto";
+
+const FORMAT_MARKER_V3 = 0x01;
+const HEADER_LENGTH = 13; // 1 (format) + 4 (PRF) + 4 (iter) + 4 (saltLen)
+
+const PRF_HMAC_SHA256 = 1;
+const PRF_HMAC_SHA512 = 2;
+
+// Quick sniff so the caller can route between argon2 and Identity-V3 without
+// throwing parse errors on every login. Only checks the format marker; the
+// full structural validation happens in `verifyIdentityV3Hash`.
+export function isIdentityV3Hash(hashB64: string): boolean {
+  const bytes = decodeBase64(hashB64);
+  if (bytes === null) return false;
+  return bytes.length >= HEADER_LENGTH && bytes[0] === FORMAT_MARKER_V3;
+}
+
+// Returns true on match. False on any mismatch — wrong password, malformed
+// hash, unsupported PRF, garbled length fields. Never throws (mirrors
+// `verifyPassword`'s contract — auth handlers don't want exceptions on
+// pathological stored data, just a clean "no").
+export function verifyIdentityV3Hash(password: string, hashB64: string): boolean {
+  const bytes = decodeBase64(hashB64);
+  if (bytes === null) return false;
+  if (bytes.length < HEADER_LENGTH) return false;
+  if (bytes[0] !== FORMAT_MARKER_V3) return false;
+
+  const prf = bytes.readUInt32BE(1);
+  const iterations = bytes.readUInt32BE(5);
+  const saltLength = bytes.readUInt32BE(9);
+
+  // Defensive: ASP.NET writes 16-byte salts, but the format technically
+  // allows any length. We accept what's encoded but bail if the blob is
+  // truncated mid-salt.
+  if (saltLength === 0) return false;
+  if (bytes.length <= HEADER_LENGTH + saltLength) return false; // need ≥1 subkey byte
+
+  const salt = bytes.subarray(HEADER_LENGTH, HEADER_LENGTH + saltLength);
+  const subkey = bytes.subarray(HEADER_LENGTH + saltLength);
+
+  const algorithm = prfToNodeAlgorithm(prf);
+  if (algorithm === null) return false;
+
+  let derived: Buffer;
+  try {
+    derived = pbkdf2Sync(password, salt, iterations, subkey.length, algorithm);
+  } catch {
+    return false;
+  }
+
+  if (derived.length !== subkey.length) return false;
+  return timingSafeEqual(derived, subkey);
+}
+
+function prfToNodeAlgorithm(prf: number): "sha256" | "sha512" | null {
+  if (prf === PRF_HMAC_SHA256) return "sha256";
+  if (prf === PRF_HMAC_SHA512) return "sha512";
+  return null;
+}
+
+function decodeBase64(b64: string): Buffer | null {
+  // Lenient decode: Buffer.from strips whitespace and ignores trailing garbage,
+  // which is what we want for hashes pulled out of CSV exports / legacy DBs
+  // that might carry stray CR/LF.
+  if (typeof b64 !== "string" || b64.length === 0) return null;
+  const buf = Buffer.from(b64, "base64");
+  if (buf.length === 0) return null;
+  return buf;
+}

package/packages/bundled-features/src/shared/index.ts

@@ -0,0 +1,53 @@
+export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
+export {
+  type ChunkedMigrationOptions,
+  type ChunkedMigrationResult,
+  type ChunkedMigrationStopReason,
+  type MigrationRowOutcome,
+  runChunkedMigration,
+} from "./chunked-entity-migration.js";
+export {
+  classifyStoredEnvelope,
+  type StoredEnvelopeClassification,
+} from "./classify-stored-envelope.js";
+export { decryptStoredPii } from "./decrypt-stored-pii.js";
+export { encryptForDirectWrite } from "./encrypt-for-direct-write.js";
+export { entitiesOf } from "./entities-of.js";
+export { isWithinGracePeriod } from "./grace-period.js";
+export { hasWhereRule } from "./has-where-rule.js";
+export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
+export { isTenantDb } from "./is-tenant-db.js";
+export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.js";
+export { mapWithConcurrency } from "./map-with-concurrency.js";
+export {
+  denyUnlessJoinRowParentVisible,
+  joinRowParentIsVisible,
+  parentRowIsVisible,
+} from "./parent-visibility.js";
+export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
+export {
+  type RowBoundGrantResult,
+  redeemRowBoundGrant,
+  signRowBoundGrant,
+} from "./row-bound-grant.js";
+export { runInSubTransaction } from "./run-in-sub-transaction.js";
+export { sessionLocaleField } from "./session-locale-field.js";
+export { sessionTimezoneField } from "./session-timezone-field.js";
+export {
+  peekTokenSubject,
+  signToken,
+  TokenPurpose,
+  type VerifyResult,
+  verifyToken,
+} from "./signed-token.js";
+export {
+  EXT_SIGNUP_HANDOVER,
+  findSignupHandoverProvider,
+  isSignupHandoverProvider,
+  SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE,
+  type SignupHandoverBinding,
+  type SignupHandoverProvider,
+} from "./signup-handover.js";
+export { createSingleUseTokenStore, hashSingleUseToken } from "./single-use-token-store.js";
+export type { SystemQueryFn } from "./system-query.js";
+export { type BurnResult, burnToken, unburnToken } from "./token-burn-store.js";

package/packages/bundled-features/src/shared/is-tenant-db.ts

@@ -0,0 +1,9 @@
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+
+// Structural probe: a TenantDb and a raw DbRunner both expose fetchOne/selectMany,
+// so the shape alone can't tell them apart — `unsafeRaw` only exists on TenantDb.
+// Shared so retention/compliance-profile resolvers that accept either (bulk cron
+// vs. per-hook TenantDb) branch through one predicate instead of duplicating it.
+export function isTenantDb(db: DbRunner | TenantDb): db is TenantDb {
+  return typeof (db as Partial<TenantDb>).unsafeRaw === "function";
+}

package/packages/bundled-features/src/shared/lockout-counter.ts

@@ -0,0 +1,108 @@
+// Generic Redis-backed failed-attempt counter with auto-expiring lockout.
+// Extracted from auth-email-password/lockout-store.ts and
+// auth-mfa/mfa-verify-attempts.ts — both were byte-identical
+// INCR/NX logic, differing only in their Redis key prefixes.
+
+import type { Redis } from "ioredis";
+
+export type LockoutCounterState = {
+  readonly failureCount: number;
+  // Epoch milliseconds when the account/attempt auto-unlocks. null while the
+  // counter is still below threshold.
+  readonly lockedUntil: number | null;
+};
+
+// Two keys per subject so each can carry its own TTL:
+//   - count-key: 24h, carries the streak. Monotonic — once threshold is
+//     crossed it STAYS crossed until the caller explicitly clears it.
+//   - until-key: exactly the lockout duration, auto-expires when the lock
+//     ends (Redis TTL replaces a "timer" that would otherwise need a job).
+//
+// Consequence of the monotonic counter: once a subject has been locked, the
+// NEXT failure after the lock expires re-locks immediately — the INCR still
+// returns a value ≥ threshold, so the SET NX re-arms the lock. Clearing the
+// streak is the caller's responsibility (e.g. a successful login, or a
+// dedicated unlock flow) — intentional: brute-force resistance favours
+// strictness over UX for anonymous attempts.
+export function createLockoutCounter(countKeyPrefix: string, untilKeyPrefix: string) {
+  function countKey(subjectId: string): string {
+    return `${countKeyPrefix}${subjectId}`;
+  }
+  function untilKey(subjectId: string): string {
+    return `${untilKeyPrefix}${subjectId}`;
+  }
+
+  async function getState(redis: Redis, subjectId: string): Promise<LockoutCounterState | null> {
+    const [countRaw, untilRaw] = await redis.mget(countKey(subjectId), untilKey(subjectId));
+    if (countRaw === null) return null;
+    const failureCount = Number(countRaw);
+    if (!Number.isFinite(failureCount)) return null;
+    const lockedUntil = untilRaw !== null ? Number(untilRaw) : null;
+    return {
+      failureCount,
+      lockedUntil: lockedUntil !== null && Number.isFinite(lockedUntil) ? lockedUntil : null,
+    };
+  }
+
+  // Race-free: INCR is atomic at the Redis level, so N concurrent failed
+  // attempts produce exactly N increments — no GET-SET window to lose an
+  // increment through. The NX on the until-key likewise guarantees only one
+  // attempt out of a concurrent batch sets the lock timestamp; subsequent
+  // concurrent attempts find the key already set and leave it alone, so the
+  // lock window stays anchored to the first-to-cross, not the last.
+  async function recordFailedAttempt(
+    redis: Redis,
+    subjectId: string,
+    maxFailedAttempts: number,
+    lockoutDurationMinutes: number,
+  ): Promise<LockoutCounterState> {
+    const lockDurationMs = lockoutDurationMinutes * 60 * 1000;
+    // TTL on the count-key: 24h covers "I fat-fingered yesterday". The
+    // lockout duration is on the until-key; the count-key outlives it so an
+    // expired lock leaves a counter ≥ threshold — that's what makes the next
+    // miss immediately re-lock (strict-semantic; see the type-comment above).
+    const ttlSec = Math.max(lockoutDurationMinutes * 60, 24 * 3600);
+
+    const count = await redis.incr(countKey(subjectId));
+    if (count === 1) {
+      // First failure → set the TTL. INCR doesn't set one; a counter without
+      // TTL would leak forever for subjects that never return.
+      await redis.expire(countKey(subjectId), ttlSec);
+    }
+
+    let lockedUntil: number | null = null;
+    if (count >= maxFailedAttempts) {
+      const computedUntil = Date.now() + lockDurationMs;
+      // NX: only set if no lock is currently armed. A second concurrent attempt
+      // arriving after the first crossed the threshold must NOT reset the
+      // timer — the lock window should align with the attempt that crossed,
+      // not the one that happened a millisecond later.
+      const setOk = await redis.set(
+        untilKey(subjectId),
+        String(computedUntil),
+        "PX",
+        lockDurationMs,
+        "NX",
+      );
+      if (setOk === "OK") {
+        lockedUntil = computedUntil;
+      } else {
+        // Another concurrent attempt already locked — read the authoritative
+        // timestamp so the returned state matches what a follow-up
+        // getState would see.
+        const existing = await redis.get(untilKey(subjectId));
+        lockedUntil = existing !== null ? Number(existing) : null;
+      }
+    }
+
+    return { failureCount: count, lockedUntil };
+  }
+
+  // Idempotent — deleting missing keys is a no-op, so a replayed clear just
+  // re-clears harmlessly.
+  async function clearState(redis: Redis, subjectId: string): Promise<void> {
+    await redis.del(countKey(subjectId), untilKey(subjectId));
+  }
+
+  return { getState, recordFailedAttempt, clearState };
+}

package/packages/bundled-features/src/shared/map-with-concurrency.ts

@@ -0,0 +1,38 @@
+// Bounded-concurrency map — runs `fn` over `items` with at most `limit`
+// calls in flight. `Promise.all(items.map(fn))` is unbounded (as many
+// calls as rows); a plain sequential loop caps concurrency at 1, which
+// under-uses a resource pool that allows more (e.g. PgKmsAdapter's
+// default `max: 4` — sequential decrypt-per-row leaves 3 pool slots idle
+// and turns each query into 2N serial round-trips instead of ~2N/4).
+// Order of `results` matches `items`, independent of completion order.
+// On rejection: the returned promise rejects with the first error, and
+// remaining workers stop claiming new items (`failed` flag). In-flight
+// calls already past the claim still run to completion (their promises
+// stay in the `Promise.all` array, so a later rejection can't surface as
+// an unhandled rejection — verified in `mapWithConcurrency.test.ts`).
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  let failed = false;
+  async function worker(): Promise<void> {
+    for (;;) {
+      // skip: another worker already failed — stop claiming new items.
+      if (failed) return;
+      const index = nextIndex++;
+      // skip: cursor exhausted, normal worker-loop exit
+      if (index >= items.length) return;
+      try {
+        results[index] = await fn(items[index] as T, index);
+      } catch (err) {
+        failed = true;
+        throw err;
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}

package/packages/bundled-features/src/shared/parent-visibility.ts

@@ -0,0 +1,104 @@
+import type { EventStoreExecutor, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  type EntityDefinition,
+  isUuid,
+  type Registry,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  NotFoundError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+
+// Keyed by definition identity, not by entity name — two test stacks can
+// register different EntityDefinitions under the same entity name.
+const executorsByEntity = new WeakMap<EntityDefinition, EventStoreExecutor>();
+
+// Postgres `serial` is int4; a larger digit string would raise 22003 (numeric
+// out of range) inside the write transaction instead of denying cleanly.
+const SERIAL_ID_MAX = 2_147_483_647;
+
+function idShapeMatchesEntity(entity: EntityDefinition, entityId: string): boolean {
+  if (entity.idType !== "serial") return isUuid(entityId);
+  return /^\d{1,10}$/.test(entityId) && Number(entityId) <= SERIAL_ID_MAX;
+}
+
+// Checks whether a client-supplied (entityType, entityId) host reference is one
+// the caller can see via that entity's own read path — tenant scope plus its
+// `access.read` ownership. Shared by every handler that attaches something to a
+// host entity the client names (add-note, assign-tag, remove-tag, set-folder,
+// clear-folder); those handlers deny with NotFoundError so the response never
+// doubles as an existence oracle.
+export async function parentRowIsVisible(
+  registry: Registry,
+  entityType: string,
+  entityId: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  // Default-deny: an entityType that names no registered entity has no read
+  // path to check visibility against, so it can never be a valid parent.
+  const entity = registry.getEntity(entityType);
+  if (!entity) return false;
+
+  // Mirrors the SQL gate, which drops join-row candidates for the same reason:
+  // resolving a host that is itself a join row would need recursive gating.
+  if (entity.parentRef !== undefined) return false;
+
+  // A malformed id would abort the write transaction on a Postgres cast
+  // error (22P02) instead of cleanly denying — reject it before it reaches
+  // the executor.
+  if (!idShapeMatchesEntity(entity, entityId)) return false;
+
+  let executor = executorsByEntity.get(entity);
+  if (!executor) {
+    executor = createEntityExecutor(entityType, entity).executor;
+    executorsByEntity.set(entity, executor);
+  }
+
+  return (await executor.detail({ id: entityId }, user, db)) !== null;
+}
+
+// Write-path half of the parentRef gate (fw#2766). Resolves the join entity's
+// own `parentRef` declaration from the registry — the same object the read
+// path's SQL gate reads — so the field names and the allowedTypes allowlist
+// exist in exactly one place instead of once per path.
+export async function joinRowParentIsVisible(
+  registry: Registry,
+  joinEntityName: string,
+  payload: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  const parentRef = registry.getEntity(joinEntityName)?.parentRef;
+  // A mount whose join entity lost its declaration can't derive a gate —
+  // deny rather than silently fall back to the pre-#2766 open behaviour.
+  if (parentRef === undefined) return false;
+
+  const entityType = payload[parentRef.entityTypeField];
+  const entityId = payload[parentRef.entityIdField];
+  if (typeof entityType !== "string" || typeof entityId !== "string") return false;
+  if (parentRef.allowedTypes !== undefined && !parentRef.allowedTypes.includes(entityType)) {
+    return false;
+  }
+
+  return parentRowIsVisible(registry, entityType, entityId, user, db);
+}
+
+// Write-handler gate over joinRowParentIsVisible: null means proceed, anything
+// else is returned as-is. The host reference is client input, so this must run
+// FIRST in the handler, ahead of every other lookup — a denied caller then
+// can't tell an invisible parent apart from a missing assignment or an unknown
+// tag/folder; every path answers with the same NotFoundError.
+export async function denyUnlessJoinRowParentVisible(
+  registry: Registry,
+  joinEntityName: string,
+  payload: { readonly entityType: string; readonly entityId: string },
+  user: SessionUser,
+  db: TenantDb,
+): Promise<WriteFailure | null> {
+  if (await joinRowParentIsVisible(registry, joinEntityName, payload, user, db)) return null;
+  return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
+}

package/packages/bundled-features/src/shared/password-hashing.ts

@@ -0,0 +1,55 @@
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
+
+// OWASP-recommended argon2id parameters (2024 guidance):
+//   memoryCost: 19 MiB, timeCost: 2, parallelism: 1
+// These strike a balance between login latency (~20ms on typical hardware)
+// and brute-force resistance. If hashing becomes a bottleneck, tune memoryCost
+// before parallelism — memory hardness is what defeats GPU attacks.
+//
+// algorithm: 2 = Argon2id (best of argon2i + argon2d).
+// We inline the numeric value instead of importing Algorithm because the
+// @node-rs/argon2 enum is const and breaks verbatimModuleSyntax imports.
+const HASH_OPTIONS = {
+  algorithm: 2,
+  memoryCost: 19456,
+  timeCost: 2,
+  parallelism: 1,
+} as const;
+
+// @wrapper-known semantic-alias
+export async function hashPassword(password: string): Promise<string> {
+  return argonHash(password, HASH_OPTIONS);
+}
+
+// Returns true if the password matches. Never throws on wrong passwords —
+// only on malformed hash strings (which would be a bug, not a login attempt).
+//
+// Two verifier paths:
+//   - argon2id (default, what `hashPassword` produces)
+//   - ASP.NET Core Identity V3 (verify-only, for legacy migrations from .NET
+//     stacks). Sniffed via the format marker; on a successful match the
+//     application can rehash to argon2 at the next password-change event.
+export async function verifyPassword(hashString: string, password: string): Promise<boolean> {
+  if (isIdentityV3Hash(hashString)) {
+    return verifyIdentityV3Hash(password, hashString);
+  }
+  try {
+    return await argonVerify(hashString, password);
+  } catch {
+    // argon2 throws on unparseable hash — treat as mismatch rather than 500
+    // to avoid revealing which accounts have corrupted stored hashes.
+    return false;
+  }
+}
+
+// Anti-enumeration timing equaliser (#774). The login handler runs this on
+// the no-user / no-hash path so a missing account costs the same argon2
+// latency as a real verify — otherwise response timing leaks whether an
+// email is registered. Derived from hashPassword once and cached, so it
+// always tracks HASH_OPTIONS; the password never matches, result discarded.
+let dummyHash: Promise<string> | undefined;
+export async function verifyDummyPassword(password: string): Promise<void> {
+  dummyHash ??= hashPassword("anti-enumeration-dummy");
+  await verifyPassword(await dummyHash, password);
+}

package/packages/bundled-features/src/shared/row-bound-grant.ts

@@ -0,0 +1,128 @@
+// A short-lived grant that lets a caller without a session perform exactly
+// one named operation on exactly one row — the shape behind
+// user-data-rights' confirm-deletion-by-token and any "you just created this
+// row, now enrich it" flow.
+//
+// The row's own anchor (a value that moves on when the row is consumed) is
+// mixed INTO the HMAC purpose rather than carried in the token. It must be
+// unique per cycle and never recur (request id, UUID, monotonic version): a
+// status can return to an earlier value and revive an old grant (ABA replay).
+// Verification recomputes it from the row's CURRENT anchor, so a replayed
+// token dies the moment the row moves on — single-use semantics without a
+// burn key or Redis. Minting and redeeming
+// share one purpose-building function so the two can't drift apart; that
+// coupling is the whole point of this module, since an unanchored purpose
+// silently degrades to a bearer token valid for the full TTL.
+//
+// Anchoring alone closes the replay window only AFTER the row has moved on.
+// Two requests redeeming the same grant simultaneously both read the live
+// anchor and both verify, so spending it is a separate, mandatory step:
+// `commitAnchor` must move the row on atomically (a conditional update on
+// the anchor) and report whether this caller was the one who did. Skipping
+// it is possible but has to be declared with a reason, the way the framework
+// handles escapeHatch — an undeclared skip is how a single-use grant quietly
+// becomes a bearer token for the length of its TTL. Put the actual write into
+// the same statement that spends the anchor: a write issued after `ok: true`
+// can lose its work to a crash while the grant is already burned.
+//
+// The subject is NOT secret: signToken puts it in the token body in the
+// clear. A grant on a row therefore exposes that row's id to whoever holds
+// the link. Where the id itself must stay hidden, use an opaque handle
+// (single-use-token-store) instead.
+
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type { Temporal } from "temporal-polyfill";
+import { peekTokenSubject, signToken, verifyToken } from "./signed-token.js";
+
+export type RowBoundGrantResult =
+  | { readonly ok: true; readonly subject: string; readonly expiresAtMs: number }
+  | { readonly ok: false };
+
+// Atomically spends the anchor: must return true only for the single caller
+// that moved the row on from `expectedAnchor`, false for everyone else. A
+// plain "read, check, then write" is not enough — two requests redeeming the
+// same grant at once both read the live anchor and both pass.
+export type AnchorCommit =
+  | ((subject: string, expectedAnchor: string) => Promise<boolean>)
+  | { readonly unsafeSkip: { readonly reason: string } };
+
+const log = createFallbackLogger("row-bound-grant");
+
+const FAILED: RowBoundGrantResult = { ok: false };
+
+function anchoredPurpose(purpose: string, anchor: string): string {
+  return `${purpose}:${anchor}`;
+}
+
+export function signRowBoundGrant(args: {
+  readonly subject: string;
+  readonly purpose: string;
+  readonly anchor: string;
+  readonly ttlMinutes: number;
+  readonly secret: string;
+  readonly now?: Temporal.Instant;
+}): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  return signToken(
+    args.subject,
+    anchoredPurpose(args.purpose, args.anchor),
+    args.ttlMinutes,
+    args.secret,
+    args.now,
+  );
+}
+
+// Every rejection returns the same bare `{ ok: false }` — no reason, by
+// design. A caller that could tell "bad signature" from "no such row" would
+// hand an attacker a row-existence oracle on an endpoint that is open to
+// anonymous callers.
+export async function redeemRowBoundGrant(args: {
+  readonly token: string;
+  readonly purpose: string;
+  readonly secret: string | undefined;
+  readonly loadAnchor: (subject: string) => Promise<string | null>;
+  readonly commitAnchor: AnchorCommit;
+  readonly now?: Temporal.Instant;
+}): Promise<RowBoundGrantResult> {
+  // Misconfiguration must throw on every call, not only on the first valid redemption.
+  if (typeof args.commitAnchor !== "function" && !args.commitAnchor.unsafeSkip.reason.trim()) {
+    throw new Error("row-bound grant: unsafeSkip needs a non-empty reason");
+  }
+  if (!args.secret) return FAILED;
+
+  const subject = peekTokenSubject(args.token);
+  if (!subject) return FAILED;
+
+  // The subject is unverified attacker input at this point, so a lookup that
+  // throws on it (e.g. a non-uuid value against a uuid column) must not
+  // surface as a 500.
+  let anchor: string | null;
+  try {
+    anchor = await args.loadAnchor(subject);
+  } catch (error) {
+    // Name/code only: driver messages can echo the attacker-supplied subject.
+    // Logged so an infrastructure outage doesn't look like an expired link.
+    log.warn("row-bound grant anchor lookup failed", {
+      errorName: error instanceof Error ? error.name : typeof error,
+      code: error instanceof Error && "code" in error ? String(error.code) : undefined,
+    });
+    return FAILED;
+  }
+  if (!anchor) return FAILED;
+
+  const verified = verifyToken(
+    args.token,
+    anchoredPurpose(args.purpose, anchor),
+    args.secret,
+    args.now,
+  );
+  if (!verified.ok) return FAILED;
+
+  // Spending happens after verification, never before: a caller that burned
+  // the anchor on an unverified token could invalidate any row it can name.
+  if (typeof args.commitAnchor === "function") {
+    const spent = await args.commitAnchor(subject, anchor);
+    if (!spent) return FAILED;
+  }
+
+  return { ok: true, subject, expiresAtMs: verified.expiresAtMs };
+}

package/packages/bundled-features/src/shared/run-in-sub-transaction.ts

@@ -0,0 +1,35 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+// Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
+//   - top-level connection (Bun.SQL / postgres-js Sql) → `.begin` (BEGIN)
+//   - TransactionSql (inside the dispatcher's outer tx, where every
+//     writeHandler already runs) → `.savepoint` (SAVEPOINT)
+// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
+// threw "is not a function" on every user when invoked through the dispatcher
+// (the cron path) → zero deletions in production, while direct-connection tests
+// stayed green. Selecting the available method makes the sub-tx work in both
+// contexts; on throw the savepoint rolls back just this user (others survive).
+export async function runInSubTransaction<T>(
+  db: DbRunner,
+  fn: (tx: DbRunner) => Promise<T>,
+): Promise<T> {
+  // `db` is already the raw runner (the handler passes ctx.db.unsafeRaw(...),
+  // the tests a top-level connection) — cast to read the transaction surface directly,
+  // without asRawClient (a test-only escape hatch).
+  const runner = db as {
+    begin?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
+    savepoint?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
+  };
+  // savepoint-first: empirically (Bun 1.3.14, not re-checked on 1.4.0) the
+  // surfaces are NOT mutually exclusive — a TransactionSql exposes begin AND
+  // savepoint, only the top-level connection has begin alone. begin-first
+  // picked the nested BEGIN inside a tx (the incident class above);
+  // savepoint-first hits the savepoint there and falls back to begin top-level.
+  const open = runner.savepoint ?? runner.begin;
+  if (!open) {
+    throw new Error(
+      "runInSubTransaction: db exposes neither .begin nor .savepoint — cannot open a sub-transaction",
+    );
+  }
+  return open.call(runner, fn);
+}

package/packages/bundled-features/src/shared/session-locale-field.ts

@@ -0,0 +1,9 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { canonicalizeLocaleTag, isValidLocaleTag } from "@cosmicdrift/kumiko-framework/i18n";
+
+export function sessionLocaleField(
+  locale: string | null | undefined,
+): Pick<SessionUser, "locale"> | Record<string, never> {
+  if (locale === null || locale === undefined || !isValidLocaleTag(locale)) return {};
+  return { locale: canonicalizeLocaleTag(locale) };
+}

package/packages/bundled-features/src/shared/session-timezone-field.ts

@@ -0,0 +1,8 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+
+export function sessionTimezoneField(
+  timezone: string | null | undefined,
+): Pick<SessionUser, "timezone"> | Record<string, never> {
+  if (timezone === null || timezone === undefined) return {};
+  return { timezone };
+}