@cosmicdrift/kumiko-bundled-features 0.109.0 → 0.111.0

package/src/secrets/handlers/rotate.job.ts

@@ -26,7 +26,12 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { rewrapDek } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  decodeStoredEnvelope,
+  encodeStoredEnvelope,
+  rewrapDek,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
 import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table";
 
 const DEFAULT_BATCH_SIZE = 100;
@@ -47,7 +52,7 @@ export type RotateJobResult = {
   readonly migrated: number;
   readonly failed: number;
   readonly batchesProcessed: number;
-  readonly stoppedReason: "empty" | "timeout" | "signal" | "too_many_failures";
+  readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
 export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
@@ -71,11 +76,6 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
     ? Date.now() + payload.maxDurationMs
     : Number.POSITIVE_INFINITY;
 
-  let migrated = 0;
-  let failed = 0;
-  let batchesProcessed = 0;
-  let stoppedReason: RotateJobResult["stoppedReason"] = "empty";
-
   // Reuse a TenantDb-per-tenant map so we don't rebuild the wrapper for
   // each row in the same tenant. Rotation typically hits one tenant in a
   // batch; the map trims an allocation without adding complexity.
@@ -89,101 +89,80 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
     return existing;
   }
 
-  while (true) {
-    if (ctx.signal?.aborted) {
-      stoppedReason = "signal";
-      break;
-    }
-    if (Date.now() >= deadline) {
-      stoppedReason = "timeout";
-      break;
-    }
-
-    const targetVersion = provider.currentVersion();
-    const batch = await selectMany<{
-      id: string;
-      tenantId: string;
-      version: number;
-      envelope: StoredEnvelope;
-      kekVersion: number;
-    }>(db, tenantSecretsTable, { kekVersion: { ne: targetVersion } }, { limit: batchSize });
-
-    if (batch.length === 0) break;
-
-    batchesProcessed++;
-
-    if (failed >= maxFailures) {
-      stoppedReason = "too_many_failures";
-      break;
-    }
-
-    for (const row of batch) {
-      if (failed >= maxFailures) {
-        stoppedReason = "too_many_failures";
-        break;
-      }
-      try {
-        const oldEnvelope = {
-          ciphertext: Buffer.from(row.envelope.ciphertext, "base64"),
-          iv: Buffer.from(row.envelope.iv, "base64"),
-          authTag: Buffer.from(row.envelope.authTag, "base64"),
-          encryptedDek: Buffer.from(row.envelope.encryptedDek, "base64"),
-          kekVersion: row.envelope.kekVersion,
-        };
-        const rotated = await rewrapDek(oldEnvelope, provider);
-
-        if (rotated.kekVersion === row.kekVersion) continue;
+  type SecretRow = {
+    id: string;
+    tenantId: string;
+    version: number;
+    envelope: StoredEnvelope;
+    kekVersion: number;
+  };
+
+  // A partial batch means the ne-filter is exhausted — the next re-query
+  // would only re-serve rows that failed above; end the run instead.
+  let sawPartialBatch = false;
+  async function nextBatch(): Promise<readonly SecretRow[]> {
+    if (sawPartialBatch) return [];
+    const batch = await selectMany<SecretRow>(
+      db,
+      tenantSecretsTable,
+      { kekVersion: { ne: provider.currentVersion() } },
+      { limit: batchSize },
+    );
+    if (batch.length < batchSize) sawPartialBatch = true;
+    return batch;
+  }
 
-        const newEnvelope: StoredEnvelope = {
-          ciphertext: rotated.ciphertext.toString("base64"),
-          iv: rotated.iv.toString("base64"),
-          authTag: rotated.authTag.toString("base64"),
-          encryptedDek: rotated.encryptedDek.toString("base64"),
+  async function migrateRow(row: SecretRow): Promise<"migrated" | "skipped" | "failed"> {
+    const rotated = await rewrapDek(decodeStoredEnvelope(row.envelope), provider);
+    if (rotated.kekVersion === row.kekVersion) return "skipped";
+
+    const actor: SessionUser = {
+      id: "system",
+      tenantId: row.tenantId as TenantId,
+      roles: SYSTEM_ROLES,
+    };
+    const result = await executor.update(
+      {
+        id: row.id,
+        version: row.version,
+        changes: {
+          envelope: encodeStoredEnvelope(rotated),
           kekVersion: rotated.kekVersion,
-        };
-
-        const actor: SessionUser = {
-          id: "system",
-          tenantId: row.tenantId as TenantId,
-          roles: SYSTEM_ROLES,
-        };
-
-        const result = await executor.update(
-          {
-            id: row.id,
-            version: row.version,
-            changes: {
-              envelope: newEnvelope,
-              kekVersion: rotated.kekVersion,
-            },
-          },
-          actor,
-          tdbFor(row.tenantId as TenantId),
-        );
-
-        // version_conflict == another writer (secrets.set or a parallel
-        // rotation worker) beat us. Count as "skipped" and move on — the
-        // row is already in a valid state, potentially even past target.
-        if (!result.isSuccess) {
-          if (result.error.code === "version_conflict") continue;
-          failed++;
-          ctx.log?.warn?.(`[secrets:rotate] executor rejected row ${row.id}`, {
-            code: result.error.code,
-          });
-          continue;
-        }
-      } catch (err) {
-        failed++;
-        ctx.log?.warn?.(`[secrets:rotate] failed to rotate row ${row.id}`, { err });
-        continue;
-      }
-      migrated++;
+        },
+      },
+      actor,
+      tdbFor(row.tenantId as TenantId),
+    );
+
+    // version_conflict == another writer (secrets.set or a parallel
+    // rotation worker) beat us — the row is already in a valid state,
+    // potentially even past target.
+    if (!result.isSuccess) {
+      if (result.error.code === "version_conflict") return "skipped";
+      ctx.log?.warn?.(`[secrets:rotate] executor rejected row ${row.id}`, {
+        code: result.error.code,
+      });
+      return "failed";
     }
-
-    if (stoppedReason === "too_many_failures") break;
-    if (batch.length < batchSize) break;
+    return "migrated";
   }
 
-  const result: RotateJobResult = { migrated, failed, batchesProcessed, stoppedReason };
+  const outcome = await runChunkedMigration<SecretRow>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: (row, err) => {
+      ctx.log?.warn?.(`[secrets:rotate] failed to rotate row ${row.id}`, { err });
+    },
+  });
+
+  const result: RotateJobResult = {
+    migrated: outcome.migrated,
+    failed: outcome.failed,
+    batchesProcessed: outcome.batchesProcessed,
+    stoppedReason: outcome.stoppedReason,
+  };
   ctx.log?.info?.(`[secrets:rotate] complete: ${JSON.stringify(result)}`);
 };

