@pithy-sh/secrets 0.1.0

package/src/sharedSecretsStore.ts

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { SecretsStoreEnv } from "./env/bindings";
+import type { SecretRegistry, SecretRegistryEntry } from "./registry";
+import { d1KeyedIO, type SecretsAccessor, secretsStore } from "./secretsStore";
+
+/**
+ * The shared, per-invocation secrets accessor. Within one worker invocation many capabilities each
+ * read secrets; resolving them independently means a Secrets Store round-trip per call site, and a
+ * repeated round-trip when two capabilities share a secret. This module resolves the **combined**
+ * registry — every capability's {@link Capability.secretRegistry} slice merged into one — exactly
+ * once, caches the resulting accessor for a configurable TTL (default 60 s), and hands each call site
+ * a precisely-typed view over only its own slice via {@link SecretsAccessor.subset}.
+ *
+ * Sharing one resolution is what made #170 bite: the combined registry is every capability's, so an
+ * unset secret anywhere in it used to fail the one resolution every capability waits on. The fix is in
+ * {@link secretsStore} — a failure is held against its own name and raised at its own read — and it is
+ * the reason a shared accessor is safe to share. This module resolves once; it does not resolve
+ * all-or-nothing.
+ *
+ * The cache is module-scoped, so it is per worker isolate: built lazily on the first request that
+ * needs secrets, reused by every access within the TTL, and rebuilt on the first access after it
+ * expires. `@pithy-sh/secrets`' capability {@link configureSharedSecrets | configures} the combined
+ * registry and TTL at worker startup (via its `compose` hook); a standalone worker that uses the
+ * accessor without `createBackend` (the email and secrets-manager workers) configures it directly.
+ */
+
+/** Default cache lifetime when the secrets capability does not override it. */
+export const DEFAULT_SECRETS_CACHE_TTL_SECONDS = 60;
+
+/** Resolves the combined registry against `env` — the real path calls {@link secretsStore}; tests inject a fake. */
+type Resolver = (env: SecretsStoreEnv, registry: SecretRegistry) => Promise<SecretsAccessor<SecretRegistry>>;
+
+/** A monotonic millisecond clock — `Date.now` in production, controllable in tests. */
+type Clock = () => number;
+
+/** Options for {@link configureSharedSecrets}. `resolve`/`now` are seams overridden only by tests. */
+export interface ConfigureSharedSecretsOptions {
+  /** The combined registry to resolve — every capability's slice merged. */
+  registry: SecretRegistry;
+  /** Cache lifetime in seconds. Defaults to {@link DEFAULT_SECRETS_CACHE_TTL_SECONDS}. */
+  ttlSeconds?: number;
+  /** Override the resolver (testing). Defaults to a real {@link secretsStore} call. */
+  resolve?: Resolver;
+  /** Override the clock (testing). Defaults to `Date.now`. */
+  now?: Clock;
+}
+
+interface SharedConfig {
+  registry: SecretRegistry;
+  ttlMs: number;
+  resolve: Resolver;
+  now: Clock;
+}
+
+interface CacheEntry {
+  accessor: SecretsAccessor<SecretRegistry>;
+  expiresAt: number;
+}
+
+let config: SharedConfig | null = null;
+let cache: CacheEntry | null = null;
+let inflight: Promise<SecretsAccessor<SecretRegistry>> | null = null;
+
+/**
+ * Configure the shared accessor with the combined registry and TTL. Called once at worker startup
+ * (the secrets capability's `compose` hook, or a standalone worker's module scope). Resets any
+ * cached accessor so the next access re-resolves against the new configuration.
+ */
+export function configureSharedSecrets(options: ConfigureSharedSecretsOptions): void {
+  const ttlSeconds = options.ttlSeconds ?? DEFAULT_SECRETS_CACHE_TTL_SECONDS;
+  config = {
+    registry: options.registry,
+    ttlMs: ttlSeconds * 1000,
+    resolve: options.resolve ?? ((env, registry) => secretsStore(env, registry)),
+    now: options.now ?? Date.now,
+  };
+  cache = null;
+  inflight = null;
+}
+
+/** Clear all shared state — configuration and cache. For test isolation between cases. */
+export function resetSharedSecrets(): void {
+  config = null;
+  cache = null;
+  inflight = null;
+}
+
+function requireConfig(): SharedConfig {
+  if (!config) {
+    throw new InternalError({
+      message: "The shared secrets accessor is not configured.",
+      detail: "configureSharedSecrets was never called — compose the `secrets` capability, or configure it directly.",
+    });
+  }
+  return config;
+}
+
+/** Resolve the combined accessor, honoring the TTL cache and de-duplicating a concurrent first fetch. */
+async function resolveCombined(env: SecretsStoreEnv): Promise<SecretsAccessor<SecretRegistry>> {
+  const cfg = requireConfig();
+  if (cache && cfg.now() < cache.expiresAt) return cache.accessor;
+  // A concurrent access during the fetch shares the one in-flight resolution, so the combined
+  // registry is fetched once even when several capabilities read secrets in the same invocation.
+  if (inflight) return inflight;
+  inflight = cfg
+    .resolve(env, cfg.registry)
+    .then((accessor) => {
+      cache = { accessor, expiresAt: cfg.now() + cfg.ttlMs };
+      return accessor;
+    })
+    .finally(() => {
+      inflight = null;
+    });
+  return inflight;
+}
+
+/**
+ * The shared, per-invocation accessor for `registry` — the calling capability's own slice. Resolves
+ * the combined registry once (cached for the TTL) and returns a precisely-typed view over `registry`.
+ * Every name in `registry` must be part of the configured combined registry; a name that is not is a
+ * wiring bug (the capability did not declare its slice on `secretRegistry`) and throws at the call.
+ */
+export async function sharedSecretsStore<R extends SecretRegistry>(
+  env: SecretsStoreEnv,
+  registry: R,
+): Promise<SecretsAccessor<R>> {
+  const cfg = requireConfig();
+  for (const name of Object.keys(registry)) {
+    if (!(name in cfg.registry)) {
+      throw new InternalError({
+        message: `Secret "${name}" is not in the aggregated registry.`,
+        detail: `'${name}' was requested but no capability declared it on its secretRegistry slice`,
+        action: "Declare the secret on the reading capability's `secretRegistry`.",
+      });
+    }
+  }
+  const combined = await resolveCombined(env);
+  // The combined accessor is cached across requests; a keyspace read or write is not cached at all,
+  // and runs real I/O. Bind it to *this* invocation's env so a member is never fetched — or sealed —
+  // through the binding of whichever earlier request happened to fill the cache.
+  return combined.subset(registry, d1KeyedIO(env));
+}
+
+/**
+ * Merge every capability's {@link Capability.secretRegistry} slice into one combined registry — the
+ * source of truth the shared accessor resolves. A secret name declared by more than one capability is
+ * allowed only when the declarations agree on every axis (`backend`, `scope`, `valueType`,
+ * `rotatable`, `keyed`); a divergent re-declaration is an author conflict and throws. The `secretsStore`
+ * reader keys purely on the name, so identical re-declarations resolve the same stored value.
+ */
+export function aggregateSecretRegistries(capabilities: readonly Capability[]): SecretRegistry {
+  const combined: Record<string, SecretRegistryEntry> = {};
+  const owners: Record<string, string> = {};
+  for (const cap of capabilities) {
+    // The Capability contract carries the slice as the loose `SecretRegistrySeam`; the concrete
+    // entries are always built by `defineSecretRegistry`, so this narrowing is sound at the seam.
+    const slice = cap.secretRegistry as SecretRegistry | undefined;
+    if (!slice) continue;
+    for (const [name, entry] of Object.entries(slice)) {
+      const existing = combined[name];
+      if (existing) {
+        if (
+          existing.backend !== entry.backend ||
+          existing.scope !== entry.scope ||
+          existing.valueType !== entry.valueType ||
+          existing.rotatable !== entry.rotatable ||
+          // A keyspace and a name are not the same secret, whatever else agrees: one resolves
+          // `<name>/<key>`, the other `<name>`.
+          Boolean(existing.keyed) !== Boolean(entry.keyed)
+        ) {
+          throw new InternalError({
+            message: `Secret "${name}" is declared incompatibly by capabilities "${owners[name]}" and "${cap.name}".`,
+            action: "Declare the same backend, scope, valueType, rotatable, and keyed for a shared secret name.",
+          });
+        }
+        continue;
+      }
+      combined[name] = entry;
+      owners[name] = cap.name;
+    }
+  }
+  return combined;
+}

