@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/sessions/session-callbacks.ts

@@ -0,0 +1,302 @@
+import type {
+  AuthSessionCheckResult,
+  SessionChecker,
+  SessionCreator,
+  SessionMassRevoker,
+  SessionMetadata,
+  SessionRevoker,
+} from "@cosmicdrift/kumiko-framework/api";
+
+export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
+
+import { fetchOne, insertOne, transaction, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { buildSessionRoles, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId, parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "temporal-polyfill";
+import { encryptForDirectWrite } from "../shared/index.js";
+import { tenantMembershipsTable } from "../tenant/index.js";
+import { isPrincipalBlocked, type UserStatus, userTable } from "../user/index.js";
+import {
+  DEFAULT_SESSION_EXPIRY_MS,
+  LAST_SEEN_REFRESH_MS,
+  USER_SESSION_ENTITY_NAME,
+} from "./constants.js";
+import { userSessionEntity, userSessionTable } from "./schema/user-session.js";
+import {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  sessionRevokedSchema,
+} from "./session-revoked-event.js";
+
+// Re-exported so existing `../sessions` importers keep working unchanged.
+export { isPrincipalBlocked };
+
+// Why the callbacks live at the raw-DB level rather than going through the
+// dispatcher: session-create/revoke/check run on the hot path of every
+// login and every request. The (createdAt/revokedAt/ip/userAgent) columns
+// already are the audit trail — a dispatcher roundtrip buys nothing.
+
+// "Sign out everywhere else, keep this one" — used both by the user-facing
+// revoke-all-others handler and by other features (auth-mfa) that need the
+// same effect from a raw callback instead of a dispatcher round-trip.
+// currentSid undefined (stateless-JWT / no sid claim) revokes everything —
+// there is no "current" row to spare.
+export type SessionAllOthersRevoker = (
+  userId: string,
+  currentSid: string | undefined,
+) => Promise<number>;
+
+export type SessionCallbacksOptions = {
+  readonly db: DbConnection;
+  // Session lifetime. MVP uses a single flat window; per-app policies can
+  // come later (e.g. longer for "remember me", shorter for admin).
+  readonly expiresInMs?: number;
+};
+
+export type SessionCallbacks = {
+  sessionCreator: SessionCreator;
+  sessionRevoker: SessionRevoker;
+  sessionChecker: SessionChecker;
+  sessionMassRevoker: SessionMassRevoker;
+  sessionRevokeAllOthers: SessionAllOthersRevoker;
+};
+
+export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCallbacks {
+  const ttlMs = opts.expiresInMs ?? DEFAULT_SESSION_EXPIRY_MS;
+  const { db } = opts;
+
+  return {
+    async sessionCreator(user: SessionUser, meta: SessionMetadata): Promise<string> {
+      const sid = generateId();
+      const now = Temporal.Now.instant();
+      const expiresAt = now.add({ milliseconds: ttlMs });
+      await insertOne(
+        db,
+        userSessionTable,
+        await encryptForDirectWrite(
+          userSessionEntity,
+          USER_SESSION_ENTITY_NAME,
+          {
+            id: sid,
+            tenantId: user.tenantId,
+            userId: user.id,
+            createdAt: now,
+            expiresAt,
+            lastSeenAt: now,
+            ip: meta.ip,
+            userAgent: meta.userAgent,
+          },
+          "sessions:create",
+        ),
+      );
+      return sid;
+    },
+
+    async sessionRevoker(sid: string): Promise<void> {
+      // Audit-preserving: `isNull(revokedAt)` in WHERE means a second call
+      // on an already-revoked sid is a no-op instead of overwriting the
+      // original timestamp. Double-revoke races land here via logout +
+      // switch-tenant on the same sid. (Password-change uses a different
+      // callback — sessionMassRevoker — and isn't in scope for this guard.)
+      // One transaction: if the append failed after the update committed, a
+      // retried logout would match no live row (revokedAt IS NULL) and never
+      // emit the event, leaving the SSE stream of this sid open until JWT expiry.
+      await transaction(db, async (tx) => {
+        const result = await updateMany<{ userId: string }>(
+          tx,
+          userSessionTable,
+          { revokedAt: Temporal.Now.instant() },
+          { id: sid, revokedAt: null },
+        );
+
+        // This is the ONLY caller of sessionRevoker — logout and tenant-switch
+        // — so it's also the only source of streamScope: "revoked-sessions".
+        // Without this append, a live SSE stream on this exact sid outlives its
+        // own logout because the access-invalidation consumer never hears
+        // about it — same gap sessionMassRevoker closed for
+        // password-change.
+        const revoked = result[0];
+        if (revoked) {
+          const payload = sessionRevokedSchema.parse({
+            userId: revoked.userId,
+            sessionIds: [sid],
+            streamScope: "revoked-sessions",
+          });
+          await append(tx, {
+            aggregateId: generateId(),
+            aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+            tenantId: SYSTEM_TENANT_ID,
+            expectedVersion: 0,
+            type: SESSION_REVOKED_EVENT_QN,
+            payload,
+            metadata: { userId: revoked.userId },
+          });
+        }
+      });
+    },
+
+    // kumiko-lint-ignore complexity-budget session check + lastSeen refresh on hot path
+    async sessionChecker(sid: string, expectedUserId: string): Promise<AuthSessionCheckResult> {
+      const row = await fetchOne<{
+        userId: string;
+        tenantId: TenantId;
+        revokedAt: unknown;
+        expiresAt: { epochMilliseconds: number };
+        lastSeenAt: { epochMilliseconds: number } | null;
+      }>(db, userSessionTable, { id: sid });
+      if (!row) return "missing";
+      // Cross-user check: if the sid belongs to someone else, treat it
+      // identically to "missing" so a compromised sid paired with a valid
+      // JWT from a different user gets the same opaque response as a
+      // forged sid. No existence oracle on other users' sids.
+      if (row.userId !== expectedUserId) return "missing";
+      if (row.revokedAt !== null) return "revoked";
+      // Temporal-native clock read (Sprint F migration) — keeps the feature
+      // free of raw Date.now() for consistency with the rest of the codebase.
+      if (row.expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds) {
+        return "expired";
+      }
+
+      // Hourly, not per-request: this check runs on every authenticated
+      // request, so a write here has to stay off the hot path.
+      const nowMs = Temporal.Now.instant().epochMilliseconds;
+      if (!row.lastSeenAt || row.lastSeenAt.epochMilliseconds + LAST_SEEN_REFRESH_MS <= nowMs) {
+        try {
+          await updateMany(
+            db,
+            userSessionTable,
+            { lastSeenAt: Temporal.Now.instant() },
+            { id: sid },
+          );
+        } catch {
+          // fail-open: a refresh failure must not block the session check
+        }
+      }
+
+      // Defense-in-depth: status flips (Art. 18 restrict, forget) revoke
+      // sessions, but a missed revoke must not keep a locked account alive on
+      // a stale sid. Fail-OPEN on a lookup miss — this is the second layer,
+      // revocation is primary; never turn a user-row miss into a global
+      // lockout. (+1 PK read on read_users per authenticated request.)
+      //
+      // Fail-open covers a THROW *and* a null-miss, not just a throw: this
+      // read sits on the hot path of every authenticated request, and a
+      // missing row here means we have no DB-confirmed roles to derive from
+      // (e.g. a bootstrap/system actor with no persisted user row) — that is
+      // a different situation from tenantMembershipsTable below, where a
+      // missing row is a legitimate "no tenant roles" outcome. Both branches
+      // return the bare "live" string (no re-derived roles) — the middleware
+      // falls back to the JWT's frozen roles claim.
+      let user: { status: UserStatus; roles: string | null } | undefined;
+      try {
+        user = await fetchOne<{ status: UserStatus; roles: string | null }>(db, userTable, {
+          id: expectedUserId,
+        });
+      } catch {
+        return "live";
+      }
+      if (!user) return "live";
+      if (isPrincipalBlocked(user.status)) return "blocked";
+
+      // Same fail-open reasoning as the userTable lookup above — a transient
+      // DB error on the membership read must not lock the user out. A
+      // missing row (not a throw) is a valid outcome: the user genuinely has
+      // no tenant-scoped roles for row.tenantId, so membershipRoles is [].
+      let membershipRoles: readonly string[];
+      try {
+        const membership = await fetchOne<{ roles: string | null }>(db, tenantMembershipsTable, {
+          userId: expectedUserId,
+          tenantId: row.tenantId,
+        });
+        membershipRoles = membership ? parseRoles(membership.roles) : [];
+      } catch {
+        return "live";
+      }
+
+      const globalRoles = parseRoles(user.roles);
+      const roles = buildSessionRoles(globalRoles, membershipRoles);
+      return { status: "live", roles } as const;
+    },
+
+    async sessionMassRevoker(userId: string): Promise<number> {
+      // Count is accurate because we only touch live rows — a previously
+      // revoked row stays in its state and isn't double-counted.
+      // One transaction, same reason as sessionRevoker: a failed append must
+      // not leave sessions revoked without the event.
+      return transaction(db, async (tx) => {
+        const result = await updateMany(
+          tx,
+          userSessionTable,
+          { revokedAt: Temporal.Now.instant() },
+          { userId, revokedAt: null },
+        );
+
+        // Lightweight append alongside the direct-write above, same pattern
+        // as revoke.write.ts (#1559) — this callback is the password-change
+        // auto-revoke path (sessions/feature.ts postSave hook) and has no
+        // dispatcher ctx to call unsafeAppendEvent from, so it uses the raw
+        // append() like revoke-all-for-user.write.ts does. Without this, the
+        // access-invalidation consumer (#1560) never hears about a password
+        // change and an already-open SSE stream survives it — the exact
+        // "stale JWT mid-stream" gap this feature exists to close.
+        if (result.length > 0) {
+          const payload = sessionRevokedSchema.parse({
+            userId,
+            sessionIds: result.map((row: { id: string }) => row.id),
+          });
+          await append(tx, {
+            aggregateId: generateId(),
+            aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+            tenantId: SYSTEM_TENANT_ID,
+            expectedVersion: 0,
+            type: SESSION_REVOKED_EVENT_QN,
+            payload,
+            metadata: { userId },
+          });
+        }
+
+        return result.length;
+      });
+    },
+
+    async sessionRevokeAllOthers(userId: string, currentSid: string | undefined): Promise<number> {
+      return transaction(db, async (tx) => {
+        const result = await updateMany(
+          tx,
+          userSessionTable,
+          { revokedAt: Temporal.Now.instant() },
+          currentSid
+            ? { userId, revokedAt: null, id: { ne: currentSid } }
+            : { userId, revokedAt: null },
+        );
+
+        // Same reasoning as sessionMassRevoker above — this raw callback
+        // (used by auth-mfa and other internal callers, distinct from the
+        // user-facing revoke-all-others.write.ts handler which already
+        // appends this event) needs its own append so callers reached
+        // through here also cut open SSE streams.
+        if (result.length > 0) {
+          const payload = sessionRevokedSchema.parse({
+            userId,
+            sessionIds: result.map((row: { id: string }) => row.id),
+            keptSessionId: currentSid,
+          });
+          await append(tx, {
+            aggregateId: generateId(),
+            aggregateType: SESSION_REVOKED_AGGREGATE_TYPE,
+            tenantId: SYSTEM_TENANT_ID,
+            expectedVersion: 0,
+            type: SESSION_REVOKED_EVENT_QN,
+            payload,
+            metadata: { userId },
+          });
+        }
+
+        return result.length;
+      });
+    },
+  };
+}

package/packages/bundled-features/src/sessions/session-revoked-event.ts

@@ -0,0 +1,37 @@
+import * as z from "zod";
+
+// Lightweight custom event appended alongside the direct-write
+// updateMany() in revoke.write.ts / revoke-all-others.write.ts /
+// revoke-all-for-user.write.ts (#1559). store_user_sessions itself stays
+// an unmanaged direct-write store (see feature.ts) — the row columns are
+// the audit trail, this event is NOT a CRUD/lifecycle event for that
+// table and carries no projection. Its only job is to give cross-instance
+// consumers (access-invalidation, #1560) something to LISTEN for via the
+// existing event-store NOTIFY, keyed by the affected userId.
+//
+// _SHORT/_QN pair mirrors cap-counter's rolling-incremented event:
+//   _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes
+//            it to the QN below.
+//   _QN    — ctx.unsafeAppendEvent({ type }) / raw append()'s `type` field.
+export const SESSION_REVOKED_EVENT_SHORT = "session-revoked" as const;
+export const SESSION_REVOKED_EVENT_QN = "sessions:event:session-revoked" as const;
+
+// Own aggregate type, decoupled from userSessionEntity's implicit
+// "user-session" — each revoke action mints a fresh aggregate id (no
+// predecessor to satisfy, no version_conflict against concurrent revokes).
+export const SESSION_REVOKED_AGGREGATE_TYPE = "user-session-revocation" as const;
+
+export const sessionRevokedSchema = z.object({
+  userId: z.string().min(1),
+  sessionIds: z.array(z.uuid()).min(1),
+  // The caller's own session a "revoke all others" write spared. Optional so
+  // events appended before it existed still replay.
+  keptSessionId: z.uuid().optional(),
+  // Set only by the raw sessionRevoker callback (logout / tenant-switch) —
+  // tells the access-invalidation consumer to close exactly `sessionIds`
+  // instead of the userwide default every other source keeps using.
+  // Optional so events appended before it existed still replay unscoped.
+  streamScope: z.literal("revoked-sessions").optional(),
+});
+
+export type SessionRevokedPayload = z.infer<typeof sessionRevokedSchema>;

package/packages/bundled-features/src/sessions/testing.ts

@@ -0,0 +1,55 @@
+// Testing helpers for the sessions feature. The factory below turns a
+// `LateBoundHolder<SessionCallbacks>` into the two shapes a test needs:
+//
+//   const holder = createLateBoundHolder<SessionCallbacks>("session-callbacks");
+//   const bound = sessionCallbacksFromLateBound(holder);
+//
+//   stack = await setupTestStack({
+//     features: [..., createSessionsFeature({
+//       autoRevokeOnPasswordChange: bound.asMassRevoker(),
+//     })],
+//     authConfig: { ...bound.asAuthConfig(), membershipQuery, loginHandler },
+//   });
+//   holder.set(createSessionCallbacks({ db: stack.db }));
+//
+// Why the helper lives in bundled-features/sessions rather than framework/testing:
+// it closes over `AuthRoutesConfig` + `SessionCallbacks`, both of which the
+// sessions feature owns. framework/testing only provides the generic
+// `createLateBoundHolder<T>` — shape-independent.
+
+import type { AuthRoutesConfig, SessionCreator } from "@cosmicdrift/kumiko-framework/api";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { LateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import type { SessionCallbacks, SessionMassRevoker } from "./session-callbacks.js";
+
+export type BoundSessionCallbacks = {
+  /** auth-config fragment: creator + revoker + checker, all late-bound. */
+  asAuthConfig(): Pick<AuthRoutesConfig, "sessionCreator" | "sessionRevoker" | "sessionChecker">;
+  /** mass-revoker function for sessionsFeature({ autoRevokeOnPasswordChange }). */
+  asMassRevoker(): SessionMassRevoker;
+};
+
+export function sessionCallbacksFromLateBound(
+  holder: LateBoundHolder<SessionCallbacks>,
+): BoundSessionCallbacks {
+  return {
+    asAuthConfig: () => ({
+      sessionCreator: (user, meta) => holder.get().sessionCreator(user, meta),
+      sessionRevoker: (sid) => holder.get().sessionRevoker(sid),
+      sessionChecker: (sid, userId) => holder.get().sessionChecker(sid, userId),
+    }),
+    asMassRevoker: () => (userId) => holder.get().sessionMassRevoker(userId),
+  };
+}
+
+// Bootstrap actors (system-admin seed writes) need a real sid once a
+// sessionChecker is wired — auth-middleware rejects sidless JWTs as
+// forged/pre-session-tracking. Mints a live session row and returns the
+// actor with `sid` attached so `stack.http.writeOk(..., actor)` passes.
+export async function withMintedSession(
+  sessionCreator: SessionCreator,
+  user: SessionUser,
+): Promise<SessionUser> {
+  const sid = await sessionCreator(user, { ip: "127.0.0.1", userAgent: "test" });
+  return { ...user, sid };
+}

package/packages/bundled-features/src/shared/assert-erased.ts

@@ -0,0 +1,26 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+
+// GDPR-forget hooks used to `await crud.forget(...)` and drop the result —
+// a silent ownership_denied (or any other failure) meant the row was never
+// actually erased, with nothing surfacing the miss. Callers must collect the
+// failure of every row (so one bad row does not leave the rest of the
+// subject's rows untried) and throw once after the loop.
+export function collectErasureFailure(
+  result: WriteResult<unknown>,
+  entityName: string,
+  id: string,
+  failures: string[],
+): void {
+  // skip: the happy path — the collection below only concerns failures.
+  if (result.isSuccess) return;
+  // skip: erasure is idempotent — a row that is already gone (e.g. a parallel
+  // forget sweep) satisfies the erase request just as well as one this call removed.
+  if (result.error.code === "not_found") return;
+  failures.push(`${entityName}/${id}: ${result.error.code} — ${result.error.message}`);
+}
+
+export function throwIfErasureFailed(failures: readonly string[]): void {
+  // skip: nothing failed, so there is nothing to report
+  if (failures.length === 0) return;
+  throw new Error(`[user-data-rights] failed to erase ${failures.join("; ")}`);
+}

package/packages/bundled-features/src/shared/changes.json

@@ -0,0 +1,14 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Row-bound grant redemption logs a failing anchor lookup instead of swallowing it silently",
+    "detail": "`redeemRowBoundGrant` now logs a warning (error name and code only, never the token or subject) when the anchor lookup throws, so a database outage no longer looks like an expired link. The result is still the same bare rejection."
+  },
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "row-bound grants: one short-lived, single-use capability for anonymous writes on one row",
+    "detail": "`signed-token.ts` moves from `auth-email-password/` to `shared/` — the mechanism\nwas never email/password specific (user-data-rights already used it). The old\npath re-exports it, so no importer breaks. New subpaths:\n`./shared/signed-token` and `./shared/row-bound-grant`.\n`shared/row-bound-grant.ts` is the new piece. It folds the row's *current*\nanchor (a request id, a status, a version — anything that moves on when the row\nis consumed) into the HMAC purpose on both mint and redeem, so a replayed token\nstops working the moment the row moves on. Single-use semantics without a burn\nkey and without Redis. Minting and redeeming share one purpose-building\nfunction, because an unanchored purpose silently degrades into a bearer token\nvalid for the whole TTL.\nAnchoring alone only closes the replay window once the row has moved on, so\nspending the anchor is part of the primitive, not homework for the caller:\n`redeemRowBoundGrant` takes a mandatory `commitAnchor(subject, expectedAnchor)`\nthat must move the row on atomically (a conditional UPDATE) and report whether\nthis caller won. It runs strictly after verification, so nobody can invalidate a\nrow by naming it with a junk token, and the loser of a race gets the same\nrejection as a forged grant. Skipping it is possible but has to be declared with\na reason (`{ unsafeSkip: { reason } }`), the way the framework handles\n`escapeHatch` — an undeclared skip is how a single-use grant quietly becomes a\nbearer token for the length of its TTL.\nEvery rejection returns a bare `{ ok: false }` with no reason, so a caller\ncannot accidentally turn an anonymous endpoint into a row-existence oracle.\n`user-data-rights`' deletion token now runs on the helper and its hand-rolled\n`peekDeletionTokenUserId` is gone. The tokens stay byte-compatible — a test\npins the wire format against the pre-refactor formula. It declares an\n`unsafeSkip` for the spend: `pendingDeletionRequestId` may only change through\n`updateUserLifecycle`, so a conditional UPDATE there would lose the field on a\nprojection rebuild. Behaviour of that flow is unchanged.\nNote for callers: the subject is not secret. `signToken` puts it in the token\nbody in the clear, so a grant on a row exposes that row's id to whoever holds\nthe link. Where the id itself must stay hidden, use an opaque handle\n(`./shared/single-use-token-store`) instead."
+  }
+]

