@pithy-sh/secrets 0.1.0

package/src/cli/writeTargets.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import type { SecretBackend, SecretScope } from "../registry";
+import { canonicalGlobalEnvironment, type ManagedEnvironment, resolveWriteTargets } from "../scope";
+
+/**
+ * **Where a write is allowed to land, decided once, before anything is dispatched.**
+ *
+ * A `global` secret is *defined* by holding one value in every environment — `email-link-signing-key`
+ * exists so a link signed in staging verifies in prod. A split is therefore not a state the product has
+ * a meaning for, and it can arrive two ways:
+ *
+ * 1. **An operator asks for one.** `pithy secrets update <global> --env staging` narrows a scope that
+ *    cannot be narrowed. This is a category error, not a fault, and it is what this module refuses.
+ * 2. **A fan-out fails part-way.** Three environments, the third throws. That one is a fault, it is not
+ *    preventable here, and the honest treatment is below.
+ *
+ * ## Why refusal is all this can offer, and why that is enough
+ *
+ * The write path is `CLI → dispatch → one Workflow per environment, in one Worker per environment`.
+ * There is no transaction across them and no rollback: a compensating write is itself a Workflow that
+ * can fail, which is the same problem one level down. **So "complete-or-revert" is not available and is
+ * not implied.** What is available is deciding before anything is written, which is exactly what closes
+ * case 1 — and case 1 is the one an ordinary command produces.
+ *
+ * This is why the refusal is here and not in the manager. A Workflow that throws does not produce a CLI
+ * error: it fails an instance, the runtime retries it, and the CLI polls and has to read an operator's
+ * typo as a distributed failure. Retrying a refusal is nonsense. Refusing before dispatch also satisfies
+ * *a refusal that has already written is not a refusal* for free — nothing was sent, so nothing landed.
+ *
+ * ## The residual window, stated rather than papered over
+ *
+ * Case 2 remains reachable. A `global` + `d1` secret fans out across every declared environment, and a
+ * fault inside that fan-out leaves some environments on the new value and the rest on the old. Nothing
+ * here narrows that. What the dispatch path does instead is **say what it wrote** — see
+ * `environmentsWrittenBeforeFailure` in `./dispatch.ts` — so the split is visible to the operator who
+ * has to repair it. A guarantee that cannot be given is not given.
+ *
+ * `global` + `cf-secrets-store` needs none of this, and the reason is structural rather than an
+ * oversight: it is one account-level entry that every environment binds, so it is a single write with
+ * nothing to be inconsistent with (`resolveWriteTargets`). It still refuses `--env`, because narrowing a
+ * scope that has no parts is the same category error arriving at a backend where it happens to be
+ * harmless.
+ *
+ * ## One owner, so a third caller inherits it
+ *
+ * `resolveWriteTargets` in `../scope.ts` is the backend × scope **table**. It holds no policy and it
+ * refuses nothing. This is the **rule**, and it is what `dispatchSecretWrite` and `mintDeclaredSecrets`
+ * both call to obtain their targets. `capabilities/writeTargetsOwner.test.ts` in `@pithy-sh/cli` fails
+ * the build on any shipped module that reaches the table directly, so a write path added later cannot
+ * quietly skip the rule by naming the thing underneath it.
+ */
+export interface SecretWriteIntent {
+  /** The secret's registry name. It appears in the refusal, so the operator knows which one is global. */
+  name: string;
+  /** Where the secret is held. Decides the fan-out shape for a `global` write; never decides the rule. */
+  backend: SecretBackend;
+  /** The secret's declared scope. This is what the rule is about. */
+  scope: SecretScope;
+  /** What the command is doing. It changes the wording of the remedy and nothing else — see the tests. */
+  mode: "create" | "update" | "delete";
+  /**
+   * The environment the operator named, or `undefined` when they named none.
+   *
+   * **The absence has to survive to here**, which is why this is optional rather than defaulted upstream.
+   * The command used to resolve a missing `--env` on a global secret to the canonical environment before
+   * dispatch, which erased the difference between *the operator narrowed the write* and *the operator
+   * said nothing* — and it is exactly that difference the rule turns on.
+   */
+  requested: ManagedEnvironment | undefined;
+  /** Every environment the project declares, from the root `pithy.config.ts`. The fan-out set. */
+  declared: DeclaredEnvironments | readonly string[];
+}
+
+/** The remedy's verb, by mode. A `rm` that is told to "set it everywhere" is a remedy for another command. */
+const REMEDY: Record<SecretWriteIntent["mode"], string> = {
+  create: "set it in every environment",
+  update: "set it in every environment",
+  delete: "remove it from every environment",
+};
+
+/**
+ * The environments this write reaches — or a refusal, thrown, if the request and the scope disagree.
+ *
+ * Two refusals, and they are the same rule read from both ends: a `global` secret cannot be narrowed to
+ * one environment, and an `environment` secret cannot be widened to all of them. Neither has a bypass
+ * flag. The remedy for both is a single re-run, and a re-run is the confirmation of intent that a `--yes`
+ * would otherwise have to stand in for.
+ */
+export function secretWriteTargets(intent: SecretWriteIntent): ManagedEnvironment[] {
+  if (intent.scope === "environment") {
+    if (intent.requested === undefined) {
+      throw new ValidationError({
+        message: `Secret '${intent.name}' is environment-scoped — choose an environment.`,
+        action: `Pass one of ${intent.declared.map((env) => `--env ${env}`).join(" or ")}.`,
+        detail: `environment-scoped secret '${intent.name}' dispatched with no requested environment`,
+      });
+    }
+    return resolveWriteTargets(intent.backend, intent.scope, intent.requested, intent.declared);
+  }
+
+  if (intent.requested !== undefined) {
+    throw new ValidationError({
+      message: `Secret '${intent.name}' is global. It holds one value across every environment, so --env cannot narrow it.`,
+      action: `Run it again without --env to ${REMEDY[intent.mode]}.`,
+      detail: `global secret '${intent.name}': ${intent.mode} narrowed to ${intent.requested}, which the scope does not permit`,
+    });
+  }
+
+  // The canonical environment is the table's input for a `global` write, not the operator's — it picks
+  // which manager performs the single `cf-secrets-store` write, and is unread for `d1`. Resolved here so
+  // the table keeps its signature and the command stops inventing an environment it was never given.
+  const canonical = canonicalGlobalEnvironment(intent.declared);
+  if (canonical === undefined) {
+    throw new ValidationError({
+      message: `This project declares no environments, so '${intent.name}' has nowhere to go.`,
+      action: "Declare at least one environment in the root pithy.config.ts, then run this again.",
+      detail: `global secret '${intent.name}': empty declaration`,
+    });
+  }
+  return resolveWriteTargets(intent.backend, intent.scope, canonical, intent.declared);
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`,
+// matching the Miniflare config in `vitest.workers.config.ts`: the dedicated D1
+// `SECRETS` database. `cloudflare:test` types its `env` as `Cloudflare.Env`, so
+// the test bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    SECRETS: D1Database;
+    /** The master-key config as a string (the `.dev.vars` shape), set in `vitest.workers.config.ts`. */
+    SECRETS_ENCRYPTION_KEYS: string;
+  }
+}

package/src/crypto/envelope.ts

@@ -0,0 +1,188 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { SecretCryptoError } from "../error/errors";
+
+/**
+ * AES-256-GCM envelope helpers, ported from the CMS `secretsCrypto`. The master key never
+ * leaves the worker: it is read from the `SECRETS_ENCRYPTION_KEYS` binding (CF Secrets Store)
+ * as an {@link EncryptionConfig}, and every encrypt/decrypt runs in-process. Helpers take a
+ * parsed config so a caller resolves it once and passes the typed value through.
+ *
+ * Two version axes live here: `currentVersion` (which master key encrypts new writes) and the
+ * `keyVersion` persisted per row (which key decrypts it). Both let the at-rest rotation job
+ * re-encrypt under a new key with an overlap window. This is the *encryption-key* version — the
+ * *value* version is a separate concern (see `versionedValue.ts`).
+ *
+ * The config carries the same uniform `{ currentVersion, versions }` envelope every secret uses
+ * (`versionedValue.ts`) — `versions` is the still-valid key set, `currentVersion` the active
+ * pointer — plus `lastRotatedAt` beside it as rotation metadata. Stringified-integer version keys,
+ * so the keys read is inherently a full-set read (every still-valid version, never current-only).
+ *
+ * ## The secret's name is authenticated, not decorative
+ *
+ * Every seal binds the secret's **stored name** 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 the envelope has no opinion about whether it
+ * belongs there — every decision about which secret a caller gets then lives in the query above, and
+ * a bug there is a disclosure rather than a failure. With the name bound, a moved ciphertext does
+ * not open, inside the primitive, however that query is later rewritten.
+ *
+ * The stored name is the right thing to bind because it *is* the row's identity: `name` is unique in
+ * `pithy_secrets_system_secrets`, and for a keyspace member it is the whole `<entry>/<key>`
+ * (`keyspace.ts`) — so one tenant's credential does not open under another tenant's key.
+ *
+ * **What is bound must be stable for the life of the ciphertext, and this is.** Nothing renames a
+ * secret: the store offers `put` and `delete`, and a rename is a create under the new name plus a
+ * delete of the old, which re-encrypts through the plaintext. An `UPDATE ... SET name` in raw SQL
+ * would leave a row that never opens again — which is the property, not a regression. Choosing
+ * anything mutable (a display label, an owning tenant that could be reassigned) would make a rename
+ * an unopenable secret; the name cannot be renamed, so it cannot.
+ *
+ * The AAD is prefixed with {@link AAD_CONTEXT} for domain separation: a ciphertext from some future
+ * construction under the same master key will not open here, and vice versa. That prefix is
+ * versioned so a later change to what is bound is a deliberate, visible break.
+ *
+ * **No compatibility path.** Ciphertexts written before the binding existed carry no AAD and do not
+ * open — they fail as `secrets/crypto_failed`, like any other unreadable row. Nothing is published
+ * and no adopter stores production values yet, so accepting an unbound ciphertext "just this once"
+ * would buy nothing and leave the exact hole this closes permanently reachable.
+ */
+export const EncryptionConfig = z
+  .object({
+    currentVersion: z
+      .string()
+      .describe(
+        "The version key (a stringified integer) whose master key encrypts new writes — the active master key.",
+      ),
+    versions: z
+      .record(z.string(), z.string())
+      .describe(
+        "Every still-valid master key: version key (stringified integer) → base64-encoded AES-256 key. Holds the current key plus any prior versions still needed to decrypt rows not yet re-encrypted.",
+      ),
+    lastRotatedAt: z.iso
+      .datetime()
+      .describe(
+        "ISO-8601 timestamp of the last at-rest key rotation; the cron compares against it to decide when to rotate.",
+      ),
+  })
+  .describe(
+    "The master-key configuration, read from the worker-only SECRETS_ENCRYPTION_KEYS binding (CF Secrets Store). The uniform versioned-value shape (currentVersion + versions) plus rotation metadata.",
+  );
+export type EncryptionConfig = z.output<typeof EncryptionConfig>;
+
+/**
+ * One AES-256-GCM envelope: base64 ciphertext, base64 IV, and the key version that produced it. The
+ * bound name is deliberately not in here — it is the row's own `name` column, supplied by the caller
+ * on the way back in, so a row that has been moved cannot carry its old context with it.
+ */
+export interface EncryptedEnvelope {
+  encryptedValue: string;
+  iv: string;
+  keyVersion: number;
+}
+
+/** Base64-encode raw bytes without spreading into `fromCharCode` (stack-safe, lint-clean). */
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Decode base64 to raw bytes. */
+function fromBase64(b64: string): Uint8Array {
+  return Uint8Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/**
+ * The domain-separation prefix on every seal's authenticated data. Versioned: changing what is bound
+ * changes this too, so the break is deliberate and every old ciphertext fails loudly rather than
+ * opening under a rule it was not sealed with.
+ */
+const AAD_CONTEXT = "pithy.secrets.v1:";
+
+/**
+ * The authenticated data for one secret: the domain prefix and the stored name.
+ *
+ * An empty name is refused on both halves. It would bind the prefix alone — every secret sharing one
+ * context is the same as binding nothing, and it would fail open rather than loudly.
+ */
+function additionalData(name: string): Uint8Array {
+  if (name.length === 0) {
+    throw new SecretCryptoError({ detail: "the envelope needs a secret name to bind; an empty name binds nothing" });
+  }
+  return new TextEncoder().encode(`${AAD_CONTEXT}${name}`);
+}
+
+/** 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")[],
+): Promise<CryptoKey> {
+  const b64 = config.versions[String(version)];
+  if (!b64) {
+    throw new SecretCryptoError({
+      detail: `encryption key version ${version} not present in SECRETS_ENCRYPTION_KEYS`,
+    });
+  }
+  return crypto.subtle.importKey("raw", fromBase64(b64), "AES-GCM", false, usage);
+}
+
+/**
+ * Encrypt `plaintext` for the secret stored as `name`, under the config's current key version. The
+ * IV is 12 fresh random bytes; `name` is bound as authenticated data, so the result opens only for
+ * that name.
+ */
+export async function encryptValue(
+  config: EncryptionConfig,
+  name: string,
+  plaintext: string,
+): Promise<EncryptedEnvelope> {
+  const aad = additionalData(name);
+  const keyVersion = Number(config.currentVersion);
+  const key = await importKey(config, keyVersion, ["encrypt"]);
+  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 };
+}
+
+/**
+ * Decrypt an envelope sealed for the secret stored as `name`. 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 for a
+ * different name all throw `secrets/crypto_failed` — never the raw 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 decrypt was *attempted under*, which is what an operator needs to see. `name`
+ * reaches logs verbatim there, which is safe because every name is either a registry literal or a
+ * `keyedSecretName` composed from a validated `SecretKey` — no newlines, no control bytes.
+ */
+export async function decryptValue(
+  config: EncryptionConfig,
+  name: string,
+  envelope: EncryptedEnvelope,
+): Promise<string> {
+  const aad = additionalData(name);
+  const key = await importKey(config, envelope.keyVersion, ["decrypt"]);
+  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 SecretCryptoError(
+      {
+        detail: `AES-GCM decrypt failed for secret '${name}' under key version ${envelope.keyVersion}: wrong key, tampered ciphertext, or a ciphertext sealed for a different name`,
+      },
+      { cause },
+    );
+  }
+}

package/src/crypto/versionedValue.ts

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { SecretCryptoError } from "../error/errors";
+
+/**
+ * The universal value serde. Every secret — rotatable or not — is stored the same way: a
+ * `{ currentVersion, versions }` envelope, JSON-encoded, then sealed in one AES-256-GCM
+ * envelope. The shape mirrors `EncryptionConfig`'s `{ currentVersion, keys }`: an explicit
+ * pointer to the current version (so we never sort stringified-integer keys, where `"10" < "2"`)
+ * plus every still-valid version. A new secret is a one-entry envelope; a value rotation (a
+ * deferred feature) appends the next version and repoints `currentVersion`. Values are strings —
+ * a `json` secret stores its serialized form, parsed at the read seam. This is the *value*
+ * version, distinct from the envelope's encryption-key version (see `envelope.ts`).
+ *
+ * Future: when a version is rotated out, it can carry a pruning TTL so a retired version is
+ * removed from the store after its grace window. That is modeled as a parallel `retiredAt` map
+ * (version → ISO timestamp), keeping `versions` itself string→string. Deferred with value rotation.
+ */
+export const VersionedValue = z
+  .object({
+    currentVersion: z
+      .string()
+      .describe("The version key (a stringified integer) whose value is current — the default returned by `get`."),
+    versions: z
+      .record(z.string(), z.string())
+      .describe("Every still-valid version: version key (stringified integer) → value. Always at least one entry."),
+  })
+  .describe("A secret's stored plaintext: an explicit current-version pointer plus every still-valid version.");
+export type VersionedValue = z.output<typeof VersionedValue>;
+
+/** The initial envelope for a freshly-created secret: version 1 is current and holds the value. */
+export function initialVersionedValue(value: string): VersionedValue {
+  return { currentVersion: "1", versions: { "1": value } };
+}
+
+/** Append `value` at the next version and make it current, keeping prior versions (a value rotation). */
+export function appendVersion(value: VersionedValue, next: string): VersionedValue {
+  const version = String(highestVersion(value) + 1);
+  return { currentVersion: version, versions: { ...value.versions, [version]: next } };
+}
+
+/** The highest existing version number — used only to pick the next on append (never to find "current"). */
+function highestVersion(value: VersionedValue): number {
+  const versions = Object.keys(value.versions)
+    .map(Number)
+    .filter((n) => Number.isInteger(n));
+  if (versions.length === 0) {
+    throw new SecretCryptoError({ detail: "decoded secret has no versions" });
+  }
+  return Math.max(...versions);
+}
+
+/** The current value — a direct lookup via the explicit `currentVersion` pointer, no sorting. */
+export function currentValue(value: VersionedValue): string {
+  const current = value.versions[value.currentVersion];
+  if (current === undefined) {
+    throw new SecretCryptoError({ detail: `currentVersion '${value.currentVersion}' is absent from versions` });
+  }
+  return current;
+}
+
+/** Serialize an envelope to the plaintext that goes into the AES-256-GCM envelope. */
+export function encodeVersionedValue(value: VersionedValue): string {
+  return JSON.stringify(VersionedValue.parse(value));
+}
+
+/** Parse decrypted plaintext into a validated envelope. Throws `secrets/crypto_failed` on a bad shape. */
+export function decodeVersionedValue(plaintext: string): VersionedValue {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(plaintext);
+  } catch (cause) {
+    throw new SecretCryptoError({ detail: "decrypted secret plaintext is not valid JSON" }, { cause });
+  }
+  const result = VersionedValue.safeParse(parsed);
+  if (!result.success) {
+    throw new SecretCryptoError({ detail: "decrypted secret plaintext is not a versioned value" });
+  }
+  return result.data;
+}

package/src/data/secretRotations.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+export const RotationStatus = z
+  .enum(["in_progress", "success", "failed"])
+  .describe("Lifecycle state of a rotation attempt: `in_progress` while running, then `success` or `failed`.");
+export type RotationStatus = z.output<typeof RotationStatus>;
+
+export const RotationTrigger = z
+  .enum(["cron", "manual", "baseline"])
+  .describe(
+    "What caused the rotation: a scheduled `cron` run, a `manual` operator action, or a `baseline` marker recorded when a secret is first established.",
+  );
+export type RotationTrigger = z.output<typeof RotationTrigger>;
+
+/**
+ * The `pithy_secrets_rotations` table — an append-only audit row per rotation attempt, in
+ * the per-environment secrets D1. Records both at-rest encryption-key rotations and (later)
+ * value rotations. Ported from the CMS `secret_rotations` model.
+ */
+export const SecretRotation = z
+  .object({
+    id: z.number().int().describe("Auto-incrementing primary key for this rotation event."),
+    name: z
+      .string()
+      .describe(
+        "Secret being rotated (matches a registry entry / `pithy_secrets_system_secrets.name`), or a sentinel for whole-store key rotation.",
+      ),
+    startedAt: SQLiteDate.describe("When the rotation attempt began. Ms-epoch in SQLite, a `Date` in app code."),
+    completedAt: SQLiteDate.nullable().describe("When the rotation finished; null while in progress."),
+    status: RotationStatus.describe("Lifecycle state of the rotation event."),
+    trigger: RotationTrigger.describe("What caused this rotation."),
+    rotatedBy: z
+      .string()
+      .describe("Identifier of the agent that initiated the rotation (workflow instance id, operator id, etc.)."),
+    errorMessage: z
+      .string()
+      .nullable()
+      .describe("Human-readable failure reason; populated when status is `failed`, otherwise null."),
+    metadataSnapshot: z
+      .string()
+      .nullable()
+      .describe("Opaque JSON snapshot captured at rotation time (per-secret, heterogeneous). Null when none."),
+  })
+  .describe("One append-only rotation audit row in the per-environment secrets D1 (`pithy_secrets_rotations`).");
+export type SecretRotation = z.output<typeof SecretRotation>;

package/src/data/statusDb.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { createDatabase } from "@pithy-sh/core/src/data/db";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { Context } from "hono";
+import type { SecretsStatusDb } from "../admin/status";
+import { secretsTables } from "./tables";
+
+/**
+ * The per-environment secrets D1 for one request, typed over this capability's tables.
+ *
+ * One reader, because there are now two callers — the management routes and the manifest's health
+ * summary — and a binding rule that lives at a call site is a rule the second call site gets wrong.
+ * Every defect class in this kit with three producers began exactly there.
+ */
+export function secretsStatusDatabase(c: Context<PithyHonoEnv>): SecretsStatusDb {
+  const binding = (c.env as Record<string, unknown>).SECRETS as D1Database | undefined;
+  if (!binding) {
+    throw new InternalError({
+      message: "The secrets store is not configured.",
+      action: "Bind a D1 database named SECRETS in wrangler.jsonc.",
+      detail: "The secrets management surface requires a `SECRETS` D1 binding; none was present on env.",
+    });
+  }
+  return createDatabase(binding, secretsTables);
+}

package/src/data/systemSecrets.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { SecretValueType } from "../registry";
+
+/**
+ * The `pithy_secrets_system_secrets` table — one encrypted row per stored secret in the
+ * per-environment secrets D1. Ported from the CMS `system_secrets` model.
+ *
+ * The row carries an AES-256-GCM envelope (`encryptedValue` + `iv`) plus the `keyVersion`
+ * that produced it, so the at-rest key-rotation job can re-encrypt under a new master key
+ * without a consumer-visible change. The decrypted plaintext is a JSON version→value map
+ * (`{ "1": <value> }`), so adding value-rotation later is append-a-version, not reshape.
+ *
+ * `z.output` is the app shape (a `Date` for the timestamps); `z.input` is the SQLite row
+ * shape (ms-epoch numbers), via the `SQLiteDate` codec.
+ */
+export const SystemSecret = z
+  .object({
+    id: z
+      .number()
+      .int()
+      .describe("Surrogate primary key, autoincremented by SQLite. Lookups use the unique `name` column."),
+    name: z
+      .string()
+      .describe(
+        "Stable identifier for the secret: a registry entry name, or `<keyspace>/<key>` for one member of a keyed entry; uniquely indexed.",
+      ),
+    encryptedValue: z.string().describe("Base64-encoded AES-256-GCM ciphertext of the version→value map."),
+    iv: z.string().describe("Base64-encoded initialization vector; unique per encryption operation."),
+    keyVersion: z
+      .number()
+      .int()
+      .describe("Master-key version that produced this ciphertext; supports overlapping at-rest rotation windows."),
+    valueType: SecretValueType.describe(
+      "How the decrypted plaintext is interpreted once unwrapped from the version map: `text` or `json`.",
+    ),
+    createdAt: SQLiteDate.describe("When the secret was first written. Ms-epoch in SQLite, a `Date` in app code."),
+    updatedAt: SQLiteDate.describe("When the secret was last written. Ms-epoch in SQLite, a `Date` in app code."),
+  })
+  .describe("One encrypted secret row in the per-environment secrets D1 (`pithy_secrets_system_secrets`).");
+export type SystemSecret = z.output<typeof SystemSecret>;

package/src/data/tables.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SecretRotation } from "./secretRotations";
+import { SystemSecret } from "./systemSecrets";
+
+/**
+ * The secrets capability's table map: camelCase keys (CamelCasePlugin emits the snake_case
+ * `pithy_secrets_` SQL). One source of truth, shared by the capability wiring (`capability.ts`)
+ * and the D1 store (`store/systemSecretsStore.ts`) so both type against the same schema.
+ */
+export const secretsTables = {
+  pithySecretsSystemSecrets: SystemSecret,
+  pithySecretsRotations: SecretRotation,
+};
+export type SecretsTables = typeof secretsTables;