package/src/store/rotationTracker.ts

@@ -0,0 +1,189 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { RotationStatus, RotationTrigger } from "../data/secretRotations";
+import { type SecretsTables, secretsTables } from "../data/tables";
+import {
+  type OpenRotation,
+  type RotationFailureCode,
+  type RotationLedger,
+  rotationClosure,
+  rotationFailureText,
+} from "../rotation/rotationLedger";
+import type { ManagedEnvironment } from "../scope";
+
+type SecretsDb = Kysely<DatabaseSchema<SecretsTables>>;
+
+/**
+ * Append-only tracker for rotation attempts, over the per-environment secrets D1's
+ * `pithy_secrets_rotations` table. Ported from the CMS `RotationTracker`, scoped to one
+ * environment (the per-env manager owns one store).
+ *
+ * `startRotation` opens an `in_progress` row and returns its id; `markSuccess`/`markFailure`
+ * close it. `recordBaseline` seeds a `success`/`baseline` row when a rotatable secret is first
+ * written, so the cadence check never flags a brand-new secret as overdue. `purgeHistory` clears
+ * a deleted secret's rows so they don't linger.
+ */
+export class RotationTracker {
+  readonly #db: SecretsDb;
+
+  constructor(db: SecretsDb) {
+    this.#db = db;
+  }
+
+  /** Build a tracker over a raw `SECRETS` D1 binding. */
+  static fromD1(d1: D1Database): RotationTracker {
+    return new RotationTracker(createDatabase(d1, secretsTables));
+  }
+
+  /** Open an `in_progress` rotation row and return its id. */
+  async startRotation(
+    name: string,
+    trigger: RotationTrigger,
+    rotatedBy: string,
+    metadataSnapshot?: unknown,
+  ): Promise<number> {
+    const inserted = await this.#db
+      .insertInto("pithySecretsRotations")
+      .values({
+        name,
+        startedAt: SQLiteDate.encode(new Date()),
+        completedAt: null,
+        status: "in_progress" satisfies RotationStatus,
+        trigger,
+        rotatedBy,
+        errorMessage: null,
+        metadataSnapshot: metadataSnapshot === undefined ? null : JSON.stringify(metadataSnapshot),
+      })
+      .returning("id")
+      .executeTakeFirstOrThrow();
+    return inserted.id;
+  }
+
+  /** Close a rotation row as `success`. */
+  async markSuccess(rotationId: number): Promise<void> {
+    await this.#db
+      .updateTable("pithySecretsRotations")
+      .set({ status: "success" satisfies RotationStatus, completedAt: SQLiteDate.encode(new Date()) })
+      .where("id", "=", rotationId)
+      .execute();
+  }
+
+  /**
+   * Close a rotation row as `failed`, under a code that names the failure.
+   *
+   * **It takes a code and not a sentence, and that is the whole of `#386`.** `error_message` is the one
+   * column on this table a failure site writes, `rotationLedger.ts` states that its text is fixed and
+   * chosen by a code, and the at-rest rotation path composed it from `cause.message` anyway — from a catch
+   * reached by decryption, envelope decoding and config parsing, which are the paths whose exception text
+   * can carry key material. Four files already refuse to publish this column; that refusal is defense in
+   * depth and was never the invariant. The invariant is that there is nothing here to publish.
+   *
+   * A comment asking for a code would have been the same comment that was already there. So the signature
+   * asks: {@link RotationFailureCode} is a closed union, `rotationFailureText` maps it here rather than at
+   * the call site, and a caller holding an exception has nowhere to put it. The exception is still raised,
+   * and its context still travels in a `PithyError`'s `detail`, which the HTTP codec strips.
+   */
+  async markFailure(rotationId: number, code: RotationFailureCode): Promise<void> {
+    await this.#db
+      .updateTable("pithySecretsRotations")
+      .set({
+        status: "failed" satisfies RotationStatus,
+        completedAt: SQLiteDate.encode(new Date()),
+        errorMessage: rotationFailureText(code),
+      })
+      .where("id", "=", rotationId)
+      .execute();
+  }
+
+  /**
+   * Seed a `success`/`baseline` row so a brand-new rotatable secret is not flagged overdue.
+   *
+   * **A first write, and it stays that.** `trigger: "baseline"` is what distinguishes establishing a value
+   * from replacing one — a rotation writes `manual` or `cron` through {@link trackerRotationLedger} and
+   * carries an actor. Widening this to cover updates would let a typo fix advance a freshness clock
+   * nobody rotated; see `../rotation/rotationLedger.ts`.
+   */
+  async recordBaseline(name: string): Promise<void> {
+    const now = SQLiteDate.encode(new Date());
+    await this.#db
+      .insertInto("pithySecretsRotations")
+      .values({
+        name,
+        startedAt: now,
+        completedAt: now,
+        status: "success" satisfies RotationStatus,
+        trigger: "baseline" satisfies RotationTrigger,
+        rotatedBy: "baseline",
+        errorMessage: null,
+        metadataSnapshot: null,
+      })
+      .execute();
+  }
+
+  /** The most recent successful completion for a name, or `null` if it has never succeeded. */
+  async getLatestSuccess(name: string): Promise<Date | null> {
+    const row = await this.#db
+      .selectFrom("pithySecretsRotations")
+      .select("completedAt")
+      .where("name", "=", name)
+      .where("status", "=", "success")
+      .where("completedAt", "is not", null)
+      .orderBy("completedAt", "desc")
+      .limit(1)
+      .executeTakeFirst();
+    if (!row || row.completedAt == null) return null;
+    return new Date(row.completedAt as number);
+  }
+
+  /** Remove all rotation rows for a secret (called on delete). Returns the count removed. */
+  async purgeHistory(name: string): Promise<number> {
+    const before = await this.#db
+      .selectFrom("pithySecretsRotations")
+      .select((eb) => eb.fn.countAll<number>().as("count"))
+      .where("name", "=", name)
+      .executeTakeFirst();
+    await this.#db.deleteFrom("pithySecretsRotations").where("name", "=", name).execute();
+    return Number(before?.count ?? 0);
+  }
+}
+
+/** What {@link trackerRotationLedger} needs beyond the tracker: which environment it is, and who is asking. */
+export interface TrackerRotationLedgerOptions {
+  /** The environment this D1 belongs to. Decides how the row closes — see `rotationClosure`. */
+  environment: ManagedEnvironment;
+  /** What caused the rotation: an operator (`manual`) or the manager's own schedule (`cron`). Never `baseline`. */
+  trigger: Exclude<RotationTrigger, "baseline">;
+  /** Who asked. A verified control-plane subject in a Worker, a workflow instance id for a scheduled run. */
+  rotatedBy: string;
+}
+
+/**
+ * The in-Worker {@link RotationLedger}: the rotation table this process already holds a handle to.
+ *
+ * The direct half of the seam. Anything running *inside* an environment — a control-plane rotate route, the
+ * manager's own cron — records through this; a process outside one records the identical rows through
+ * `../cli/rotationLedger.ts`, over a dispatch. Both compose the closing verdict with `rotationClosure` and
+ * the failure sentence with `rotationFailureText`, which is what stops the two paths from disagreeing about
+ * whether a rotation happened (`#379`).
+ */
+export function trackerRotationLedger(tracker: RotationTracker, options: TrackerRotationLedgerOptions): RotationLedger {
+  return {
+    async open(name: string): Promise<OpenRotation> {
+      const rotationId = await tracker.startRotation(name, options.trigger, options.rotatedBy);
+      return {
+        async close(outcome): Promise<void> {
+          const closure = rotationClosure(outcome, options.environment);
+          if (closure.status === "success") await tracker.markSuccess(rotationId);
+          // The reason, not its sentence. Every reason is a `RotationFailureCode`, and the tracker renders
+          // it — one place composes the text, on both sides of the seam (`#386`).
+          else await tracker.markFailure(rotationId, closure.reason);
+        },
+      };
+    },
+  };
+}

