@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/sessions/session-callbacks.ts

@@ -2,17 +2,29 @@ import type {
   AuthSessionStatus,
   SessionChecker,
   SessionCreator,
+  SessionMassRevoker,
   SessionMetadata,
   SessionRevoker,
 } from "@cosmicdrift/kumiko-framework/api";
+
+export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
+
 import { fetchOne, insertOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
+import { encryptForDirectWrite } from "../shared";
 import { USER_STATUS, type UserStatus, userTable } from "../user";
 import { DEFAULT_SESSION_EXPIRY_MS } from "./constants";
-import { userSessionTable } from "./schema/user-session";
+import { userSessionEntity, userSessionTable } from "./schema/user-session";
+import {
+  SESSION_REVOKED_AGGREGATE_TYPE,
+  SESSION_REVOKED_EVENT_QN,
+  sessionRevokedSchema,
+} from "./session-revoked-event";
 
 // Locked accounts whose live sessions must be refused. deletionRequested is
 // intentionally absent — it's a reversible grace period and the user needs
@@ -27,10 +39,15 @@ const BLOCKED_STATUSES: ReadonlySet<UserStatus> = new Set([
 // login and every request. The (createdAt/revokedAt/ip/userAgent) columns
 // already are the audit trail — a dispatcher roundtrip buys nothing.
 
-// Mass-revoke for a single user. Used by the password-change hook and
-// "sign out everywhere" flows. Returns the count of rows flipped so a
-// caller can log "revoked N other sessions".
-export type SessionMassRevoker = (userId: string) => Promise<number>;
+// "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;
@@ -44,6 +61,7 @@ export type SessionCallbacks = {
   sessionRevoker: SessionRevoker;
   sessionChecker: SessionChecker;
   sessionMassRevoker: SessionMassRevoker;
+  sessionRevokeAllOthers: SessionAllOthersRevoker;
 };
 
 export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCallbacks {
@@ -55,15 +73,23 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
       const sid = generateId();
       const now = Temporal.Now.instant();
       const expiresAt = now.add({ milliseconds: ttlMs });
-      await insertOne(db, userSessionTable, {
-        id: sid,
-        tenantId: user.tenantId,
-        userId: user.id,
-        createdAt: now,
-        expiresAt,
-        ip: meta.ip,
-        userAgent: meta.userAgent,
-      });
+      await insertOne(
+        db,
+        userSessionTable,
+        await encryptForDirectWrite(
+          userSessionEntity,
+          {
+            id: sid,
+            tenantId: user.tenantId,
+            userId: user.id,
+            createdAt: now,
+            expiresAt,
+            ip: meta.ip,
+            userAgent: meta.userAgent,
+          },
+          "sessions:create",
+        ),
+      );
       return sid;
     },
 
@@ -124,6 +150,65 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
         { 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(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: string, currentSid: string | undefined): Promise<number> {
+      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: { id: string }) => 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;
     },
   };

package/src/sessions/session-checker-fail-open.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import * as bunDb from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { Temporal } from "temporal-polyfill";
+import { USER_STATUS, userTable } from "../user/schema/user";
+import { userSessionTable } from "./schema/user-session";
+import { createSessionCallbacks } from "./session-callbacks";
+
+// Unit-only: the fail-open-on-throw branch cannot be provoked through real
+// Postgres without faking infrastructure failure. Integration tests forbid
+// mocks, so this lives next to the source as a plain *.test.ts.
+
+type FetchOne = typeof bunDb.fetchOne;
+
+describe("sessionChecker fail-open on user-lookup throw", () => {
+  test("read_users THROW → live (not 500 / not blocked)", async () => {
+    const db = {} as DbConnection;
+    const cbs = createSessionCallbacks({ db });
+    const sid = "00000000-0000-4000-8000-00000000sid1";
+    const userId = "00000000-0000-4000-8000-00000000user";
+    const farFutureMs = Temporal.Now.instant().add({ hours: 1 }).epochMilliseconds;
+
+    const originalFetchOne = bunDb.fetchOne;
+    const spy = spyOn(bunDb, "fetchOne").mockImplementation((async (_db, table) => {
+      if (table === userSessionTable) {
+        return {
+          userId,
+          revokedAt: null,
+          expiresAt: { epochMilliseconds: farFutureMs },
+        };
+      }
+      if (table === userTable) {
+        throw new Error("simulated pool exhaustion");
+      }
+      throw new Error("unexpected table in sessionChecker spy");
+    }) as FetchOne);
+
+    try {
+      expect(await cbs.sessionChecker(sid, userId)).toBe("live");
+    } finally {
+      spy.mockRestore();
+      // Sanity: restore must put the real export back (guards against spy leak).
+      expect(bunDb.fetchOne).toBe(originalFetchOne);
+    }
+  });
+
+  test("control: Restricted user without throw → blocked (spy must hit userTable)", async () => {
+    // If the spy somehow skipped the userTable branch, Restricted would still
+    // be "live" via fail-open-on-null — this control pins that the throw path
+    // is what we exercise above, not an accidental miss.
+    const db = {} as DbConnection;
+    const cbs = createSessionCallbacks({ db });
+    const sid = "00000000-0000-4000-8000-00000000sid2";
+    const userId = "00000000-0000-4000-8000-00000000usr2";
+    const farFutureMs = Temporal.Now.instant().add({ hours: 1 }).epochMilliseconds;
+
+    const spy = spyOn(bunDb, "fetchOne").mockImplementation((async (_db, table) => {
+      if (table === userSessionTable) {
+        return {
+          userId,
+          revokedAt: null,
+          expiresAt: { epochMilliseconds: farFutureMs },
+        };
+      }
+      if (table === userTable) {
+        return { status: USER_STATUS.Restricted };
+      }
+      throw new Error("unexpected table in sessionChecker spy");
+    }) as FetchOne);
+
+    try {
+      expect(await cbs.sessionChecker(sid, userId)).toBe("blocked");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/sessions/session-revoked-event.ts

@@ -0,0 +1,29 @@
+import { 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),
+});
+
+export type SessionRevokedPayload = z.infer<typeof sessionRevokedSchema>;

package/src/sessions/testing.ts

@@ -17,7 +17,8 @@
 // sessions feature owns. framework/testing only provides the generic
 // `createLateBoundHolder<T>` — shape-independent.
 
-import type { AuthRoutesConfig } from "@cosmicdrift/kumiko-framework/api";
+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";
 
@@ -40,3 +41,15 @@ export function sessionCallbacksFromLateBound(
     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/src/shared/__tests__/chunked-entity-migration.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import { runChunkedMigration } from "../chunked-entity-migration";
+
+describe("runChunkedMigration", () => {
+  test("processes all batches and stops with 'done' when nextBatch returns empty", async () => {
+    const batches: readonly number[][] = [[1, 2], [3], []];
+    let call = 0;
+    const migrated: number[] = [];
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => batches[call++] ?? [],
+      migrateRow: async (row) => {
+        migrated.push(row);
+        return "migrated";
+      },
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    expect(migrated).toEqual([1, 2, 3]);
+    expect(result).toEqual({
+      migrated: 3,
+      skipped: 0,
+      failed: 0,
+      batchesProcessed: 2,
+      stoppedReason: "done",
+    });
+  });
+
+  test("counts skipped and failed outcomes separately from migrated", async () => {
+    let call = 0;
+    const rows = [
+      { id: 1, outcome: "migrated" as const },
+      { id: 2, outcome: "skipped" as const },
+      { id: 3, outcome: "failed" as const },
+    ];
+
+    const result = await runChunkedMigration({
+      nextBatch: async () => (call++ === 0 ? rows : []),
+      migrateRow: async (row) => row.outcome,
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    expect(result.migrated).toBe(1);
+    expect(result.skipped).toBe(1);
+    expect(result.failed).toBe(1);
+    expect(result.stoppedReason).toBe("done");
+  });
+
+  test("a thrown migrateRow counts as failed and invokes onRowError", async () => {
+    let call = 0;
+    const errors: unknown[] = [];
+    const boom = new Error("boom");
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => (call++ === 0 ? [1] : []),
+      migrateRow: async () => {
+        throw boom;
+      },
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+      onRowError: (row, err) => errors.push([row, err]),
+    });
+
+    expect(result.failed).toBe(1);
+    expect(errors).toEqual([[1, boom]]);
+  });
+
+  test("stops with 'too_many_failures' once failed >= maxFailures, mid-batch", async () => {
+    let call = 0;
+    const seen: number[] = [];
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => (call++ === 0 ? [1, 2, 3] : []),
+      migrateRow: async (row) => {
+        seen.push(row);
+        return "failed";
+      },
+      maxFailures: 2,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    // The circuit-breaker checks before each row — row 3 is never attempted.
+    expect(seen).toEqual([1, 2]);
+    expect(result.failed).toBe(2);
+    expect(result.stoppedReason).toBe("too_many_failures");
+  });
+
+  test("stops with 'too_many_failures' checked between batches too", async () => {
+    let call = 0;
+    const batches = [["a"], ["b"], ["c"]];
+
+    const result = await runChunkedMigration<string>({
+      nextBatch: async () => batches[call++] ?? [],
+      migrateRow: async () => "failed",
+      maxFailures: 1,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    // Batch 1 processes "a" and pushes failed to 1; the breaker is checked
+    // before batchesProcessed is incremented for the next fetched batch, so
+    // "b" is fetched but never touched and doesn't count as processed.
+    expect(result.batchesProcessed).toBe(1);
+    expect(result.stoppedReason).toBe("too_many_failures");
+  });
+
+  test("stops with 'timeout' once the deadline has passed, without calling nextBatch again", async () => {
+    let nextBatchCalls = 0;
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => {
+        nextBatchCalls++;
+        return [];
+      },
+      migrateRow: async () => "migrated",
+      maxFailures: 10,
+      deadlineAt: Date.now() - 1,
+    });
+
+    expect(nextBatchCalls).toBe(0);
+    expect(result.batchesProcessed).toBe(0);
+    expect(result.stoppedReason).toBe("timeout");
+  });
+
+  test("stops with 'signal' when the AbortSignal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    let nextBatchCalls = 0;
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => {
+        nextBatchCalls++;
+        return [];
+      },
+      migrateRow: async () => "migrated",
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+      signal: controller.signal,
+    });
+
+    expect(nextBatchCalls).toBe(0);
+    expect(result.stoppedReason).toBe("signal");
+  });
+});

package/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/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/src/shared/encrypt-for-direct-write.ts

@@ -0,0 +1,23 @@
+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,
+  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,
+  });
+}

