@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/renderer-simple/resolve-variables.ts

@@ -0,0 +1,57 @@
+import type { RendererContext, RenderRequest } from "../renderer-foundation/index.js";
+import {
+  createTemplateResolverApi,
+  FALLBACK_LOCALE,
+  TemplateNotFoundError,
+} from "../template-resolver/index.js";
+
+type NotificationRequest = Extract<RenderRequest, { kind: "notification" }>;
+
+/** Merge template-resolver content (plain JSON EmailTemplateData) with runtime variables. */
+export async function resolveNotificationVariables(
+  req: NotificationRequest,
+  ctx: RendererContext,
+): Promise<Readonly<Record<string, unknown>>> {
+  const variables = req.payload.variables ?? {};
+  const slug = req.payload.template?.trim();
+  if (!slug || req.payload.content || !ctx.db || !ctx.registry.features.has("template-resolver")) {
+    return variables;
+  }
+
+  try {
+    const api = createTemplateResolverApi(ctx.db);
+    const locale = req.payload.locale ?? FALLBACK_LOCALE;
+    const resolved = await api.resolveTemplate({
+      tenantId: ctx.tenantId,
+      slug,
+      kind: "notification",
+      locale,
+    });
+    if (resolved.contentFormat === "plain") {
+      const base = parsePlainTemplateContent(resolved.content);
+      return { ...base, ...variables };
+    }
+    // body always wins from the resolved template for rendered formats — a runtime
+    // "variables.body" override would clobber the actual rendered content.
+    return { ...variables, body: resolved.content };
+  } catch (err) {
+    if (err instanceof TemplateNotFoundError) {
+      return variables;
+    }
+    throw err;
+  }
+}
+
+function parsePlainTemplateContent(content: string): Record<string, unknown> {
+  const trimmed = content.trim();
+  if (!trimmed) return {};
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // ponytail: non-JSON plain content becomes a single body section downstream
+  }
+  return { body: content };
+}

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -0,0 +1,65 @@
+import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import type { NotificationRenderer } from "../delivery/index.js";
+
+type Section =
+  | { readonly text: string }
+  | { readonly button: { readonly label: string; readonly url: string } };
+
+type EmailTemplateData = {
+  // Preferred: structured email data
+  readonly header?: string;
+  readonly sections?: readonly Section[];
+  readonly footer?: string;
+  // Fallback: plain title + body (used when no structured template is defined)
+  readonly title?: string;
+  readonly body?: string;
+};
+
+function renderSection(section: Section): string {
+  if ("text" in section) {
+    return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
+  }
+  if ("button" in section) {
+    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
+  }
+  return "";
+}
+
+// Simple Renderer: turns structured email template data into HTML with inline CSS.
+// No external dependencies, no template engine — just string concatenation.
+export const simpleRenderer: NotificationRenderer = {
+  name: "simple",
+
+  async render(input) {
+    const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
+
+    // Fallback: if no structured fields, use title + body as header + single text section
+    const header = data.header ?? data.title;
+    const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+
+    const parts: string[] = [];
+    parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
+    parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+
+    if (header) {
+      parts.push(
+        `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
+      );
+    }
+
+    if (sections) {
+      for (const section of sections) {
+        parts.push(renderSection(section));
+      }
+    }
+
+    if (data.footer) {
+      parts.push(
+        `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
+      );
+    }
+
+    parts.push("</div></body></html>");
+    return parts.join("");
+  },
+};

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

