@pithy-sh/core 0.11.0 → 0.13.0

package/src/controlPlane/http/responses.ts

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { PrivacyPosture } from "../../privacy/posture";
+import { PRIVACY_SOURCES } from "../../privacy/report";
 import { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, Ed25519PublicJwk } from "../data/connection";
 
 /**
@@ -228,3 +230,101 @@ export const ControlPlaneMigrationsResponse = z
   })
   .describe("What is applied, pending and undeclared in each bound database, and which run put it there.");
 export type ControlPlaneMigrationsResponse = z.output<typeof ControlPlaneMigrationsResponse>;
+
+/**
+ * One marked field, as `GET {basePath}/privacy` reports it (#132).
+ *
+ * **The per-field record.** Since #390 it says whether the field rests encrypted beside `class`, so "which of
+ * your PHI fields are encrypted" is a derivation over this list rather than a second inventory to keep.
+ */
+export const PrivacyFieldView = z
+  .object({
+    path: z
+      .string()
+      .describe(
+        "Where the field sits. A D1 column path (`email`, `address.line1`, `profile.phone` inside a JSON column), or a KV entry's part first (`key.email`, `value.token`, `metadata.ip`, or `value` for a whole marked value). An array element is `[]`, a record's value `*`.",
+      ),
+    class: z
+      .string()
+      .describe("The privacy class it is marked with: `secret`, `pii`, `phi`, `pci`, or an adopter's own."),
+    truncated: z
+      .literal(true)
+      .optional()
+      .describe(
+        "Set where the class is assumed rather than found: a read ran out of its budget there, or the schema could not be read at all, so any class may be marked below it. Absent where the schema was read to the end.",
+      ),
+    sameAs: z
+      .string()
+      .optional()
+      .describe(
+        "Set on a reference: the path this field's position was first listed under, once the list reached its cap on paths. The class is marked somewhere beneath both, and the paths beneath this one are those beneath that one.",
+      ),
+    encryptedAtRest: z
+      .boolean()
+      .optional()
+      .describe(
+        "Whether the field rests encrypted (#390). Absent where the core cannot say — an assumed class, a reference, or a core older than encrypted fields — and never defaulted to false.",
+      ),
+    unrotatable: z
+      .literal(true)
+      .optional()
+      .describe(
+        "Set on an encrypted field whose storage is not D1: it can never be rotated, and it blocks retirement.",
+      ),
+  })
+  .describe("One marked field and its class.");
+export type PrivacyFieldView = z.output<typeof PrivacyFieldView>;
+
+/** One storage schema holding at least one marked field. */
+export const PrivacySchemaView = z
+  .object({
+    capability: z
+      .string()
+      .describe("The capability that declared the schema, as the manifest's `capabilities[]` names it."),
+    storage: z.enum(PRIVACY_SOURCES).describe("Where it is stored: a `d1` table or a `kv` store."),
+    container: z.string().describe("The D1 database name or the KV namespace name it lives in."),
+    name: z.string().describe("The table name, or the KV store name."),
+    fields: z.array(PrivacyFieldView).describe("Every marked field in it, in schema order."),
+    encrypted: z
+      .array(
+        z
+          .object({
+            path: z.string().describe("Where the encrypted field sits, on the same paths as `fields[].path`."),
+            unrotatable: z
+              .literal(true)
+              .optional()
+              .describe("Set where the storage is not D1, so the field can never be rotated."),
+          })
+          .describe("One encrypted field."),
+      )
+      .optional()
+      .describe(
+        "Every field marked encrypted at rest, classed or not (#390). Absent on a Worker whose core predates encrypted fields.",
+      ),
+  })
+  .describe("One storage schema and the marked fields it holds.");
+export type PrivacySchemaView = z.output<typeof PrivacySchemaView>;
+
+/**
+ * `GET /control-plane/privacy` — the full inventory, behind `privacy:read` (#132).
+ *
+ * Derived at runtime from the schemas this Worker composed, walked once per isolate. The manifest's `privacy`
+ * block is the headline; this is the detail, and it names fields, which is why it has a scope of its own.
+ */
+export const ControlPlanePrivacyResponse = z
+  .object({
+    environment: z.string().describe("The environment this Worker answers for."),
+    posture: PrivacyPosture.describe("The declared and observed classes, the delta, and the console gate."),
+    schemasWalked: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("How many storage schemas were walked, marked or not, across the sources `posture.sources` names."),
+    schemas: z
+      .array(PrivacySchemaView)
+      .describe("Every schema holding a marked field, in composition order. A schema with none is not listed."),
+  })
+  .describe(
+    "Every schema this Worker stores that holds a marked field, each field's path and class, and where it lives.",
+  );
+export type ControlPlanePrivacyResponse = z.output<typeof ControlPlanePrivacyResponse>;