package/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/src/shared/grace-period.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { withoutAmbientTemporal } from "@cosmicdrift/kumiko-framework/testing";
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { isWithinGracePeriod } from "./grace-period";
+
+describe("isWithinGracePeriod — kumiko-framework#1525/#1550", () => {
+  test("null gracePeriodEnd → false without ambient Temporal", async () => {
+    await withoutAmbientTemporal(() => {
+      expect(isWithinGracePeriod(null)).toBe(false);
+    });
+  });
+
+  test("future vs past without ambient Temporal", async () => {
+    const future = TemporalPolyfill.Now.instant().add({
+      hours: 1,
+    }) as unknown as Temporal.Instant;
+    const past = TemporalPolyfill.Now.instant().subtract({
+      hours: 1,
+    }) as unknown as Temporal.Instant;
+
+    await withoutAmbientTemporal(() => {
+      expect(isWithinGracePeriod(future)).toBe(true);
+      expect(isWithinGracePeriod(past)).toBe(false);
+    });
+  });
+});

package/src/shared/grace-period.ts

@@ -0,0 +1,20 @@
+/** 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/src/{auth-email-password/__tests__ → shared}/identity-v3-hash.test.ts

@@ -15,8 +15,8 @@
 
 import { describe, expect, test } from "bun:test";
 import { pbkdf2Sync } from "node:crypto";
-import { isIdentityV3Hash, verifyIdentityV3Hash } from "../identity-v3-hash";
-import { verifyPassword } from "../password-hashing";
+import { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+import { verifyPassword } from "./password-hashing";
 
 // --- Test helpers ---
 

package/src/shared/index.ts

@@ -0,0 +1,16 @@
+export {
+  type ChunkedMigrationOptions,
+  type ChunkedMigrationResult,
+  type ChunkedMigrationStopReason,
+  type MigrationRowOutcome,
+  runChunkedMigration,
+} from "./chunked-entity-migration";
+export { decryptStoredPii } from "./decrypt-stored-pii";
+export { encryptForDirectWrite } from "./encrypt-for-direct-write";
+export { entitiesOf } from "./entities-of";
+export { isWithinGracePeriod } from "./grace-period";
+export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
+export { mapWithConcurrency } from "./map-with-concurrency";
+export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
+export type { SystemQueryFn } from "./system-query";
+export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";