package/src/secrets/secrets-context.ts

@@ -25,10 +25,13 @@ import {
   createDekCache,
   createSecret,
   type DekCache,
+  decodeStoredEnvelope,
   decryptValue,
+  encodeStoredEnvelope,
   encryptValue,
   type MasterKeyProvider,
   type SecretsContext,
+  withDekCache,
 } from "@cosmicdrift/kumiko-framework/secrets";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
@@ -79,37 +82,9 @@ function resolveKey(keyOrHandle: string | { readonly name: string }): string {
   return typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
 }
 
-// Wrap a provider so its unwrapDek goes through the cache. Lets decryptValue
-// use the full provider contract without knowing about caching — separation
-// of concerns: decryptValue handles crypto, cache handles cost.
-function cachedProvider(provider: MasterKeyProvider, cache: DekCache): MasterKeyProvider {
-  return {
-    wrapDek: provider.wrapDek.bind(provider),
-    unwrapDek: (encryptedDek, version) => cache.unwrapDek(encryptedDek, version, provider),
-    currentVersion: provider.currentVersion.bind(provider),
-    isAvailable: provider.isAvailable.bind(provider),
-  };
-}
-
-function decodeEnvelope(stored: StoredEnvelope): {
-  ciphertext: Buffer;
-  iv: Buffer;
-  authTag: Buffer;
-  encryptedDek: Buffer;
-  kekVersion: number;
-} {
-  return {
-    ciphertext: Buffer.from(stored.ciphertext, "base64"),
-    iv: Buffer.from(stored.iv, "base64"),
-    authTag: Buffer.from(stored.authTag, "base64"),
-    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
-    kekVersion: stored.kekVersion,
-  };
-}
-
 export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
   const { db, masterKeyProvider } = opts;
