@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/sessions/screens.d.ts

@@ -0,0 +1,4 @@
+import { type ProjectionDetailScreenDefinition, type ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare const sessionListScreen: ProjectionListScreenDefinition;
+export declare const sessionDetailScreen: ProjectionDetailScreenDefinition;
+export declare const sessionMineScreen: ProjectionListScreenDefinition;

package/dist/sessions/screens.js

@@ -0,0 +1,136 @@
+import { access, i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
+import { SESSION_DETAIL_SCREEN_ID, SESSION_LIST_SCREEN_ID, SESSION_MINE_SCREEN_ID, SessionHandlers, SessionQueries, } from "./constants.js";
+const listAccess = { roles: access.admin };
+export const sessionListScreen = {
+    id: SESSION_LIST_SCREEN_ID,
+    type: "projectionList",
+    query: SessionQueries.list,
+    // Mirrors list.query's own fallback (unrecognised/absent sort → createdAt
+    // desc) — kept in sync by hand, boot-validator only requires the field
+    // be present once the query accepts `sort` (fw#2230).
+    defaultSort: { field: "createdAt", dir: "desc" },
+    columns: [
+        { field: "id", label: i18nKey("sessions.list.col.id") },
+        {
+            field: "userId",
+            label: i18nKey("sessions.list.col.userId"),
+            refEntity: "user:user",
+            refLabelField: "displayName",
+        },
+        {
+            field: "createdAt",
+            label: i18nKey("sessions.list.col.createdAt"),
+            renderer: { format: "timestamp" },
+        },
+        {
+            field: "expiresAt",
+            label: i18nKey("sessions.list.col.expiresAt"),
+            renderer: { format: "timestamp" },
+        },
+        {
+            field: "revokedAt",
+            label: i18nKey("sessions.list.col.revokedAt"),
+            renderer: { format: "timestamp" },
+        },
+    ],
+    rowActions: [
+        {
+            kind: "navigate",
+            id: "open",
+            label: i18nKey("sessions.list.action.open"),
+            screen: SESSION_DETAIL_SCREEN_ID,
+            entityId: "id",
+            rowClick: true,
+        },
+    ],
+    access: listAccess,
+};
+export const sessionDetailScreen = {
+    id: SESSION_DETAIL_SCREEN_ID,
+    type: "projectionDetail",
+    query: SessionQueries.detail,
+    listScreenId: SESSION_LIST_SCREEN_ID,
+    layout: {
+        sections: [
+            {
+                fields: [
+                    "id",
+                    { field: "userId", refEntity: "user:user", refLabelField: "displayName" },
+                    // The shim (projection-detail-shim.ts) stamps every field as
+                    // type:"text" — field.renderer is the only way this screen
+                    // type reaches real per-type formatting instead of a raw ISO
+                    // string (fw#2245).
+                    { field: "createdAt", renderer: { format: "timestamp" } },
+                    { field: "expiresAt", renderer: { format: "timestamp" } },
+                    { field: "revokedAt", renderer: { format: "timestamp" } },
+                    "ip",
+                    "userAgent",
+                ],
+            },
+        ],
+    },
+    fieldLabels: {
+        id: i18nKey("sessions.detail.field.id"),
+        userId: i18nKey("sessions.detail.field.userId"),
+        createdAt: i18nKey("sessions.detail.field.createdAt"),
+        expiresAt: i18nKey("sessions.detail.field.expiresAt"),
+        revokedAt: i18nKey("sessions.detail.field.revokedAt"),
+        ip: i18nKey("sessions.detail.field.ip"),
+        userAgent: i18nKey("sessions.detail.field.userAgent"),
+    },
+    access: listAccess,
+};
+// Revoke is hidden on the current session — it would sign the user out mid-click; logout covers it.
+export const sessionMineScreen = {
+    id: SESSION_MINE_SCREEN_ID,
+    type: "projectionList",
+    query: SessionQueries.mine,
+    columns: [
+        {
+            field: "createdAt",
+            label: i18nKey("sessions.list.col.createdAt"),
+            renderer: { format: "timestamp" },
+        },
+        {
+            field: "expiresAt",
+            label: i18nKey("sessions.list.col.expiresAt"),
+            renderer: { format: "timestamp" },
+        },
+        { field: "ip", label: i18nKey("sessions.mine.col.ip") },
+        { field: "userAgent", label: i18nKey("sessions.mine.col.userAgent") },
+        {
+            field: "current",
+            label: i18nKey("sessions.mine.col.current"),
+            renderer: { format: "boolean" },
+        },
+    ],
+    rowActions: [
+        {
+            kind: "writeHandler",
+            id: "revoke",
+            label: i18nKey("sessions.mine.revoke"),
+            handler: SessionHandlers.revoke,
+            style: "danger",
+            confirm: i18nKey("sessions.mine.revoke.confirm"),
+            visible: { field: "current", eq: false },
+        },
+    ],
+    toolbarActions: [
+        {
+            kind: "writeHandler",
+            id: "revoke-all-others",
+            label: i18nKey("sessions.mine.revokeAllOthers"),
+            handler: SessionHandlers.revokeAllOthers,
+            style: "danger",
+            confirm: i18nKey("sessions.mine.revokeAllOthers.confirm"),
+        },
+    ],
+    access: {
+        openToAll: {
+            reason: "each signed-in user views and revokes only their own sessions, mirroring the mine/revoke handlers",
+        },
+    },
+    // Self-service settings-area screen, placed by the consuming app's own
+    // r.nav() — no nav area to resolve in isolation.
+    dormant: true,
+};

package/dist/sessions/session-callbacks.d.ts

@@ -0,0 +1,18 @@
+import type { SessionChecker, SessionCreator, SessionMassRevoker, SessionRevoker } from "@cosmicdrift/kumiko-framework/api";
+export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { isPrincipalBlocked } from "../user/index.js";
+export { isPrincipalBlocked };
+export type SessionAllOthersRevoker = (userId: string, currentSid: string | undefined) => Promise<number>;
+export type SessionCallbacksOptions = {
+    readonly db: DbConnection;
+    readonly expiresInMs?: number;
+};
+export type SessionCallbacks = {
+    sessionCreator: SessionCreator;
+    sessionRevoker: SessionRevoker;
+    sessionChecker: SessionChecker;
+    sessionMassRevoker: SessionMassRevoker;
+    sessionRevokeAllOthers: SessionAllOthersRevoker;
+};
+export declare function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCallbacks;

package/dist/sessions/session-callbacks.js

@@ -0,0 +1,197 @@
+import { fetchOne, insertOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+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, userTable } from "../user/index.js";
+import { DEFAULT_SESSION_EXPIRY_MS, LAST_SEEN_REFRESH_MS } 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 };
+export function createSessionCallbacks(opts) {
+    const ttlMs = opts.expiresInMs ?? DEFAULT_SESSION_EXPIRY_MS;
+    const { db } = opts;
+    return {
+        async sessionCreator(user, meta) {
+            const sid = generateId();
+            const now = Temporal.Now.instant();
+            const expiresAt = now.add({ milliseconds: ttlMs });
+            await insertOne(db, userSessionTable, await encryptForDirectWrite(userSessionEntity, "user-session", {
+                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) {
+            // 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.)
+            const result = await updateMany(db, 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(db, {
+                    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, expectedUserId) {
+            const row = await fetchOne(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;
+            try {
+                user = await fetchOne(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;
+            try {
+                const membership = await fetchOne(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 };
+        },
+        async sessionMassRevoker(userId) {
+            // Count is accurate because we only touch live rows — a previously
+            // revoked row stays in its state and isn't double-counted.
+            const result = await updateMany(db, 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) => row.id),
+                });
+                await append(db, {
+                    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, currentSid) {
+            const result = await updateMany(db, 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) => row.id),
+                    keptSessionId: currentSid,
+                });
+                await append(db, {
+                    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/dist/sessions/session-revoked-event.d.ts

@@ -0,0 +1,11 @@
+import * as z from "zod";
+export declare const SESSION_REVOKED_EVENT_SHORT: "session-revoked";
+export declare const SESSION_REVOKED_EVENT_QN: "sessions:event:session-revoked";
+export declare const SESSION_REVOKED_AGGREGATE_TYPE: "user-session-revocation";
+export declare const sessionRevokedSchema: z.ZodObject<{
+    userId: z.ZodString;
+    sessionIds: z.ZodArray<z.ZodUUID>;
+    keptSessionId: z.ZodOptional<z.ZodUUID>;
+    streamScope: z.ZodOptional<z.ZodLiteral<"revoked-sessions">>;
+}, z.core.$strip>;
+export type SessionRevokedPayload = z.infer<typeof sessionRevokedSchema>;

package/dist/sessions/session-revoked-event.js

@@ -0,0 +1,32 @@
+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";
+export const SESSION_REVOKED_EVENT_QN = "sessions:event:session-revoked";
+// 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";
+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(),
+});

package/dist/sessions/testing.d.ts

@@ -0,0 +1,12 @@
+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 declare function sessionCallbacksFromLateBound(holder: LateBoundHolder<SessionCallbacks>): BoundSessionCallbacks;
+export declare function withMintedSession(sessionCreator: SessionCreator, user: SessionUser): Promise<SessionUser>;

package/dist/sessions/testing.js

@@ -0,0 +1,36 @@
+// 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.
+export function sessionCallbacksFromLateBound(holder) {
+    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, user) {
+    const sid = await sessionCreator(user, { ip: "127.0.0.1", userAgent: "test" });
+    return { ...user, sid };
+}

package/dist/shared/assert-erased.d.ts

@@ -0,0 +1,2 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+export declare function assertErased(result: WriteResult<unknown>, entityName: string, id: string): void;

package/dist/shared/assert-erased.js

@@ -0,0 +1,13 @@
+// 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 assert.
+export function assertErased(result, entityName, id) {
+    // skip: the happy path — the assertion 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;
+    throw new Error(`[user-data-rights] failed to erase ${entityName}/${id}: ${result.error.code} — ${result.error.message}`);
+}

package/dist/shared/chunked-entity-migration.d.ts

@@ -0,0 +1,18 @@
+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;
+    readonly deadlineAt: number;
+    readonly signal?: AbortSignal | undefined;
+    readonly onRowError?: (row: Row, err: unknown) => void;
+};
+export declare function runChunkedMigration<Row>(opts: ChunkedMigrationOptions<Row>): Promise<ChunkedMigrationResult>;

package/dist/shared/chunked-entity-migration.js

@@ -0,0 +1,63 @@
+// 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 async function runChunkedMigration(opts) {
+    let migrated = 0;
+    let skipped = 0;
+    let failed = 0;
+    let batchesProcessed = 0;
+    let stoppedReason = "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;
+            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/dist/shared/classify-stored-envelope.d.ts

@@ -0,0 +1,2 @@
+export type StoredEnvelopeClassification = "rotate" | "current" | "unrecognized";
+export declare function classifyStoredEnvelope(value: string, targetVersion: number): StoredEnvelopeClassification;

package/dist/shared/classify-stored-envelope.js

@@ -0,0 +1,17 @@
+import { isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
+// 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, targetVersion) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return "unrecognized";
+    }
+    if (!isStoredEnvelope(parsed))
+        return "unrecognized";
+    return parsed.kekVersion === targetVersion ? "current" : "rotate";
+}

package/dist/shared/decrypt-stored-pii.d.ts

@@ -0,0 +1 @@
+export declare function decryptStoredPii(value: string, field: string, fallbackRequestId: string): Promise<string>;

package/dist/shared/decrypt-stored-pii.js

@@ -0,0 +1,19 @@
+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, field, fallbackRequestId) {
+    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/dist/shared/encrypt-for-direct-write.d.ts

@@ -0,0 +1,2 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function encryptForDirectWrite(entity: EntityDefinition, entityName: string, row: Record<string, unknown>, fallbackRequestId: string): Promise<Record<string, unknown>>;

package/dist/shared/encrypt-for-direct-write.js

@@ -0,0 +1,12 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+// 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, entityName, row, fallbackRequestId) {
+    const kms = configuredPiiSubjectKms();
+    if (!kms)
+        return row;
+    return encryptPiiFieldValues(row, entity, collectPiiSubjectFields(entity), kms, { requestId: requestContext.get()?.requestId ?? fallbackRequestId }, { entityName });
+}

package/dist/shared/entities-of.d.ts

@@ -0,0 +1,2 @@
+import type { EntityDefinition, FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function entitiesOf(feature: FeatureDefinition): ReadonlyArray<readonly [string, EntityDefinition]>;

package/dist/shared/entities-of.js

@@ -0,0 +1,13 @@
+// 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) {
+    const fromEntities = Object.entries(feature.entities ?? {});
+    const fromProjections = Object.values(feature.projections ?? {})
+        .filter((p) => p.entity !== undefined)
+        .map((p) => [p.name, p.entity]);
+    return [...fromEntities, ...fromProjections];
+}

package/dist/shared/grace-period.d.ts

@@ -0,0 +1,6 @@
+/** Shared grace-period check for user-data-rights + tenant-lifecycle cancel flows. */
+/**
+ * True when `gracePeriodEnd` is still in the future.
+ * Uses the polyfill Instant API so callers don't depend on `globalThis.Temporal`.
+ */
+export declare function isWithinGracePeriod(gracePeriodEnd: Temporal.Instant | null): boolean;