@@ -0,0 +1,29 @@
+[
+  {
+    "version": "0.337.0",
+    "type": "breaking",
+    "title": "secrets:set and secrets:delete accept only keys declared via r.secret; r.secret takes writeRoles",
+    "detail": "Both handlers reject a key that no feature declared with `r.secret` (404, i18n key `secrets.errors.unknownKey`). `r.secret` takes `writeRoles`: when set, only users holding one of those roles may set or delete that key (403, i18n key `secrets.errors.writeDenied`). The roles narrow the handler access, so both checks must pass. An empty `writeRoles` array throws at declaration.",
+    "migration": "Declare every key you set through `secrets:write:set` via `r.secret`. Rows stored under undeclared keys stay in the table but can no longer be set or deleted through the API. A key that only SystemAdmin may write declares `writeRoles: [\"SystemAdmin\"]`, and the secrets feature must then grant SystemAdmin handler access via `createSecretsFeature({ roles: [\"TenantAdmin\", \"SystemAdmin\"] })`. Tests that set a key no feature declares need the same fix: the kumiko-studio test `bundled-stack.integration.test.ts` sets `ai-foundation:secret:anthropic-api-key`, which no feature declares; kumiko-ai-foundation 0.39.1 and 0.40.1 declare the Anthropic key as `ai-provider-anthropic:secret:anthropic-api-key`."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "createSecretsFeature rejects access and roles together",
+    "detail": "`createSecretsFeature` throws at mount when both `access` and `roles` are passed; `access` used to silently discard `roles`. The personal-access-token mint form builds its i18n keys from the shared key helpers, and `ACTION_FORM_ENTITY` is now exported from `@cosmicdrift/kumiko-framework/ui-types`. The rate-limiting feature registers de/en copy for its error keys.",
+    "migration": "Remove `roles` from the `createSecretsFeature` options when `access` is set (or drop `access` and keep `roles`). Before, `roles` was silently ignored next to `access`."
+  },
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "rotateJob takes the raw DbConnection as a third argument; the rotate job declares escapeHatch (fw#2914).",
+    "detail": "JobContext.db is now a tenant-filtered TenantDb. Rotation re-encrypts every tenant's secrets, so the `rotate` registration declares `escapeHatch` and passes `ctx.db.unsafeRaw(reason)` to `rotateJob(payload, ctx, db)`.",
+    "migration": "Direct callers of the exported `rotateJob` pass the raw `DbConnection` as the third argument. Apps that only mount the feature need no change."
+  },
+  {
+    "version": "0.166.0",
+    "type": "improvement",
+    "title": "derivePurposeSecret: HKDF-based per-purpose secret derivation (fw#1623).",
+    "detail": "Previously copy-pasted in four apps as deriveSubSecret. The second parameter is a domain separator, not a label — the rename says so. auth-mfa gains resolveMfaTokenSecrets, which owns the two MFA purpose strings so a prod and a dev entrypoint cannot drift apart and invalidate each other's tokens."
+  }
+]

package/packages/bundled-features/src/secrets/constants.ts

@@ -0,0 +1,12 @@
+// @runtime client
+// secrets bundle constants — default RBAC for set/delete/list (#2296).
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+// Default-RBAC of the set/delete/list handlers, hard-wired to ["TenantAdmin"]
+// before #2296. Apps with their own role vocabulary override via
+// createSecretsFeature({ roles }) or createSecretsFeature({ access }) — the
+// rotate job stays untouched, it's a manual/ops path across all tenants by
+// design, not a per-tenant RBAC surface.
+export const DEFAULT_SECRETS_ROLES = ["TenantAdmin"] as const;
+export const DEFAULT_SECRETS_ACCESS: AccessRule = { roles: DEFAULT_SECRETS_ROLES };

package/packages/bundled-features/src/secrets/db/queries/read.ts

@@ -0,0 +1,16 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { StoredEnvelope } from "../../table.js";
+
+export async function selectTenantSecretEnvelope(
+  db: DbRunner,
+  tenantId: TenantId,
+  key: string,
+): Promise<StoredEnvelope | undefined> {
+  const rows = await asRawClient(db).unsafe<{ envelope: StoredEnvelope }>(
+    `SELECT envelope FROM read_tenant_secrets WHERE tenant_id = $1 AND key = $2 LIMIT 1`,
+    [tenantId, key],
+  );
+  return rows[0]?.envelope;
+}

package/packages/bundled-features/src/secrets/feature.ts

