@pithy-sh/core 0.10.0 → 0.12.0

package/src/controlPlane/migrationState/migrationState.ts

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+import type { Capability } from "../../capability/capability";
+import { composeDatabases } from "../../data/databases";
+import { InternalError } from "../../error/pithyError";
+import { collectMigrationSets } from "../../migrations/capabilitySets";
+import { composedMigrationKey, createMigrationRegistry, decomposeMigrationKey } from "../../migrations/registry";
+import { readMigrationLedger } from "../../migrations/runner";
+import { type MigrationLastGroup, readMigrationState } from "../../migrations/state";
+import type { CapabilityHealthInput } from "../discovery/health";
+import type { HealthSummary } from "../discovery/healthSummary";
+import type { MigrationDatabaseView, MigrationGroupView, MigrationView } from "../http/responses";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope";
+
+/**
+ * **Migration state over the control plane (#729).**
+ *
+ * A management client could not answer what is applied where, or whether a deploy left something behind:
+ * the seam registered a ping, the manifest and key rotation, and not one field of it was about a database.
+ * The read already existed — {@link readMigrationLedger} answers both directions — and it needs a D1
+ * binding and the composed provider in one process. **The Worker is the only thing holding both**, and it
+ * is the deployed build, so asked from its side the answer cannot be stale the way the project on disk is.
+ *
+ * Two halves. At assembly, {@link composeMigrationDatabases} builds what this Worker declares per bound
+ * database, through `collectMigrationSets` — the function `pithy migrate` composes with, so the route and
+ * `pithy doctor` compose the same way. Not always from the same inputs: on a D1 two Workers share, the CLI
+ * merges both Workers' sets and the route holds only its own, so `pending` and `undeclared` can differ
+ * there. On a database one Worker binds alone they agree. Per request, {@link readDatabaseMigrations} reads
+ * one database for the route and {@link readMigrationHealth} totals all of them for the manifest.
+ *
+ * **Read-only.** Nothing here runs, reverses or resets a migration. A screen somebody opened to ask must
+ * not hand them the thing that changes the schema.
+ *
+ * **`undeclared` is relative to this Worker.** Two Workers can be bound to one physical D1, and the CLI
+ * composes across all of them. A Worker composes only its own capabilities and cannot learn a co-bound
+ * Worker's, so from inside one, every migration the other shipped to the shared database reads as
+ * undeclared. That is why `undeclaredMigrations` grades nothing.
+ */
+
+/** One database this Worker binds, with what this build declares for it. Built once, at assembly. */
+export interface ComposedMigrationDatabase {
+  /** The database name, as capabilities declare it in `databases`. */
+  database: string;
+  /** The D1 binding it is read through. */
+  binding: string;
+  /** Every migration this build declares for it — empty for a database bound with none. */
+  provider: MigrationProvider;
+  /** Each declared migration's namespace, known from the set it came from. */
+  namespaces: ReadonlyMap<string, string>;
+}
+
+/** A provider declaring nothing, for a database bound with no migrations: everything applied is undeclared. */
+const NOTHING_DECLARED: MigrationProvider = { getMigrations: async () => ({}) };
+
+/**
+ * Every database this Worker binds, with the provider this build composes for it, sorted by name.
+ *
+ * One entry per database `composeDatabases` maps to a binding — the same map the request registry is built
+ * from — so a database bound with no migrations is still reported. Leaving it out would read as not bound.
+ */
+export function composeMigrationDatabases(capabilities: readonly Capability[]): ComposedMigrationDatabase[] {
+  const sets = collectMigrationSets([...capabilities]);
+  const registry = createMigrationRegistry(sets);
+  const bound = composeDatabases([...capabilities]);
+  return Object.entries(bound)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([database, group]) => {
+      const namespaces = new Map<string, string>();
+      for (const set of sets) {
+        if (set.database !== database) continue;
+        for (const localKey of Object.keys(set.migrations))
+          namespaces.set(composedMigrationKey(set, localKey), set.namespace);
+      }
+      return { database, binding: group.binding, provider: registry[database] ?? NOTHING_DECLARED, namespaces };
+    });
+}
+
+/**
+ * One migration as the route reports it.
+ *
+ * A declared migration's namespace comes from the set it was declared in. An undeclared one has only its
+ * key, so it is decomposed — and a key no registry composed answers null rather than a guess.
+ */
+export function migrationView(name: string, namespaces: ReadonlyMap<string, string>): MigrationView {
+  return { name, namespace: namespaces.get(name) ?? decomposeMigrationKey(name)?.namespace ?? null };
+}
+
+/** The D1 binding for `entry`, or a refusal naming it — a Worker missing the binding cannot read it. */
+function bindingOf(env: Record<string, unknown>, entry: ComposedMigrationDatabase): D1Database {
+  const database = env[entry.binding];
+  if (database == null) {
+    throw new InternalError({
+      message: `The ${entry.binding} binding is missing, so database "${entry.database}" cannot be read.`,
+      action: `Declare ${entry.binding} in this Worker's wrangler.jsonc, then deploy again.`,
+    });
+  }
+  return database as D1Database;
+}
+
+function groupView(group: MigrationLastGroup, namespaces: ReadonlyMap<string, string>): MigrationGroupView {
+  return {
+    group: group.group,
+    appliedAt: group.appliedAt.toISOString(),
+    migrations: group.migrations.map((name) => migrationView(name, namespaces)),
+    position:
+      group.position.state === "top"
+        ? { state: "top" }
+        : {
+            state: "buried",
+            above: group.position.above,
+            ungrouped: group.position.ungrouped.map((name) => migrationView(name, namespaces)),
+          },
+  };
+}
+
+/**
+ * Read one database's migration state for the route.
+ *
+ * **A database that cannot be read is `unreadable`, and costs only itself.** The cause goes to
+ * `onUnreadable` — the route logs it, where the operator's context stays the operator's — and never into
+ * the view: a D1 error can name a table or a query, and the view crosses to a management client.
+ */
+export async function readDatabaseMigrations(
+  env: Record<string, unknown>,
+  entry: ComposedMigrationDatabase,
+  onUnreadable?: (entry: ComposedMigrationDatabase, cause: unknown) => void,
+): Promise<MigrationDatabaseView> {
+  try {
+    const state = await readMigrationState(bindingOf(env, entry), entry.provider);
+    const view = (name: string) => migrationView(name, entry.namespaces);
+    return {
+      state: "readable",
+      database: entry.database,
+      binding: entry.binding,
+      applied: state.applied.map(view),
+      pending: state.pending.map(view),
+      undeclared: state.undeclared.map(view),
+      lastGroup: state.lastGroup ? groupView(state.lastGroup, entry.namespaces) : null,
+    };
+  } catch (cause) {
+    onUnreadable?.(entry, cause);
+    return { state: "unreadable", database: entry.database, binding: entry.binding };
+  }
+}
+
+/**
+ * The two health keys the seam contributes to its own manifest entry.
+ *
+ * Both `indexed`: one small select per bound database, bounded by the declared migration count rather
+ * than by the adopter's data. Both behind {@link MIGRATIONS_READ_SCOPE}, which the seam's own route
+ * requires, so a connection without it gets no value rather than a zero.
+ *
+ * **`undeclaredMigrations` declares no nominal, on purpose.** From inside one Worker, a database shared
+ * with another lists the other's migrations as undeclared, so `atMost: 0` would report a corrupted chain
+ * on a database that is entirely fine. Null is what a client reads as unknowable, never as healthy (#471).
+ */
+export const MIGRATION_HEALTH_KEYS = [
+  {
+    key: "pendingMigrations",
+    kind: "count",
+    states: null,
+    scope: MIGRATIONS_READ_SCOPE,
+    cost: "indexed",
+    summary: "Migrations this build declares that a bound database has not applied.",
+    nominal: { atMost: 0 },
+  },
+  {
+    key: "undeclaredMigrations",
+    kind: "count",
+    states: null,
+    scope: MIGRATIONS_READ_SCOPE,
+    cost: "indexed",
+    summary:
+      "Migrations a bound database holds that this Worker does not declare. Relative to this Worker: a database shared with another lists that Worker's migrations here.",
+    nominal: null,
+  },
+] as const satisfies CapabilityHealthInput["keys"];
+
+/**
+ * Total pending and undeclared across every bound database, for the manifest.
+ *
+ * **Throws rather than total a database it could not read.** A partial total is a zero for the database
+ * nobody read. The seam catches the throw and reports the summary `unavailable`, which a client reads as
+ * unknown — null is never zero.
+ */
+export async function readMigrationHealth(
+  env: Record<string, unknown>,
+  databases: readonly ComposedMigrationDatabase[],
+): Promise<HealthSummary> {
+  const ledgers = await Promise.all(
+    databases.map((entry) => readMigrationLedger(bindingOf(env, entry), entry.provider)),
+  );
+  return {
+    pendingMigrations: ledgers.reduce((total, ledger) => total + ledger.pending.length, 0),
+    undeclaredMigrations: ledgers.reduce((total, ledger) => total + ledger.undeclared.length, 0),
+  };
+}