package/src/controlPlane/http/routes.ts

@@ -6,7 +6,13 @@ import type { PithyHonoEnv } from "../../capability/capability";
 import { describeRoute } from "../../http/routeSpec";
 import { validate } from "../../http/validation";
 import { type AdminRoute, ControlPlaneManifest } from "../discovery/adminRoute";
-import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, MIGRATIONS_READ_SCOPE } from "../scope/scope";
+import {
+  ANY_VERIFIED_CALLER,
+  KEYS_ROTATE_SCOPE,
+  MANIFEST_READ_SCOPE,
+  MIGRATIONS_READ_SCOPE,
+  PRIVACY_READ_SCOPE,
+} from "../scope/scope";
 import { requireControlPlane } from "./guard";
 import {
   type ControlPlaneHandlerDeps,
@@ -15,12 +21,14 @@ import {
   manifestHandler,
   migrationsHandler,
   pingHandler,
+  privacyHandler,
   registerKeyHandler,
 } from "./handlers";
 import {
   ControlPlaneKeysResponse,
   ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
+  ControlPlanePrivacyResponse,
   ExpireKeyResponse,
   RegisterKeyResponse,
 } from "./responses";
@@ -35,6 +43,7 @@ import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas
  *   POST /control-plane/keys                  → register a key               (keys:rotate)
  *   POST /control-plane/keys/:keyId/expire    → retire a superseded key      (keys:rotate)
  *   GET  /control-plane/migrations            → where each database stands   (migrations:read)
+ *   GET  /control-plane/privacy               → what each schema holds        (privacy:read)
  *
  * Every one is `control-plane` and default-denied — with no connection registered they all answer 403,
  * and that is the shipped state of a Worker nobody has connected.
@@ -100,6 +109,13 @@ export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
       summary:
         "What each bound database has applied, what is pending, what is undeclared, and which run put it there. Undeclared is relative to this Worker.",
     },
+    {
+      method: "GET",
+      path: `${basePath}/privacy`,
+      scope: PRIVACY_READ_SCOPE,
+      summary:
+        "Every stored schema holding a privacy-marked field, each field's path and class, and where it lives. Derived from the running code.",
+    },
   ];
 }
 
@@ -184,4 +200,18 @@ export function registerControlPlaneRoutes(
     requireControlPlane(MIGRATIONS_READ_SCOPE),
     migrationsHandler(deps),
   );
+
+  app.get(
+    `${basePath}/privacy`,
+    describeRoute({
+      summary: "Report every stored field marked with a privacy class.",
+      description:
+        "Every D1 table and KV store this Worker composed that holds a privacy-marked field, with each field's path, its class and where it is stored, beside the declared-and-observed posture. Derived at runtime from the deployed schemas. Read-only.",
+      verification: "control-plane",
+      scopes: [PRIVACY_READ_SCOPE],
+      responses: { 200: ControlPlanePrivacyResponse },
+    }),
+    requireControlPlane(PRIVACY_READ_SCOPE),
+    privacyHandler(deps),
+  );
 }

package/src/controlPlane/scope/scope.ts

@@ -85,13 +85,24 @@ export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "keys:rotate";
  */
 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} is absent on purpose.** It 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.