package/packages/bundled-features/src/shared/chunked-entity-migration.ts

@@ -0,0 +1,89 @@
+// Shared loop for chunked, idempotent row migrations (secrets KEK rotation,
+// config re-encrypt, future entity-field re-encrypts). Owns the operational
+// mechanics — abort signal, deadline, failure circuit-breaker, batch
+// accounting — while the caller owns the domain: what a batch is and how a
+// single row migrates.
+//
+// Contract notes:
+//   - nextBatch() returning an empty array ends the run ("done"). Callers
+//     whose batch query re-evaluates (WHERE kek_version != current) converge
+//     naturally; full-scan callers return their one batch, then [].
+//   - migrateRow returns "migrated" | "skipped" (already current, lost a
+//     version_conflict race) | "failed" (counted against maxFailures);
+//     throws count as "failed" too and go through onRowError.
+//   - Rows that keep failing MAY be re-served by a re-evaluating nextBatch —
+//     the circuit-breaker (maxFailures) is what terminates that loop, same
+//     semantics the secrets rotate job always had.
+
+export type MigrationRowOutcome = "migrated" | "skipped" | "failed";
+
+export type ChunkedMigrationStopReason = "done" | "timeout" | "signal" | "too_many_failures";
+
+export type ChunkedMigrationResult = {
+  readonly migrated: number;
+  readonly skipped: number;
+  readonly failed: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: ChunkedMigrationStopReason;
+};
+
+export type ChunkedMigrationOptions<Row> = {
+  readonly nextBatch: () => Promise<readonly Row[]>;
+  readonly migrateRow: (row: Row) => Promise<MigrationRowOutcome>;
+  readonly maxFailures: number;
+  // Epoch ms; Number.POSITIVE_INFINITY for no time bound.
+  readonly deadlineAt: number;
+  readonly signal?: AbortSignal | undefined;
+  readonly onRowError?: (row: Row, err: unknown) => void;
+};
+
+export async function runChunkedMigration<Row>(
+  opts: ChunkedMigrationOptions<Row>,
+): Promise<ChunkedMigrationResult> {
+  let migrated = 0;
+  let skipped = 0;
+  let failed = 0;
+  let batchesProcessed = 0;
+  let stoppedReason: ChunkedMigrationStopReason = "done";
+
+  outer: while (true) {
+    if (opts.signal?.aborted) {
+      stoppedReason = "signal";
+      break;
+    }
+    if (Date.now() >= opts.deadlineAt) {
+      stoppedReason = "timeout";
+      break;
+    }
+
+    const batch = await opts.nextBatch();
+    if (batch.length === 0) break;
+
+    if (failed >= opts.maxFailures) {
+      stoppedReason = "too_many_failures";
+      break;
+    }
+
+    batchesProcessed++;
+
+    for (const row of batch) {
+      if (failed >= opts.maxFailures) {
+        stoppedReason = "too_many_failures";
+        break outer;
+      }
+      let outcome: MigrationRowOutcome;
+      try {
+        outcome = await opts.migrateRow(row);
+      } catch (err) {
+        opts.onRowError?.(row, err);
+        failed++;
+        continue;
+      }
+      if (outcome === "migrated") migrated++;
+      else if (outcome === "skipped") skipped++;
+      else failed++;
+    }
+  }
+
+  return { migrated, skipped, failed, batchesProcessed, stoppedReason };
+}