package/src/controlPlane/migrations/0003_connection_principal.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+ *
+ * **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+ * it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+ *
+ * **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+ * principal, and none can be recovered: most of the trail that might be mined for one names a token
+ * rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+ * end. So null means *registered before principals were recorded*, the connection keeps working exactly
+ * as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+ * is set only by registering again, under a signed-in session.
+ *
+ * **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+ * other two exist for the adopter's own review, on their own side.
+ */
+export const controlplane_0003_connection_principal: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("authorizedBy", "text").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("actorKind", "text").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").addColumn("purpose", "text").execute();
+  },
+
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    // Dropped column by column, newest first, for the reason `0002` gives: D1's engine drops a column in
+    // place, and a twelve-step rebuild would rewrite every row of a table holding live credentials.
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("purpose").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("actorKind").execute();
+    await db.schema.alterTable("pithyControlplaneConnections").dropColumn("authorizedBy").execute();
+  },
+};

package/src/controlPlane/scope/scope.ts

@@ -78,8 +78,31 @@ export const MANIFEST_READ_SCOPE: ControlPlaneScope = "manifest:read";
 export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "keys:rotate";
 
 /**
- * Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
- * Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+ * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+ * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+ */
+export const MIGRATIONS_READ_SCOPE: ControlPlaneScope = "migrations:read";
+
+/**
+ * Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
+ * path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+ *
+ * **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
+ * reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
+ * classes and counts only, so a connection without this one still sees the posture headline.
+ */
+export const PRIVACY_READ_SCOPE: ControlPlaneScope = "privacy:read";
+
+/**
+ * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+ * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ *
+ * **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+ * every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
+ * derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
+ * otherwise drop out.
  */
 export const SEAM_SCOPES: readonly ControlPlaneScope[] = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
 