package/src/store/systemSecretsStore.ts

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import { decryptValue, type EncryptionConfig, encryptValue } from "../crypto/envelope";
+import { decodeVersionedValue, encodeVersionedValue, type VersionedValue } from "../crypto/versionedValue";
+import { type SecretsTables, secretsTables } from "../data/tables";
+import { resolveEncryptionConfig, type SecretsStoreEnv } from "../env/bindings";
+import { SecretCryptoError } from "../error/errors";
+import type { SecretValueType } from "../registry";
+
+/** The Kysely instance the store queries — typed over the secrets tables, CamelCasePlugin installed. */
+type SecretsDb = Kysely<DatabaseSchema<SecretsTables>>;
+
+/**
+ * One stored secret as a read found it: its envelope, or that the row is there and would not open (#384).
+ *
+ * **The state rides on the value**, so a caller cannot reach a plaintext without narrowing and forgetting
+ * the unreadable case is a compile error rather than a silent empty. That is the shape `#350`, `#371` and
+ * `#380` settled, and it is here for the reason it was there: this is a *batch* read, so an unreadable row
+ * that throws is an unreadable row that costs every other name in the call. `#170` promised that a failure
+ * belongs to its secret; it was true of a **missing** row and not of an **unreadable** one, which is a
+ * narrower guarantee than the sentence reads.
+ *
+ * **Absent is a third fact and it is not in this union.** A name with no row is simply not a key in the
+ * record `getValues` returns. Missing and unreadable are different faults with different remedies —
+ * provision it, versus investigate the row or re-seal it — and folding either into the other loses the
+ * only thing the operator needed.
+ *
+ * `unreadable` carries nothing. There is nothing safe to put on it: what the decrypt threw names a key
+ * version and a ciphertext it could not open, and the row's own name is already the key this value is
+ * filed under.
+ */
+export type StoredSecretValue =
+  | {
+      /** The row opened and its plaintext parsed as a value envelope. */
+      state: "readable";
+      /** The decrypted `{ currentVersion, versions }` envelope. */
+      value: VersionedValue;
+    }
+  | {
+      /** The row is stored and did not open — a corrupt ciphertext, or a key version no longer held. */
+      state: "unreadable";
+    };
+
+/**
+ * What a stored secret that will not open is told — the sibling of `secretsStore`'s `unprovisioned`, and
+ * deliberately a different sentence with a different code.
+ *
+ * Constructed here rather than re-thrown from the decrypt, because nothing derived from that failure may
+ * travel: the guard's `catch` takes no binding (`#350`), so there is no error object in scope to attach as
+ * `cause` and no text to fold into `detail`. What survives is the name — never a ciphertext, an IV, or a
+ * key version.
+ *
+ * **Only for a name a registry declares.** `message` crosses the HTTP boundary, so the name in it must be
+ * one an operator wrote in a registry and not one a caller supplied. A keyspace member's stored name embeds
+ * a tenant key; {@link SystemSecretsStore.getValue} keeps that out of `message` for exactly that reason.
+ */
+export function unreadableSecret(name: string): SecretCryptoError {
+  return new SecretCryptoError({
+    message: `Secret '${name}' is stored and could not be read.`,
+    action:
+      "Check SECRETS_ENCRYPTION_KEYS still holds the key version this row was sealed under. If it does not, re-seal the secret with `pithy secrets update`.",
+    detail: `d1 secret '${name}' has a row that did not decrypt`,
+  });
+}
+
+/**
+ * Decrypt and parse one row, or answer that it would not open (#384).
+ *
+ * **The `catch` takes no binding, and that is the point rather than a tidiness.** A decryption failure's
+ * own text names the key version it tried and the context it tried under; `decodeVersionedValue`'s names
+ * the shape it found in a plaintext. Neither may reach a log, a response, or a held error, and a `catch`
+ * with nothing bound makes that impossible to get wrong later rather than merely absent today.
+ *
+ * Both halves are inside it. A ciphertext that opens to something that is not an envelope is as unreadable
+ * as one that does not open at all, and it arrives by the same routes.
+ */
+async function readRow(
+  config: EncryptionConfig,
+  row: { name: string; encryptedValue: string; iv: string; keyVersion: number },
+): Promise<StoredSecretValue> {
+  try {
+    // The row's own name is the bound context: a ciphertext moved to another row does not open.
+    return { state: "readable", value: decodeVersionedValue(await decryptValue(config, row.name, row)) };
+  } catch {
+    return { state: "unreadable" };
+  }
+}
+
+/**
+ * The D1-backed encrypted store for `d1`-backed secrets, ported from the CMS `SystemSecretsStore`
+ * with Pithy's universal value envelope layered on. Every secret's plaintext is a
+ * `{ currentVersion, versions }` envelope (`crypto/versionedValue`), sealed in one AES-256-GCM
+ * envelope (`crypto/envelope`) and persisted as one `pithy_secrets_system_secrets` row. The master
+ * key is held only in memory, resolved once from the worker-only `SECRETS_ENCRYPTION_KEYS` binding.
+ *
+ * The store is the low-level read/write primitive: it persists and returns value envelopes. The
+ * create/update/rotate *semantics* (which envelope to write) live above it — in the manager
+ * Workflow and the CLI. Construct per request so a `SECRETS_ENCRYPTION_KEYS` rotation is picked up.
+ */
+export class SystemSecretsStore {
+  readonly #db: SecretsDb;
+  readonly #config: EncryptionConfig;
+
+  constructor(db: SecretsDb, config: EncryptionConfig) {
+    this.#db = db;
+    this.#config = config;
+  }
+
+  /** Build a store from the worker env: its `SECRETS` D1 and resolved master-key config. */
+  static async fromEnv(env: SecretsStoreEnv): Promise<SystemSecretsStore> {
+    const config = await resolveEncryptionConfig(env);
+    return new SystemSecretsStore(createDatabase(env.SECRETS, secretsTables), config);
+  }
+
+  /**
+   * Read every requested name that exists, each row's outcome on its own value (absent names omitted).
+   *
+   * The name list is the *application's* size, not a query's: `secretsStore` hands this every D1-backed
+   * secret the registry declares, in one call, at boot. So it is chunked against D1's cap rather than
+   * assumed to fit. Unchunked, an app declaring 101 of them read none of them, and because every
+   * capability's secrets resolve through this one call, that is the whole Worker failing to start over a
+   * limit nothing in a registry mentions (#250).
+   *
+   * **And for the same reason a row that will not open costs only itself (#384).** The decrypt used to run
+   * in a bare loop, so one corrupt ciphertext — or one `keyVersion` orphaned by a master-key rotation —
+   * threw out of the batch, and the caller above held that against *every* `d1` name in the read. An
+   * unreadable `auth-github-credentials` therefore took `auth-session-secret` down with it, which is how
+   * one unreadable OAuth credential ended every form of sign-in (#381). Each row is guarded now and lands
+   * as a {@link StoredSecretValue} against its own name, which is what #170 promised.
+   */
+  async getValues(names: string[]): Promise<Record<string, StoredSecretValue>> {
+    if (names.length === 0) return {};
+    const out: Record<string, StoredSecretValue> = {};
+    for (const chunk of chunkByBoundParameters(names, 0)) {
+      const rows = await this.#db
+        .selectFrom("pithySecretsSystemSecrets")
+        .select(["name", "encryptedValue", "iv", "keyVersion"])
+        .where("name", "in", chunk)
+        .execute();
+
+      for (const row of rows) out[row.name] = await readRow(this.#config, row);
+    }
+    return out;
+  }
+
+  /**
+   * The value envelope for one secret, or `undefined` if it is not stored. A stored row that will not open
+   * throws `secrets/crypto_failed`.
+   *
+   * **The union collapses here, and only here, because a batch of one has nothing to protect.** The state
+   * rides on the value in {@link getValues} so that one bad row cannot cost its neighbors; asking for a
+   * single name there are no neighbors, and every caller of this one — a keyspace member read, a rotate's
+   * baseline, the dev seeder — wants the value or an exception. What it must *not* do is answer
+   * `undefined`, which means "nothing is stored" and sends the reader to provision a row that is already
+   * there.
+   *
+   * **The name goes in `detail` and never in `message`, which is why this is not {@link unreadableSecret}.**
+   * That one is handed a registry literal. This one is handed a *stored* name, and for a keyspace member
+   * that is the whole `<keyspace>/<key>` — a tenant identifier, supplied by a caller. `message` crosses the
+   * HTTP boundary and `detail` is stripped there, so a sentence naming the secret would answer "which of
+   * your tenants has a broken credential" to whoever could provoke it.
+   */
+  async getValue(name: string): Promise<VersionedValue | undefined> {
+    const stored = (await this.getValues([name]))[name];
+    if (!stored) return undefined;
+    if (stored.state === "unreadable") {
+      throw new SecretCryptoError({ detail: `stored secret '${name}' has a row that did not decrypt` });
+    }
+    return stored.value;
+  }
+
+  /** Whether a secret with this name is stored. */
+  async has(name: string): Promise<boolean> {
+    const row = await this.#db
+      .selectFrom("pithySecretsSystemSecrets")
+      .select("name")
+      .where("name", "=", name)
+      .executeTakeFirst();
+    return row !== undefined;
+  }
+
+  /**
+   * Encrypt `value` under the current key version and upsert the row. Inserts on first write,
+   * updates the envelope in place otherwise. `name` is sealed into the ciphertext as authenticated
+   * data (`crypto/envelope`), so a rename has to go through here and not through SQL: an
+   * `UPDATE ... SET name` leaves a row nothing can open. The caller owns the envelope's shape —
+   * `initialVersionedValue` for a create, an edited envelope for an update, `appendVersion` for a
+   * value rotation.
+   */
+  async put(name: string, value: VersionedValue, valueType: SecretValueType = "text"): Promise<void> {
+    const { encryptedValue, iv, keyVersion } = await encryptValue(this.#config, name, encodeVersionedValue(value));
+    const now = SQLiteDate.encode(new Date());
+
+    if (await this.has(name)) {
+      await this.#db
+        .updateTable("pithySecretsSystemSecrets")
+        .set({ encryptedValue, iv, keyVersion, valueType, updatedAt: now })
+        .where("name", "=", name)
+        .execute();
+      return;
+    }
+    await this.#db
+      .insertInto("pithySecretsSystemSecrets")
+      .values({ name, encryptedValue, iv, keyVersion, valueType, createdAt: now, updatedAt: now })
+      .execute();
+  }
+
+  /** Remove a secret. A no-op if it does not exist. */
+  async delete(name: string): Promise<void> {
+    await this.#db.deleteFrom("pithySecretsSystemSecrets").where("name", "=", name).execute();
+  }
+
+  /** Every stored secret name, sorted — the metadata `ls` reads without touching values. */
+  async listNames(): Promise<string[]> {
+    const rows = await this.#db.selectFrom("pithySecretsSystemSecrets").select("name").orderBy("name").execute();
+    return rows.map((row) => row.name);
+  }
+}

package/src/test-utils/devEncryptionKeys.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { EncryptionConfig } from "../crypto/envelope";
+
+/**
+ * A fresh AES-256 master-key config for a test run, as the string a `SECRETS_ENCRYPTION_KEYS` binding
+ * carries — the same shape `.dev.vars` supplies in local dev. Put it on a package's Miniflare
+ * `bindings` and the worker resolves its encryption config from it, so encrypt, decrypt, and at-rest
+ * rotation are all exercisable locally with no live Cloudflare Secrets Store.
+ *
+ * **Its own module, with one type-only import and nothing else, and that is load-bearing.** A
+ * `vitest.workers.config.ts` is loaded by vite through Node's own ESM resolver, which cannot follow
+ * the extensionless specifiers this repository's TypeScript sources use — so a config importing
+ * anything with a runtime dependency fails before a single test runs. The type import is erased.
+ * Keep this file free of runtime imports, or every workers config that reads it stops loading.
+ *
+ * Generated per call, and never reused as anything but a test key.
+ */
+export function devEncryptionKeys(): string {
+  const key = crypto.getRandomValues(new Uint8Array(32));
+  let binary = "";
+  for (const byte of key) binary += String.fromCharCode(byte);
+  const config: EncryptionConfig = {
+    currentVersion: "1",
+    versions: { "1": btoa(binary) },
+    lastRotatedAt: "2026-01-01T00:00:00.000Z",
+  };
+  return JSON.stringify(config);
+}