package/packages/bundled-features/src/shared/classify-stored-envelope.ts

@@ -0,0 +1,21 @@
+import { isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
+
+export type StoredEnvelopeClassification = "rotate" | "current" | "unrecognized";
+
+// Shared by every KEK-rotation job (config, auth-mfa, ...): a row whose value
+// isn't a current-cipher envelope (malformed JSON, or any pre-envelope
+// format) is never a supported re-encrypt input — classify it "unrecognized"
+// so callers fail it loudly instead of handing it to cipher.decrypt.
+export function classifyStoredEnvelope(
+  value: string,
+  targetVersion: number,
+): StoredEnvelopeClassification {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return "unrecognized";
+  }
+  if (!isStoredEnvelope(parsed)) return "unrecognized";
+  return parsed.kekVersion === targetVersion ? "current" : "rotate";
+}

package/packages/bundled-features/src/shared/decrypt-stored-pii.ts

@@ -0,0 +1,26 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+
+// Raw reads (fetchOne/selectMany) return the stored column value — with an
+// active KMS that is ciphertext (self-describing: it names its own subject,
+// so no entity/field context is needed for key selection). `field` must
+// still match the field name used at encrypt time — it is part of the
+// AAD (#1263), so a mismatch fails decrypt loud rather than silently
+// letting ciphertext cut-and-pasted from another field decrypt. An erased
+// subject yields the sentinel, which matches no real value.
+export async function decryptStoredPii(
+  value: string,
+  field: string,
+  fallbackRequestId: string,
+): Promise<string> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return value;
+  const out = await decryptPiiFieldValues({ [field]: value }, [field], kms, {
+    requestId: requestContext.get()?.requestId ?? fallbackRequestId,
+  });
+  const decrypted = out[field];
+  return typeof decrypted === "string" ? decrypted : value;
+}