package/src/controlPlane/token/base64url.ts

@@ -27,7 +27,7 @@ const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
 export function base64UrlEncode(bytes: Uint8Array): string {
   // Built one character at a time. `String.fromCharCode(...bytes)` overflows the argument stack on
   // inputs this seam genuinely sees — a request body digest, an exported key — so the loop is the
-  // implementation, not a style choice. (Same reason as `secrets/src/crypto/envelope.ts`.)
+  // implementation, not a style choice. (Same reason as `core/src/crypto/envelope.ts`.)
   let binary = "";
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

package/src/createBackend.ts

@@ -3,6 +3,7 @@
 
 import { Hono } from "hono";
 import { z } from "zod";
+import { noActingOrganization } from "./access/acting";
 import { noopEmit } from "./audit/recorder";
 import { BindingSpec } from "./capability/bindings";
 import type {
@@ -18,6 +19,7 @@ import { validateBindings } from "./capability/validateBindings";
 import { pithyCommandOf } from "./cli/command";
 import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
+import { registerReadinessGuards } from "./controlPlane/http/readiness";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
 import { ValidationError } from "./error/pithyError";
@@ -30,6 +32,7 @@ import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
 import type { RouteGroup } from "./openapi/document";
 import { recordRouteGroups } from "./openapi/routeGroups";
+import { refuseEncryptedKvStores } from "./privacy/encryptedColumns";
 import { HEALTH_PATH } from "./worker/health";
 import { workerVersion } from "./worker/identity";
 import { registeredWorkflowBinding } from "./workflow/bindings";
@@ -176,6 +179,9 @@ export function createBackend<
   // `@pithy-sh/i18n`'s middleware replaces it per request; nothing else ever does.
   const defaultTranslator = bakedTranslator(catalogFor(messages, DEFAULT_LOCALE));
   const namespaces = composeKv(all);
+  // An encrypted field in a KV store is refused here, at boot (#390): a KV envelope cannot be found by key version,
+  // so it could never be rotated. The refusal names the store, the field and D1.
+  refuseEncryptedKvStores(all);
   const workflows = composeWorkflows(all);
 
   // Each named database implies its D1 binding; each KV namespace implies its KV binding; each
@@ -205,15 +211,19 @@ export function createBackend<
   // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.
   const baseLogger = options.logger ?? createWorkerLogger();
 
+  // Every composed capability's `adminRoutes`, folded per path: the surface CORS answers for, and the
+  // surface no readiness guard may refuse. One computation, so the two cannot disagree.
+  const adminSurface = corsSurface(all);
+
   // **CORS first — before this Worker's own base middleware and before every capability's.**
   //
   // Hono runs middleware in registration order, so whatever registers first is the only thing that can
   // put a header on a response somebody else short-circuits. Capabilities short-circuit for real
-  // reasons: `@pithy-sh/vector`'s `provisionGuard` is an `app.use("*")` that throws on every request
-  // when the provision record disagrees with config. Register CORS after that and a misprovisioned
-  // Worker answers a management call with no `Access-Control-Allow-Origin`, so the dashboard sees the
-  // opaque `fetch` TypeError this exists to remove — on precisely the misconfiguration where the
-  // operator most needs to read the real message. Ahead of `validateBindings` for the same reason.
+  // reasons: a rate limit, or a readiness guard like `@pithy-sh/vector`'s `provisionGuard`, which
+  // throws on every request off the admin surface when the provision record disagrees with config.
+  // Register CORS after either and the refusal reaches a browser with no `Access-Control-Allow-Origin`,
+  // so the dashboard sees the opaque `fetch` TypeError this exists to remove instead of the reason.
+  // Ahead of `validateBindings` for the same reason.
   //
   // It lives here rather than in the capability's `middleware` hook because that hook runs inside the
   // loop below, in the adopter's composition order, and this must not depend on where they listed
@@ -222,7 +232,7 @@ export function createBackend<
   const controlPlane = all.find(isControlPlaneCapability);
   if (controlPlane) {
     const cors = controlPlane.controlPlaneConfig;
-    registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+    registerControlPlaneCors(app, adminSurface, allowedOriginSet(cors), cors.corsMaxAgeSeconds);
   }
 
   let validated = false;
@@ -233,6 +243,9 @@ export function createBackend<
       validated = true;
     }
     if (c.get("auth") === undefined) c.set("auth", null);
+    // Nothing in force until `@pithy-sh/organization`'s middleware publishes a resolver. Media and storage
+    // read it to scope every record, so a Worker with no tenancy answers null rather than throwing.
+    if (c.get("actingOrganization") === undefined) c.set("actingOrganization", noActingOrganization);
     // Null means nothing negotiated, which is not the same fact as "the default was chosen" — only
     // `@pithy-sh/i18n` ever sets it, and `c.var.t` works either way.
     if (c.get("locale") === undefined) c.set("locale", null);
@@ -316,6 +329,15 @@ export function createBackend<
   for (const cap of all) {
     for (const middleware of cap.middleware ?? []) middleware(app);
   }
+  // Readiness guards after every capability's middleware, so the verifier, `emit` and every rate limit
+  // are in place, and before any capability's routes, so a terminal handler cannot outrun them. Each is
+  // skipped on the admin surface: the control plane answers whatever else is wrong with the Worker,
+  // because it is how a management client finds out what that is (#763).
+  registerReadinessGuards(
+    app,
+    adminSurface,
+    all.flatMap((cap) => cap.readiness ?? []),
+  );
   // Each hook's slice of the route table is noted as it mounts, so the OpenAPI contract can tag every
   // operation with the capability that owns it (`openapi/routeGroups.ts`).
   for (const cap of all) {

package/src/createEntrypoint.ts

@@ -4,6 +4,7 @@
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
 import type { Capability, CapabilityEmailHandler } from "./capability/capability";
 import { type CreateBackendOptions, createBackend } from "./createBackend";
+import { withLocalServices } from "./worker/serviceLoopback";
 import { triggerWorkflow } from "./workflow/dispatch";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register";
 
@@ -88,7 +89,11 @@ export function createEntrypoint<
   const registry = composeWorkflows(all);
   const scheduled = scheduledWorkflows(registry);
 
-  const entrypoint: PithyEntrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+  // Under `pithy dev`, a service binding's local stand-in goes into the env before anything reads it — the
+  // binding check included (#617). Anywhere else this hands back the env it was given.
+  const entrypoint: PithyEntrypoint = {
+    fetch: (request, env, ctx) => app.fetch(request, withLocalServices(env), ctx),
+  };
 
   // Cron-carrying jobs get the Worker's one `scheduled` entry. Each is started independently so one
   // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
@@ -102,7 +107,7 @@ export function createEntrypoint<
         // can never receive on a schedule therefore fails loudly here, which is the author's bug and
         // is exactly what should surface.
         try {
-          await triggerWorkflow(env, registry, entry.key, {});
+          await triggerWorkflow(withLocalServices(env), registry, entry.key, {});
         } catch (error) {
           failures.push(error);
         }
@@ -114,7 +119,8 @@ export function createEntrypoint<
   // Only expose an `email` handler when something actually handles inbound mail — an inert one would
   // silently drop any message Email Routing delivered to this Worker.
   if (handlers.length > 0) {
-    entrypoint.email = async (message, env, ctx) => {
+    entrypoint.email = async (message, given, ctx) => {
+      const env = withLocalServices(given);
       if (handlers.length === 1) {
         await handlers[0]?.(message, env, ctx);
         return;

package/src/crypto/envelope.ts

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../error/pithyError";
+
+/**
+ * **The AES-256-GCM envelope: one primitive, two callers** (#390).
+ *
+ * It was `@pithy-sh/secrets`' own, ported from the CMS `secretsCrypto`, and it sealed that capability's rows and
+ * nothing else. Field encryption needs the same primitive inside an adopter's own Workers, and a capability may not
+ * depend on another's internals (principle 4), so it lives in core now and both callers import it from here. The
+ * format did not change: a row secrets sealed before the move opens after it, byte for byte.
+ *
+ * ## Two version axes
+ *
+ * `currentVersion` says which key seals new writes, and the `keyVersion` persisted on every envelope says which key
+ * opens it. A rotation adds a version, moves the pointer and keeps the old key until nothing is sealed under it, so
+ * a row opens under whichever version sealed it, for as long as that version is in the set. This is the
+ * *encryption-key* version. A secret's *value* version is a separate concern (`secrets/src/crypto/versionedValue.ts`).
+ *
+ * The config is the uniform `{ currentVersion, versions }` shape every versioned value uses, plus `lastRotatedAt`
+ * beside it as rotation metadata. Version keys are stringified integers, so reading the keys is a full-set read:
+ * every still-valid version, never the current one alone.
+ *
+ * ## The bound context is the caller's, and it is authenticated
+ *
+ * Every seal binds a **context** string as AES-GCM additional authenticated data. It is not encrypted; it is bound.
+ * Without it a ciphertext is valid under the key alone, so one lifted from one row and written into another opens
+ * cleanly, and every decision about which value a caller gets lives in the query above. With it, a moved ciphertext
+ * fails inside the primitive, however that query is later rewritten.
+ *
+ * The primitive takes the context whole, because what to bind is the caller's fact, not this module's:
+ *
+ * - `@pithy-sh/secrets` binds `pithy.secrets.v1:<stored name>` — exactly what it always bound.
+ * - A field marked `encrypted()` binds `pithy/enc/1:<declared name>:<field path>:<primary key>` (`../privacy/sealed`).
+ *
+ * Each prefix is versioned, so a later change to what is bound is a deliberate, visible break, and the two prefixes
+ * are distinct, so a secret's ciphertext never opens as a field and a field's never opens as a secret. **What is bound
+ * must be stable for the life of the ciphertext**: each caller states why its own context is.
+ *
+ * An empty context is refused on both halves. It binds nothing, and it would fail open rather than loudly.
+ */
+
+/** The key set a seal draws from: which version is current, every still-valid key, and when it last rotated. */
+export const EncryptionConfig = z
+  .object({
+    currentVersion: z
+      .string()
+      .meta({ multiline: false })
+      .describe("The version key (a stringified integer) whose key seals new writes — the active key."),
+    versions: z
+      // Every string leaf of a `json` secret says whether it fits on a terminal line, and a base64 key
+      // does. See `cli/promptPlan.ts`; held repo-wide by `packages/cli/src/ci/secretFieldLines.test.ts`.
+      .record(z.string(), z.string().meta({ multiline: false }))
+      .describe(
+        "Every still-valid key: version key (stringified integer) → base64-encoded AES-256 key. Holds the current key plus any prior versions still needed to open values not yet re-sealed.",
+      ),
+    lastRotatedAt: z.iso
+      .datetime()
+      .meta({ multiline: false })
+      .describe(
+        "ISO-8601 timestamp of the last rotation; the rotation cron compares against it to decide when to rotate.",
+      ),
+  })
+  .describe(
+    "A versioned AES-256 key set: the uniform versioned-value shape (currentVersion + versions) plus rotation metadata. Secrets' master key (`SECRETS_ENCRYPTION_KEYS`) and the field key (`PITHY_FIELD_KEYS`) both take it.",
+  );
+export type EncryptionConfig = z.output<typeof EncryptionConfig>;
+
+/**
+ * One AES-256-GCM envelope: base64 ciphertext, base64 IV, and the key version that sealed it.
+ *
+ * The bound context is deliberately not in here. It is supplied by the caller on the way back in, from the row's own
+ * identity, so a row that has been moved cannot carry its old context with it.
+ */
+export const EncryptedEnvelope = z
+  .object({
+    encryptedValue: z.string().min(1).describe("The AES-256-GCM ciphertext and tag, base64."),
+    iv: z.string().min(1).describe("The 12-byte initialization vector, base64. Fresh for every seal."),
+    keyVersion: z
+      .number()
+      .int()
+      .describe("The version of the key that sealed this value: the key set entry that opens it."),
+  })
+  .describe("An AES-256-GCM envelope: the ciphertext, its IV, and the key version that sealed it.");
+export type EncryptedEnvelope = z.output<typeof EncryptedEnvelope>;
+
+/** What the refusals name the key set by — its binding, so an operator knows which entry to inspect. */
+export interface EnvelopeOptions {
+  /** The binding the key set was read from, e.g. `SECRETS_ENCRYPTION_KEYS`. Defaults to `the key set`. */
+  keys?: string;
+}
+
+/** Base64-encode raw bytes without spreading into `fromCharCode` (stack-safe, lint-clean). */
+export function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Decode base64 to raw bytes. */
+export function fromBase64(b64: string): Uint8Array<ArrayBuffer> {
+  return Uint8Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/** The authenticated data for one seal. An empty context is refused: it would bind nothing. */
+function additionalData(context: string): Uint8Array<ArrayBuffer> {
+  if (context.length === 0) {
+    throw new InternalError({ detail: "the envelope needs a context to bind; an empty context binds nothing" });
+  }
+  // Copied through `from` so the view is backed by an `ArrayBuffer` rather than an `ArrayBufferLike`:
+  // workers-types types `encode` as the wider one, which no longer satisfies `BufferSource`.
+  return Uint8Array.from(new TextEncoder().encode(context));
+}
+
+/** The raw key bytes for `version`, or a refusal naming the key set. Never the key itself. */
+export function keyBytes(
+  config: EncryptionConfig,
+  version: number,
+  options: EnvelopeOptions = {},
+): Uint8Array<ArrayBuffer> {
+  const b64 = config.versions[String(version)];
+  if (!b64) {
+    throw new InternalError({
+      detail: `encryption key version ${version} not present in ${options.keys ?? "the key set"}`,
+    });
+  }
+  return fromBase64(b64);
+}
+
+/** Import the AES-GCM key for `version` from the config, or throw if that version is absent. */
+async function importKey(
+  config: EncryptionConfig,
+  version: number,
+  usage: ("encrypt" | "decrypt")[],
+  options: EnvelopeOptions,
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", keyBytes(config, version, options), "AES-GCM", false, usage);
+}
+
+/**
+ * Seal `plaintext` under the config's current key version, binding `context`. The IV is 12 fresh random bytes, so
+ * two seals of one value never share a ciphertext.
+ */
+export async function encryptValue(
+  config: EncryptionConfig,
+  context: string,
+  plaintext: string,
+  options: EnvelopeOptions = {},
+): Promise<EncryptedEnvelope> {
+  const aad = additionalData(context);
+  const keyVersion = Number(config.currentVersion);
+  const key = await importKey(config, keyVersion, ["encrypt"], options);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: aad },
+    key,
+    new TextEncoder().encode(plaintext),
+  );
+  return { encryptedValue: toBase64(new Uint8Array(ciphertext)), iv: toBase64(iv), keyVersion };
+}
+
+/**
+ * Open an envelope sealed under `context`. The key version may differ from `currentVersion` during a rotation window;
+ * the matching key must still be in the config.
+ *
+ * A missing key version, a tampered ciphertext, the wrong key, or a ciphertext sealed under another context all throw
+ * — never the plaintext or key material. GCM cannot tell those apart, and separating them for the caller would be an
+ * oracle: the `detail` names the context the open was *attempted under*, which is what an operator needs. Each caller
+ * binds a context composed from validated identifiers, so it is safe in a log; neither binds a value.
+ */
+export async function decryptValue(
+  config: EncryptionConfig,
+  context: string,
+  envelope: EncryptedEnvelope,
+  options: EnvelopeOptions = {},
+): Promise<string> {
+  const aad = additionalData(context);
+  const key = await importKey(config, envelope.keyVersion, ["decrypt"], options);
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: fromBase64(envelope.iv), additionalData: aad },
+      key,
+      fromBase64(envelope.encryptedValue),
+    );
+    return new TextDecoder().decode(plaintext);
+  } catch (cause) {
+    throw new InternalError(
+      {
+        detail: `AES-GCM decrypt failed for '${context}' under key version ${envelope.keyVersion}: wrong key, tampered ciphertext, or a ciphertext sealed under a different context`,
+      },
+      { cause },
+    );
+  }
+}