@@ -0,0 +1,197 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type AccessRule,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { SETTINGS_HUB_I18N } from "@cosmicdrift/kumiko-framework/i18n";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import * as z from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "./constants.js";
+import { createDeleteHandler } from "./handlers/delete.write.js";
+import { createListHandler } from "./handlers/list.query.js";
+import { rotateJob } from "./handlers/rotate.job.js";
+import { createSetHandler } from "./handlers/set.write.js";
+import { SECRETS_I18N } from "./i18n.js";
+import { secretReadSchema } from "./secrets-context.js";
+import { tenantSecretEntity, tenantSecretsTable } from "./table.js";
+
+const ROTATE_ESCAPE_HATCH_REASON = "re-encrypts every tenant's secrets with the new master key";
+
+/**
+ * Env-vars contract for the `secrets` feature. Apps merge this via
+ * `composeEnvSchema({ features: [secretsFeature, ...] })` so boot-time
+ * validation catches a missing/short KEK before the first `.get()` call.
+ *
+ * Rotation: declare additional versions (V2, V3, …) in the app's `extend`
+ * block — the env-master-key-provider scans the env for any
+ * `KUMIKO_SECRETS_MASTER_KEY_V<n>` matching `/^KUMIKO_SECRETS_MASTER_KEY_V(\d+)$/`
+ * and picks the highest as the active KEK unless
+ * `KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION` pins one explicitly.
+ */
+export const SECRETS_FEATURE_NAME = "secrets";
+
+export const secretsEnvSchema = z.object({
+  KUMIKO_SECRETS_MASTER_KEY_V1: z
+    .string()
+    .refine((v) => Buffer.from(v, "base64").length === 32, {
+      message: "must be base64-encoded 32 bytes (AES-256 KEK)",
+    })
+    .describe("AES-256 master-key (KEK) for tenant-secrets encryption.")
+    .meta({
+      kumiko: { kms: true, pulumi: { generator: "openssl rand -base64 32", secret: true } },
+    }),
+  KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: z
+    .string()
+    .regex(/^[1-9]\d*$/, "must be a positive integer (V<n> selector)")
+    .default("1")
+    .describe(
+      "Pins the active KEK version. Default '1'. Bump after writing a higher KUMIKO_SECRETS_MASTER_KEY_V<n>.",
+    ),
+});
+
+export {
+  createSecretsContext,
+  type SecretsContext,
+  type SecretsContextOptions,
+  TENANT_SECRET_READ_EVENT,
+} from "./secrets-context.js";
+export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./table.js";
+
+// AppContext carries ctx.secrets via extraContext. requireSecretsContext
+// wraps that raw context so every `.get(...)` call auto-includes the
+// current user + handler as audit metadata — feature code can't forget
+// to log the read (silent bypass of audit was the v1 gap).
+//
+// Surface bewusst minimal: HandlerContext-Pfade (Set/Delete-Handler) +
+// FileProviderContext-Pfade (S3-Plugin im Worker) liefern dieselben
+// zwei Felder, also reicht die schmale ctx-shape — kein voller
+// HandlerContext-Import noetig.
+export function requireSecretsContext(
+  ctx: { readonly secrets?: SecretsContext; readonly _userId?: string | undefined },
+  handlerName: string,
+): SecretsContext {
+  if (!ctx.secrets) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.secrets missing — pass ` +
+        "createSecretsContext({db, masterKeyProvider}) via extraContext.secrets at boot.",
+    });
+  }
+  const raw = ctx.secrets;
+  const userId = ctx._userId;
+  if (!userId) {
+    throw new InternalError({
+      message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
+    });
+  }
+  return {
+    get: (tenantId, key, overrideAudit) =>
+      raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
+    // No audit injection: has() is metadata-only and never logs a read.
+    has: raw.has.bind(raw),
+    set: raw.set.bind(raw),
+    delete: raw.delete.bind(raw),
+  };
+}
+
+export type SecretsFeatureOptions = {
+  /** Access rule for the `set`, `delete` and `list` handlers. Default
+   *  { roles: ["TenantAdmin"] }. Adopt the host's role vocabulary with
+   *  { roles: [...] }, or { openToAll: { reason: "..." } } to let any authenticated tenant
+   *  user manage secrets — note this is a much larger blast radius than the
+   *  default: tenant credentials (API keys, tokens) become writable/deletable,
+   *  and their previews/hints listable, by every tenant member, not just
+   *  admins. Mutually exclusive with `roles`. The `rotate` job is unaffected —
+   *  it's a manual, cross-tenant ops path, not per-tenant RBAC. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Mutually exclusive with `access`. */
+  readonly roles?: readonly string[];
+};
+
+function resolveSecretsAccess(opts: SecretsFeatureOptions): AccessRule {
+  if (opts.access !== undefined && opts.roles !== undefined) {
+    throw new InternalError({
+      message:
+        "createSecretsFeature: pass either `access` or `roles`, not both — " +
+        "`access` previously silently discarded `roles`, which looks like a refinement.",
+    });
+  }
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_SECRETS_ACCESS;
+}
+
+export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureDefinition {
+  const access = resolveSecretsAccess(opts);
+  return defineFeature(SECRETS_FEATURE_NAME, (r) => {
+    r.describe(
+      'Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host\'s role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).',
+    );
+    r.uiHints({
+      displayLabel: "Tenant Secrets",
+      category: "infrastructure",
+      recommended: true,
+    });
+    r.envSchema(secretsEnvSchema);
+
+    // `secrets` is a foundation feature auto-mounted even when `config` is
+    // not (see FOUNDATION_FEATURES, dev-server scaffold-app.ts), so it must
+    // ship the Settings-Hub chrome keys itself — server-authored
+    // r.translations are projected into FeatureSchema.translations and used
+    // as a client fallback bundle (create-app.tsx schemaTranslations),
+    // covering both boot-time validation and rendering without a web
+    // client-plugin for this feature.
+    r.translations({ keys: SETTINGS_HUB_I18N });
+    r.translations({ keys: SECRETS_I18N });
+
+    // ES entity: set/delete go through the executor, `tenantSecret.created/
+    // .updated/.deleted` events land on the aggregate stream. Reads fire a
+    // separate `tenantSecretRead` event per call (see secrets-context.get
+    // for the one-event-per-read rationale).
+    // Backing table: envelope/metadata/last_rotated_at + the (tenant,key)
+    // uniqueIndex are not expressible via the field-DSL (jsonb-without-default,
+    // now()-default), so the physical table is the DDL truth. Without this the
+    // generated migration omitted those columns → prod-500 (publicstatus#116).
+    r.entity("tenant-secret", tenantSecretEntity, { table: tenantSecretsTable });
+
+    // Read-audit domain-event. Registered here so ops tools + MSPs can
+    // discover the type; secrets-context.get parses payloads against
+    // `secretReadSchema` at write time because the low-level append() path
+    // skips ctx.appendEvent's schema-validation guard.
+    r.defineEvent("read", secretReadSchema, { piiFields: "none" });
+
+    // Per-tenant handlers (set/delete/list) run in the default tenant-scope,
+    // giving them the automatic ctx.db tenant-filter as extra defense.
+    // The rotation job deliberately reaches for ctx.db.unsafeRaw() (raw,
+    // cross-tenant) because rotation is a deployment-wide operation — no
+    // feature-wide r.systemScope() needed.
+    r.writeHandler(createSetHandler(access));
+    r.writeHandler(createDeleteHandler(access));
+    r.queryHandler(createListHandler(access));
+    // Manual-only by design: ops triggers rotation after a KEK version flip.
+    // BullMQ delivers to exactly one worker, so running it against a busy
+    // table on multiple instances is still safe.
+    r.job({
+      name: "rotate",
+      trigger: { manual: true },
+      escapeHatch: {
+        reason: ROTATE_ESCAPE_HATCH_REASON,
+      },
+      handler: (payload, ctx) =>
+        rotateJob(
+          payload,
+          ctx,
+          ctx.db.unsafeRaw(ROTATE_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ),
+    });
+
+    // Pre-ES had a separate `retention-cleanup` job scrubbing the audit
+    // table on a compliance-driven schedule (90d default). Post-ES the
+    // read-audit lives on the events-table as tenantSecretRead events;
+    // retention for those flows through the framework-wide `pruneEvents`
+    // ops-tool (see docs/plans/architecture/event-dispatcher.md §retention).
+    // No per-feature retention-job anymore.
+  });
+}