package/packages/bundled-features/src/shared/encrypt-for-direct-write.ts

@@ -0,0 +1,29 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+// Unmanaged direct-write stores (r.unmanagedTable) skip the executor, so its
+// PII encryption never runs — every insert of subject-annotated fields must
+// go through this instead, and the feature declares { piiEncryptedOnWrite:
+// true } at the registration site (enforced by the registry, #820).
+export async function encryptForDirectWrite(
+  entity: EntityDefinition,
+  entityName: string,
+  row: Record<string, unknown>,
+  fallbackRequestId: string,
+): Promise<Record<string, unknown>> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return row;
+  return encryptPiiFieldValues(
+    row,
+    entity,
+    collectPiiSubjectFields(entity),
+    kms,
+    { requestId: requestContext.get()?.requestId ?? fallbackRequestId },
+    { entityName },
+  );
+}

package/packages/bundled-features/src/shared/entities-of.ts

@@ -0,0 +1,17 @@
+import type { EntityDefinition, FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+// r.entity(...) is not the only way a feature exposes an entity shape:
+// r.projection(...) can carry an optional `entity` too (raw read-models with
+// no executor, e.g. billing-foundation's subscription table). Boot-check
+// gates need every entity a feature declares, not just the r.entity ones, or
+// a pii/tenantOwned/userOwned field on a projection-only entity is invisible
+// to the guard it was annotated for.
+export function entitiesOf(
+  feature: FeatureDefinition,
+): ReadonlyArray<readonly [string, EntityDefinition]> {
+  const fromEntities = Object.entries(feature.entities ?? {});
+  const fromProjections = Object.values(feature.projections ?? {})
+    .filter((p): p is typeof p & { entity: EntityDefinition } => p.entity !== undefined)
+    .map((p) => [p.name, p.entity] as const);
+  return [...fromEntities, ...fromProjections];
+}

package/packages/bundled-features/src/shared/grace-period.ts

@@ -0,0 +1,21 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+/** Shared grace-period check for user-data-rights + tenant-lifecycle cancel flows. */
+
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+
+/**
+ * True when `gracePeriodEnd` is still in the future.
+ * Uses the polyfill Instant API so callers don't depend on `globalThis.Temporal`.
+ */
+export function isWithinGracePeriod(gracePeriodEnd: Temporal.Instant | null): boolean {
+  // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+  // at runtime — row types resolve against ambient Temporal; polyfill Instant
+  // is a separate nominal type across the two .d.ts sources.
+  return (
+    gracePeriodEnd != null &&
+    TemporalPolyfill.Instant.compare(
+      gracePeriodEnd as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
+      TemporalPolyfill.Now.instant(),
+    ) > 0
+  );
+}

package/packages/bundled-features/src/shared/has-where-rule.ts

@@ -0,0 +1,11 @@
+import type { OwnershipMap } from "@cosmicdrift/kumiko-framework/engine";
+
+// `where`-rules are read-path only (buildOwnershipClause). The write path
+// decides in memory against the concrete row, so a where-rule there can only
+// ever deny — boot validation rejects the shape (fw#2626). Feature factories
+// that accept an `ownership` option reject it earlier, at build time, so the
+// author gets the option name in the message instead of an entity scope.
+export function hasWhereRule(map: OwnershipMap | undefined): boolean {
+  if (!map) return false;
+  return Object.values(map).some((rule) => rule !== "all" && rule.kind === "where");
+}