+ * **{@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

@@ -32,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";
@@ -178,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

package/src/createEntrypoint.ts

@@ -28,7 +28,13 @@ export interface PithyEntrypoint {
    */
   email?: (message: ForwardableEmailMessage, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
   /**
-   * The Worker `scheduled` handler — starts every registered job that declares a `schedule`.
+   * The Worker `scheduled` handler — starts every registered job whose `schedule` is the cron that fired.
+   *
+   * A Worker carries one `scheduled` entry for all of its `triggers.crons`, and the runtime names the one
+   * that fired on `controller.cron`, verbatim as `wrangler.jsonc` declares it. Only the jobs whose
+   * `schedule` is that string start: a daily job composed beside an hourly one must not run every hour,
+   * and the hourly one must not run an extra time at the daily job's minute (#622). An event that names
+   * no cron, or one no job declares, starts nothing.
    *
    * **Present only when at least one job carries a cron.** The reason differs from `email`'s: an
    * inert `email()` silently *drops* mail, which is a correctness bug, whereas an inert `scheduled()`
@@ -50,6 +56,13 @@ export interface PithyEntrypoint {
   scheduled?: (controller: unknown, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
 }
 
+/** The cron expression a `scheduled` event fired for, or `undefined` when the event names none. */
+function firedCron(controller: unknown): string | undefined {
+  if (typeof controller !== "object" || controller === null) return undefined;
+  const cron = (controller as { cron?: unknown }).cron;
+  return typeof cron === "string" ? cron : undefined;
+}
+
 /**
  * The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
  * the next sees an empty stream. When more than one capability handles inbound mail we buffer the
@@ -99,9 +112,11 @@ export function createEntrypoint<
   // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
   // rethrown after the pass so the invocation is still recorded as failed.
   if (scheduled.length > 0) {
-    entrypoint.scheduled = async (_controller, env) => {
+    entrypoint.scheduled = async (controller, env) => {
+      const cron = firedCron(controller);
       const failures: unknown[] = [];
       for (const entry of scheduled) {
+        if (entry.spec.schedule !== cron) continue;
         // A cron supplies no caller input, which is an *empty* parameter object, not an absent one —
         // `z.object({})` accepts `{}` and rejects `undefined`. A job whose schema requires fields it
         // can never receive on a schedule therefore fails loudly here, which is the author's bug and

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 },
+    );
+  }
+}

package/src/crypto/fieldKeys.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { remedy } from "../cli/command";
+import { InternalError } from "../error/pithyError";
+import { EncryptionConfig } from "./envelope";
+
+/**
+ * **The field key: what an app Worker seals its encrypted fields with** (#390).
+ *
+ * `PITHY_FIELD_KEYS` is an {@link EncryptionConfig}, the same versioned shape as secrets' master key, and it is a
+ * **different key on purpose**. Field encryption seals and opens inside the adopter's own Workers, so every Worker that
+ * holds an encrypted field must hold the key it uses. Were that the master key `SECRETS_ENCRYPTION_KEYS`, every such
+ * Worker would hold the key to the whole secrets vault, and one compromised would open it. A key of its own limits
+ * that to the fields: a Worker that holds an encrypted field and composes no `secrets` is bound this key and never
+ * the master key.
+ *
+ * It is not a second mechanism: `pithy secrets provision` mints it beside the master key, in the same format, binds
+ * it to every Worker that holds an encrypted field, and the manager's at-rest cron rotates it every
+ * {@link FIELD_KEY_ROTATION_DAYS} days.
+ */
+
+/** The binding an app Worker reads its field key through. Fixed across environments; only the store entry is scoped. */
+export const FIELD_KEYS_BINDING = "PITHY_FIELD_KEYS";
+
+/** How often the manager rotates the field key, in days. */
+export const FIELD_KEY_ROTATION_DAYS = 30;
+
+/** A Secrets Store binding: `.get()` resolves the plaintext inside the Worker. */
+export interface FieldKeyBinding {
+  get(): Promise<string>;
+}
+
+/**
+ * Where a field key comes from: the Worker's `env.PITHY_FIELD_KEYS` binding (a Secrets Store binding deployed, a JSON
+ * string from `.dev.vars` locally), or a config a caller already resolved.
+ */
+export type FieldKeys = FieldKeyBinding | string | EncryptionConfig;
+
+/**
+ * Resolve a field key to its config. A missing binding, text that is not JSON, and JSON that is not a key set are each
+ * refused, and **nothing read is ever echoed**: what failed to parse is the key set.
+ */
+export async function resolveFieldKeys(keys: FieldKeys | undefined): Promise<EncryptionConfig> {
+  let raw: unknown = keys;
+  if (keys === undefined || keys === null) {
+    throw new InternalError({
+      message: "This Worker holds an encrypted field and no field key.",
+      action: `Bind ${FIELD_KEYS_BINDING}. ${remedy("secrets provision").say((command) => `${command} binds it to every Worker with an encrypted field.`)}`,
+      detail: `${FIELD_KEYS_BINDING} binding is not configured`,
+    });
+  }
+  if (typeof keys === "object" && "get" in keys && typeof keys.get === "function") raw = await keys.get();
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not valid JSON` });
+    }
+  }
+  const parsed = EncryptionConfig.safeParse(raw);
+  if (!parsed.success) throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not a valid EncryptionConfig` });
+  return parsed.data;
+}
+
+/**
+ * Every live version in a key set, newest first, as numbers. A version key that is not an integer is refused rather
+ * than sorted as text, where `"10"` sorts before `"9"`.
+ */
+export function liveVersions(config: EncryptionConfig): number[] {
+  const versions = Object.keys(config.versions).map(Number);
+  if (!versions.every((version) => Number.isInteger(version))) {
+    throw new InternalError({ detail: `${FIELD_KEYS_BINDING}: a version key is not a stringified integer` });
+  }
+  return versions.sort((left, right) => right - left);
+}