-  const provider = cachedProvider(masterKeyProvider, opts.dekCache ?? createDekCache());
+  const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
 
   type SecretLookupRow = {
     readonly id: string;
@@ -133,7 +108,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
       if (!auditCtx) {
         const existing = await lookup(tenantId, key);
         if (!existing) return undefined;
-        const plaintext = await decryptValue(decodeEnvelope(existing.envelope), provider);
+        const plaintext = await decryptValue(decodeStoredEnvelope(existing.envelope), provider);
         return createSecret(plaintext);
       }
 
@@ -142,7 +117,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
         // type doesn't widen to the transaction object cleanly.
         const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
         if (!envelope) return undefined;
-        const pt = await decryptValue(decodeEnvelope(envelope), provider);
+        const pt = await decryptValue(decodeStoredEnvelope(envelope), provider);
 
         // One event per read on its own aggregate-stream (fresh UUID as
         // aggregateId). Avoids version-conflicts between parallel reads —
@@ -190,13 +165,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
     async set(tenantId, keyOrHandle, value, setOpts = {}) {
       const key = resolveKey(keyOrHandle);
       const envelope = await encryptValue(value, masterKeyProvider);
-      const stored: StoredEnvelope = {
-        ciphertext: envelope.ciphertext.toString("base64"),
-        iv: envelope.iv.toString("base64"),
-        authTag: envelope.authTag.toString("base64"),
-        encryptedDek: envelope.encryptedDek.toString("base64"),
-        kekVersion: envelope.kekVersion,
-      };
+      const stored: StoredEnvelope = encodeStoredEnvelope(envelope);
       const metadata: StoredMetadata = {
         ...(setOpts.redact ? { redactedPreview: setOpts.redact(value) } : {}),
         ...(setOpts.hint ? { hint: setOpts.hint } : {}),

package/src/secrets/table.ts

@@ -13,6 +13,7 @@ import {
   createNumberField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
+import type { StoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
 
 // Envelope stored as a single jsonb blob. All ops are upsert-by-(tenantId, key)
 // so there's no value in decomposing the envelope into separate columns —
@@ -22,13 +23,11 @@ import {
 // `WHERE kek_version != currentVersion()` with an index on just that column
 // without deserializing the jsonb. Duplicated inside envelope too — the two
 // always stay in sync via the write path.
-export type StoredEnvelope = {
-  readonly ciphertext: string; // base64
-  readonly iv: string; // base64
-  readonly authTag: string; // base64
-  readonly encryptedDek: string; // base64
-  readonly kekVersion: number;
-};
+//
+// StoredEnvelope itself is canonical in @cosmicdrift/kumiko-framework/secrets
+// (shared with EnvelopeCipher for TEXT-column stores) — re-exported here so
+// existing consumers keep their import path.
+export type { StoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
 
 export type StoredMetadata = {
   readonly redactedPreview?: string;

package/src/sessions/__tests__/auto-revoke-binding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { AppContext, SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { bindAutoRevokeFromFeature, createSessionsFeature } from "../feature";
+
+// The postSave hook is registered unconditionally; the revoker arrives either
+// as the explicit constructor option or late-bound by run{Prod,Dev}App via
+// bindAutoRevokeOnPasswordChange. These tests pin the binding + precedence
+// semantics at the hook level — the full DB sweep is covered by
+// password-auto-revoke.integration.test.ts.
+
+const passwordChange: SaveContext = {
+  kind: "save",
+  id: "user-1",
+  data: {},
+  changes: { passwordHash: "new-hash" },
+  previous: {},
+  isNew: false,
+};
+
+// @cast-boundary test fixture — the hook never touches AppContext
+const appContext = {} as unknown as AppContext;
+
+function userPostSaveHook(feature: ReturnType<typeof createSessionsFeature>) {
+  const hook = feature.entityHooks?.postSave?.["user"]?.[0];
+  if (!hook) throw new Error("sessions feature did not register the user postSave hook");
+  return (ctx: SaveContext) => hook.fn(ctx, appContext);
+}
+
+describe("sessions auto-revoke binding", () => {
+  test("late-bound revoker fires on password change", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+
+    const bind = bindAutoRevokeFromFeature(feature);
+    expect(bind).toBeDefined();
+    bind?.(revoker);
+
+    await userPostSaveHook(feature)(passwordChange);
+    expect(revoker).toHaveBeenCalledTimes(1);
+    expect(revoker).toHaveBeenCalledWith("user-1");
+  });
+
+  test("unbound hook is a silent no-op", async () => {
+    const feature = createSessionsFeature();
+    // must resolve without throwing — stateless-JWT deployments have no revoker
+    const result = await userPostSaveHook(feature)(passwordChange);
+    expect(result).toBeUndefined();
+  });
+
+  test("skips isNew and non-passwordHash changes", async () => {
+    const revoker = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature();
+    bindAutoRevokeFromFeature(feature)?.(revoker);
+
+    await userPostSaveHook(feature)({ ...passwordChange, isNew: true });
+    await userPostSaveHook(feature)({ ...passwordChange, changes: { displayName: "x" } });
+    expect(revoker).not.toHaveBeenCalled();
+  });
+
+  test("explicit constructor option wins over the runtime binding", async () => {
+    const explicit = mock(async (_userId: string) => 1);
+    const lateBound = mock(async (_userId: string) => 1);
+    const feature = createSessionsFeature({ autoRevokeOnPasswordChange: explicit });
+
+    bindAutoRevokeFromFeature(feature)?.(lateBound);
+    await userPostSaveHook(feature)(passwordChange);
+
+    expect(explicit).toHaveBeenCalledWith("user-1");
+    expect(lateBound).not.toHaveBeenCalled();
+  });
+});

package/src/sessions/__tests__/password-auto-revoke.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -10,7 +9,10 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { createLateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createLateBoundHolder,
+  createTestEnvelopeCipher,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { AuthHandlers } from "../../auth-email-password/constants";
 import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
 import { createConfigFeature } from "../../config";
@@ -49,8 +51,8 @@ const encryptionKey = randomBytes(32).toString("base64");
 const TENANT: TenantId = testTenantId(1);
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
   const bound = sessionCallbacksFromLateBound(callbacks);
   const baseRevoker = bound.asMassRevoker();
 

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -1,7 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -12,6 +11,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import {
   createLateBoundHolder,
+  createTestEnvelopeCipher,
   deleteRows,
   resetTestTables,
   updateRows,
@@ -47,8 +47,8 @@ const encryptionKey = randomBytes(32).toString("base64");
 const TENANT: TenantId = testTenantId(1);
 
 beforeAll(async () => {
-  const encryption = createEncryptionProvider(encryptionKey);
-  const resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
   const bound = sessionCallbacksFromLateBound(callbacks);
 
   stack = await setupTestStack({

package/src/sessions/feature.ts

@@ -10,19 +10,46 @@ import { userSessionEntity } from "./schema/user-session";
 import type { SessionMassRevoker } from "./session-callbacks";
 
 export type SessionsFeatureOptions = {
-  // When wired, a successful update on the `user` entity that changes the
-  // `passwordHash` column triggers a mass-revoke of every live session for
-  // that user. Industry-standard "password-change signs you out everywhere"
-  // flow, including the session that did the change itself — the client has
+  // A successful update on the `user` entity that changes the `passwordHash`
+  // column triggers a mass-revoke of every live session for that user.
+  // Industry-standard "password-change signs you out everywhere" flow,
+  // including the session that did the change itself — the client has
   // to re-login after a password change.
   //
   // Runs as an afterCommit postSave hook: the password-change commits first,
   // then the sessions are revoked. Best-effort — if the mass-revoker throws,
   // the password change is NOT rolled back (a password change with a stale
   // session still wins over a user-visible error on the change itself).
+  //
+  // Default: run{Prod,Dev}App bind their own sessionMassRevoker via
+  // `bindAutoRevokeOnPasswordChange` (secure-by-default). Set this option
+  // only to supply a custom revoker — an explicit value wins over the
+  // runtime binding.
   readonly autoRevokeOnPasswordChange?: SessionMassRevoker;
 };
 
+export type BindAutoRevokeOnPasswordChange = (revoker: SessionMassRevoker) => void;
+
+// Reads the late-bind setter off a mounted sessions feature's exports.
+// run{Prod,Dev}App call it once the DB connection is concrete — the feature
+// itself is constructed in app run-config long before a db exists, so the
+// revoker can't be a constructor argument.
+export function bindAutoRevokeFromFeature(
+  feature: FeatureDefinition,
+): BindAutoRevokeOnPasswordChange | undefined {
+  const exports = feature.exports;
+  if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
+    const { bindAutoRevokeOnPasswordChange } = exports as {
+      bindAutoRevokeOnPasswordChange: unknown;
+    };
+    if (typeof bindAutoRevokeOnPasswordChange === "function") {
+      // @cast-boundary exports-walk — feature.exports is untyped by design
+      return bindAutoRevokeOnPasswordChange as BindAutoRevokeOnPasswordChange;
+    }
+  }
+  return undefined;
+}
+
 // The sessions feature registers the read_user_sessions table (as an
 // unmanaged direct-write store, NOT an r.entity — see below) and the three
 // user-facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
@@ -93,20 +120,26 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     // "the handler didn't touch this column", which is exactly the signal
     // we want to skip on. Works for both direct user:update calls and any
     // other handler that happens to write the column.
-    const autoRevoke = options?.autoRevokeOnPasswordChange;
-    if (autoRevoke) {
-      r.entityHook("postSave", "user", async (ctx) => {
-        // skip: brand-new user, no sessions can possibly exist yet. The
-        // initial passwordHash on a user:create would trip the second guard
-        // otherwise — every registration would do a mass-revoke roundtrip
-        // for a user who literally has no rows in user_sessions.
-        if (ctx.isNew) return;
-        // skip: handler didn't touch passwordHash, nothing to revoke
-        if (ctx.changes["passwordHash"] === undefined) return;
-        await autoRevoke(String(ctx.id));
-      });
-    }
+    let autoRevoke = options?.autoRevokeOnPasswordChange;
+    r.entityHook("postSave", "user", async (ctx) => {
+      // skip: nothing bound — stateless-JWT deployments without a runtime
+      // that calls bindAutoRevokeOnPasswordChange keep the old behavior.
+      if (!autoRevoke) return;
+      // skip: brand-new user, no sessions can possibly exist yet. The
+      // initial passwordHash on a user:create would trip the second guard
+      // otherwise — every registration would do a mass-revoke roundtrip
+      // for a user who literally has no rows in user_sessions.
+      if (ctx.isNew) return;
+      // skip: handler didn't touch passwordHash, nothing to revoke
+      if (ctx.changes["passwordHash"] === undefined) return;
+      await autoRevoke(String(ctx.id));
+    });
+
+    const bindAutoRevokeOnPasswordChange: BindAutoRevokeOnPasswordChange = (revoker) => {
+      // explicit constructor option wins over the runtime binding
+      autoRevoke ??= revoker;
+    };
 
-    return { handlers, queries };
+    return { handlers, queries, bindAutoRevokeOnPasswordChange };
   });
 }

package/src/sessions/index.ts

@@ -6,8 +6,8 @@ export {
   SessionHandlers,
   SessionQueries,
 } from "./constants";
-export type { SessionsFeatureOptions } from "./feature";
-export { createSessionsFeature } from "./feature";
+export type { BindAutoRevokeOnPasswordChange, SessionsFeatureOptions } from "./feature";
+export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature";
 export { userSessionEntity, userSessionTable } from "./schema/user-session";
 export type {
   SessionCallbacks,

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;
+
+    batchesProcessed++;
+
+    if (failed >= opts.maxFailures) {
+      stoppedReason = "too_many_failures";
+      break;
+    }
+
+    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/index.ts

@@ -0,0 +1,7 @@
+export {
+  type ChunkedMigrationOptions,
+  type ChunkedMigrationResult,
+  type ChunkedMigrationStopReason,
+  type MigrationRowOutcome,
+  runChunkedMigration,
+} from "./chunked-entity-migration";