package/packages/bundled-features/src/secrets/handlers/delete.write.ts

@@ -0,0 +1,29 @@
+import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "../constants.js";
+import { requireSecretsContext } from "../feature.js";
+import { checkSecretKeyWrite } from "../write-gate.js";
+
+export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
+  return defineWriteHandler({
+    name: "delete",
+    description:
+      "Permanently removes the stored secret under the given key for the caller's tenant, breaking every feature that depends on that credential.",
+    agent: { risk: "high" },
+    schema: z.object({
+      key: z.string().min(1).max(100),
+    }),
+    access,
+    handler: async (event, ctx) => {
+      const secrets = requireSecretsContext(ctx, "secrets:write:delete");
+      const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key);
+      if (!gate.ok) return gate.failure;
+      const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
+        deletedBy: event.user.id,
+      });
+      if (!removed) return failNotFound("tenant-secret", event.payload.key);
+      return { isSuccess: true, data: { key: event.payload.key } };
+    },
+  });
+}

package/packages/bundled-features/src/secrets/handlers/list.query.ts

@@ -0,0 +1,40 @@
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { DEFAULT_SECRETS_ACCESS } from "../constants.js";
+import { tenantSecretsTable } from "../table.js";
+
+// Lists all secrets for the current tenant. Returns redactedPreview, never
+// the plaintext. Decryption would be pointless here anyway — this is the
+// TenantAdmin UI, not feature code that needs the value.
+export function createListHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
+  return defineQueryHandler({
+    name: "list",
+    description:
+      "Lists the secrets stored for the caller's tenant by key with a redacted preview, hint, key version and rotation date — never the plaintext; use it to check which credentials are set.",
+    schema: z.object({}),
+    access,
+    handler: async (event, ctx) => {
+      const rows = await ctx.db.selectMany<{
+        key: string;
+        kekVersion: number;
+        metadata: { redactedPreview?: string; hint?: string };
+        lastRotatedAt: unknown;
+        insertedAt: unknown;
+      }>(
+        tenantSecretsTable,
+        { tenantId: event.user.tenantId },
+        {
+          orderBy: { col: "key", direction: "asc" },
+        },
+      );
+      return rows.map((r) => ({
+        key: r.key,
+        redactedPreview: r.metadata.redactedPreview ?? null,
+        hint: r.metadata.hint ?? null,
+        kekVersion: r.kekVersion,
+        lastRotatedAt: r.lastRotatedAt,
+        createdAt: r.insertedAt,
+      }));
+    },
+  });
+}

package/packages/bundled-features/src/secrets/handlers/rotate.job.ts

@@ -0,0 +1,166 @@
+// Rotation job. Scans tenant_secrets for rows whose kekVersion is older
+// than provider.currentVersion() and rewraps their DEK under the new KEK
+// — the ciphertext itself never changes, only the 60-byte DEK wrapper
+// and the kek_version column. See architecture/core-secrets.md for the
+// full rotation story.
+//
+// The job is idempotent: re-running it after a partial failure picks up
+// the remaining old-version rows. Consumers that want a time-bound run
+// pass a maxDurationMs in the payload.
+//
+// Post-ES pivot: each rotation is an executor.update against the
+// tenantSecret aggregate. The resulting `.updated` event carries
+// {changes, previous} with BOTH envelopes — useful for a full rotation
+// audit trail (when did row X flip from v1 to v2, who triggered it).
+// Concurrency-guard shifts from the pre-ES `WHERE kek_version = old`
+// check to the executor's stream-version check; a parallel secrets.set
+// that landed the row on the new kekVersion first surfaces here as a
+// version_conflict error (counted as "skipped", not "failed").
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  decodeStoredEnvelope,
+  encodeStoredEnvelope,
+  rewrapDek,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared/index.js";
+import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table.js";
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_MAX_FAILURES = 10;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(tenantSecretsTable, tenantSecretEntity, {
+  entityName: "tenant-secret",
+});
+
+export type RotateJobPayload = {
+  readonly batchSize?: number;
+  readonly maxDurationMs?: number;
+  readonly maxFailures?: number;
+};
+
+export type RotateJobResult = {
+  readonly migrated: number;
+  readonly failed: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: ChunkedMigrationStopReason;
+};
+
+export async function rotateJob(
+  rawPayload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
+  const payload = rawPayload as RotateJobPayload; // @cast-boundary engine-payload
+  if (!ctx.masterKeyProvider) {
+    throw new InternalError({
+      message:
+        "[secrets:rotate] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+    });
+  }
+  const provider = ctx.masterKeyProvider;
+  const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  // 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.
+  const tdbCache = new Map<TenantId, TenantDb>();
+  function tdbFor(tenantId: TenantId): TenantDb {
+    let existing = tdbCache.get(tenantId);
+    if (!existing) {
+      existing = createTenantDb(db, tenantId, "system");
+      tdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  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;
+  }
+
+  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,
+        },
+      },
+      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";
+    }
+    return "migrated";
+  }
+
+  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)}`);
+}