@pithy-sh/secrets 0.1.0

package/src/capability.ts

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { secretsHealth } from "./admin/health";
+import { EncryptionConfig } from "./crypto/envelope";
+import { secretsTables } from "./data/tables";
+import { MASTER_KEY_BINDING } from "./env/bindings";
+import { secretsAdminRoutes } from "./http/guards";
+import { registerSecretsRoutes, SECRETS_DEFAULT_BASE_PATH } from "./http/routes";
+import { secrets_0001_init } from "./migrations/0001_init";
+import { MANAGER_CF_API_TOKEN_SECRET } from "./provision/provisionSecrets";
+import { defineSecretRegistry, type SecretRegistry, type SecretRegistryEntry } from "./registry";
+import {
+  aggregateSecretRegistries,
+  configureSharedSecrets,
+  DEFAULT_SECRETS_CACHE_TTL_SECONDS,
+} from "./sharedSecretsStore";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * The secrets manager's own token profile — the standard default for its least-privilege runtime
+ * credential. Declared here, next to the capability, and consumed as the single source of that scope
+ * (the CLI provisioner mints the manager token from it). Secrets Store read + write, nothing else.
+ *
+ * `secretScope: "global"` is load-bearing, not documentation. It puts the literal `global` in the
+ * environment slot of the store entry the minted value is written to, so `pithy token mint secrets`
+ * lands on `<project>-global-secrets-manager-cf-api-token` — byte-identical to what
+ * `managerCfApiTokenSecretName` provisions and what the manager's `CLOUDFLARE_API_TOKEN` binding
+ * reads. Drop it and a mint writes a per-environment entry nothing binds, leaving the manager on a
+ * credential the operator believes they just rolled.
+ */
+export const secretsTokenProfile = {
+  permissions: ["secrets:read", "secrets:write"],
+  secret: MANAGER_CF_API_TOKEN_SECRET,
+  secretScope: "global",
+  defaultStore: "secrets-store",
+  description: "The secrets manager's runtime credential — reads and writes CF Secrets Store from its Worker.",
+} as const;
+
+/**
+ * The master key, declared as what it already is: a `cf-secrets-store` secret, one value for the whole
+ * project, read from the `SECRETS_ENCRYPTION_KEYS` binding (#179).
+ *
+ * **It was a bare `requiredBindings` entry with no backend, scope, rotatable or valueType** — so nothing
+ * could route it, and local dev had to keep it in a file of its own with a special case at every reader.
+ * Production has always stored it in the account's Secrets Store, under the entry `masterKeySecretName`
+ * composes; this records that, and dev then materialises it from `secrets.jsonc` like every other secret
+ * of that backend.
+ *
+ * **`json`, against `EncryptionConfig`, because that is what the value is.** A hand-edit that drops
+ * `lastRotatedAt` or mistypes a key version is caught by the seeder naming the secret, rather than by a
+ * Worker answering every request with `secrets/crypto_failed`.
+ *
+ * **`bootstrap`, because the Worker reads it without the decoder.** See the axis for why that is the one
+ * secret whose binding carries its value rather than its envelope — and, since #323, the one secret whose
+ * entry in `secrets.jsonc` is that value rather than an envelope around it. Both statements are the same
+ * rule: the file states the payload the destination receives.
+ *
+ * **No `devValue`.** A random string is not an `EncryptionConfig`, and the registry refuses `devValue` on
+ * a non-text entry for exactly that reason. `pithy add secrets` mints one properly, through
+ * `initialMasterKeyConfig`, and writes it into `secrets.jsonc`.
+ *
+ * **`rotatable: false` is about *value* versions, not key versions.** The master key rotates on the
+ * `versions` map inside its own `EncryptionConfig` — that is what `atRestKeyRotation` walks — and a
+ * second value-envelope version on top would be a second rotation axis for one key.
+ *
+ * **`origin` is a structured mint, and that is why `SecretRecipe` is a union (#322).** The issue that
+ * introduced these axes asserted this secret was minted from a random string. It is minted — by
+ * `initialMasterKeyConfig` — and its value is an `EncryptionConfig`, so a `recipe` that knew only
+ * `random` would have failed on the first secret it was drafted around. `recipe: "encryptionConfig"` says
+ * both halves, which is why the entry still carries no `devValue` and `isMintableSecret` still answers
+ * false: nothing arbitrary fills this.
+ *
+ * **`rotation: "local"` and `rotatable: false` are not in conflict.** They answer different questions.
+ * Replacing this value is something the kit does entirely by itself — that is `local`. Whether the stored
+ * *envelope* accumulates versions is `rotatable`, and here it does not, because the versions live inside
+ * the value.
+ */
+export const masterKeyRegistryEntry: SecretRegistryEntry = {
+  backend: "cf-secrets-store",
+  scope: "environment",
+  rotatable: false,
+  bootstrap: true,
+  valueType: "json",
+  schema: EncryptionConfig,
+  origin: { kind: "minted", recipe: { kind: "encryptionConfig" } },
+  rotation: { kind: "local" },
+  notes: "The at-rest master key every other secret is encrypted under. Minted by pithy add secrets.",
+};
+
+/** Sort order of the secrets migrations within the `SECRETS` database. */
+const SECRETS_MIGRATION_ORDER = 100;
+
+/** Default at-rest key-rotation cadence, in days. */
+const DEFAULT_ROTATION_INTERVAL_DAYS = 30;
+
+/** Configuration for the secrets capability, passed in `pithy.config.ts`. */
+export interface SecretsConfig {
+  /**
+   * The project's secret registry — the single source of truth for backend, scope, rotatability,
+   * value type, and (for json) schema, per secret. Both the worker's `secretsStore` and the
+   * `pithy secrets` CLI read it: the CLI discovers it off this capability in `pithy.config.ts`.
+   */
+  registry: SecretRegistry;
+  /** At-rest key-rotation cadence in days. Defaults to 30. Surfaced as the `rotationIntervalDays` option. */
+  rotationIntervalDays?: number;
+  /**
+   * Lifetime in seconds of the shared per-invocation secrets cache. Within one worker invocation
+   * every capability's secrets are resolved once and reused for this long; after it elapses the next
+   * access re-fetches the full combined set. Defaults to 60. Lower it to pick up a rotated secret
+   * sooner; raise it to cut Secrets Store round-trips further.
+   */
+  secretsCacheTtlSeconds?: number;
+  /**
+   * Mount the management surface somewhere other than `/secrets`. Moves the paths the control-plane
+   * manifest advertises with it, so a client composing its calls from the manifest follows.
+   */
+  basePath?: string;
+}
+
+/**
+ * The secrets capability, with its registry attached. The attachment is what lets the
+ * `pithy secrets` CLI discover the registry by loading `pithy.config.ts` and finding this
+ * capability — no separate registry-loading convention needed.
+ */
+export interface SecretsCapability extends Capability {
+  secretRegistry: SecretRegistry;
+  rotationIntervalDays: number;
+  secretsCacheTtlSeconds: number;
+}
+
+/**
+ * The secrets capability. It contributes a **dedicated** `SECRETS` D1 database — distinct from the
+ * app `DB`, because the app database is provisioned ephemerally per feature branch and secrets are
+ * durable and shared, so they cannot be the same database. It requires the `SECRETS` D1 binding and
+ * the `SECRETS_ENCRYPTION_KEYS` master-key binding (CF Secrets Store, worker-only), and carries the
+ * project's {@link SecretRegistry} — with {@link masterKeyRegistryEntry} merged in, so the binding it
+ * requires and the secret that fills it are one declaration rather than two that can drift.
+ *
+ * It also contributes a **read-only** control-plane surface behind `secrets:status:read` — when each
+ * secret was last rotated, and whether it is past the cadence its registry entry declares. Metadata
+ * only, and structurally so: `http/responses.ts` has no field that could carry a value. Like every
+ * capability's, the routes are always mounted and default-denied — with `controlplane()` uncomposed each
+ * one raises `controlplane/not_connected`, because a management surface that appears only when something
+ * else is installed is a surface nobody can discover.
+ */
+export function secrets(config: SecretsConfig): SecretsCapability {
+  const ttlSeconds = config.secretsCacheTtlSeconds ?? DEFAULT_SECRETS_CACHE_TTL_SECONDS;
+  // The capability's own secret, merged under the adopter's so a project that declares nothing still has
+  // a routable master key — and so an adopter who deliberately overrides the entry keeps that power.
+  //
+  // Validated on the way out, because the merge is what produces the registry everything else reads and
+  // it is the one registry nothing had checked: `masterKeyRegistryEntry` is a plain const, and an
+  // override arrives from `pithy.config.ts` where an adopter may well have written an object literal.
+  // Re-checking an already-defined registry costs nothing and is the difference between a contradiction
+  // caught at boot and one discovered by a client rendering it.
+  const registry: SecretRegistry = defineSecretRegistry({
+    [MASTER_KEY_BINDING]: masterKeyRegistryEntry,
+    ...config.registry,
+  });
+  // Resolved once, here, and handed to both the router and the manifest — so the advertised admin paths
+  // and the mounted ones cannot disagree about where the surface lives.
+  const mountPath = config.basePath ?? SECRETS_DEFAULT_BASE_PATH;
+  // What the status surface reports over, replaced by `compose` with the combined registry. It starts as
+  // this capability's own so a Worker that somehow answers before composing still reports honestly
+  // rather than emptily; after compose it is every capability's, which is the useful answer — a project's
+  // auth signing key and email link key are secrets its owner needs the status of just as much.
+  const reported = { current: registry };
+  const capability = defineCapability({
+    name: "secrets",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    secretRegistry: registry,
+    tokenProfiles: { secrets: secretsTokenProfile },
+    requiredBindings: [
+      { type: "d1", name: "SECRETS" },
+      { type: "secret", name: "SECRETS_ENCRYPTION_KEYS" },
+    ],
+    databases: {
+      secrets: {
+        binding: "SECRETS",
+        tables: secretsTables,
+        migrationOrder: SECRETS_MIGRATION_ORDER,
+        migrations: { "0001_init": secrets_0001_init },
+      },
+    },
+    routes: registerSecretsRoutes({ registry: () => reported.current, basePath: mountPath }),
+    // Built from the resolved mount path, never the default: an adopter who mounts this at `/vault` gets
+    // a manifest naming `/vault/admin/status`, which is what a management client composes its calls from.
+    adminRoutes: secretsAdminRoutes(mountPath),
+    // One number on the manifest entry — how many secrets are past their declared cadence — so a client
+    // renders "3 need rotating" beside the rail from the read it already made, instead of spending a
+    // credential per screen load to ask (#317). Behind the same scope as the listing it summarizes, and
+    // over the same combined registry, so a secret whose freshness can be seen is one this counts.
+    health: secretsHealth(() => reported.current),
+    // At worker startup, merge every capability's secret-registry slice into one combined registry and
+    // back the shared per-invocation accessor from it — so all secrets resolve in one batch, shared
+    // across capabilities, with this capability's configured TTL.
+    compose: ({ capabilities }) => {
+      const combined = aggregateSecretRegistries(capabilities);
+      configureSharedSecrets({ registry: combined, ttlSeconds });
+      // The same combined set the accessor resolves is the set the status surface reports. One
+      // aggregation, so a secret that can be read is a secret whose freshness can be seen.
+      reported.current = combined;
+    },
+  });
+  return Object.assign(capability, {
+    secretRegistry: registry,
+    rotationIntervalDays: config.rotationIntervalDays ?? DEFAULT_ROTATION_INTERVAL_DAYS,
+    secretsCacheTtlSeconds: ttlSeconds,
+  });
+}
+
+/** Whether a capability is the secrets capability — carries a registry. The CLI uses this to discover it. */
+export function isSecretsCapability(capability: Capability): capability is SecretsCapability {
+  return capability.name === "secrets" && "secretRegistry" in capability;
+}

package/src/cli/audit.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The `ls --check` audit. Compares the secrets the registry declares against what is actually
+ * present in an environment, surfacing two problems:
+ *
+ *   - **missing** — a declared secret with no value in this env. The app needs it, so this is what
+ *     the promote gate fails on (`ls --check --env prod`): a newly-required secret must be set
+ *     before prod deploys against it.
+ *   - **orphan** — a stored secret no longer in the registry. Harmless but worth cleaning up.
+ *
+ * Pure set logic — the caller gathers `expectedNames` (registry) and `presentNames` (the store's D1
+ * metadata + bound CF Secrets Store entries) for the env.
+ */
+export interface AuditResult {
+  missing: string[];
+  orphan: string[];
+}
+
+export function auditSecrets(expectedNames: string[], presentNames: string[]): AuditResult {
+  const present = new Set(presentNames);
+  const expected = new Set(expectedNames);
+  return {
+    missing: [...expected].filter((name) => !present.has(name)).sort(),
+    orphan: [...present].filter((name) => !expected.has(name)).sort(),
+  };
+}
+
+/** The promote gate: an env is promotable only when no declared secret is missing a value. */
+export function passesPromoteGate(audit: AuditResult): boolean {
+  return audit.missing.length === 0;
+}

package/src/cli/dispatch.ts

@@ -0,0 +1,192 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import type { RotationTrigger } from "../data/secretRotations";
+import type { SecretBackend, SecretScope, SecretValueType } from "../registry";
+import type { RotationClosure } from "../rotation/rotationLedger";
+import type { ManagedEnvironment } from "../scope";
+import { partialWriteReport } from "./partialWrite";
+import { secretWriteTargets } from "./writeTargets";
+
+/**
+ * One write/delete dispatched to a single environment's manager Workflow. The CLI never encrypts or
+ * writes locally — the master key is worker-only — so every value-touching command becomes one of
+ * these per target environment.
+ */
+export interface SecretWriteRequest {
+  env: ManagedEnvironment;
+  mode: "create" | "update" | "delete";
+  name: string;
+  /** Present for create/update; omitted for delete. Already validated + canonicalized by the CLI. */
+  value?: string;
+  valueType?: SecretValueType;
+  rotatable?: boolean;
+}
+
+/**
+ * The dispatch seam: send one request to an environment's manager Workflow and resolve once it
+ * reaches a terminal state. Stubbed in tests; backed by the CF Workflows REST client (dispatch +
+ * poll) in the manager-worker/provisioning slice.
+ */
+export interface SecretDispatcher {
+  dispatch(request: SecretWriteRequest): Promise<void>;
+}
+
+/** One presence question, asked of one environment's manager. Carries a name and nothing else. */
+export interface SecretProbeRequest {
+  env: ManagedEnvironment;
+  /** The secret to ask about. */
+  name: string;
+}
+
+/**
+ * **The read seam, and it is deliberately its own.** A `d1` secret's value is sealed under a master
+ * key that never leaves the manager Worker, so whether one exists is a question only the manager can
+ * answer — and provisioning has to ask it *before* deciding, because a per-environment decision taken
+ * during a fan-out cannot preserve a cross-environment invariant.
+ *
+ * Separate from {@link SecretDispatcher} because the contracts are opposites: one mutates and returns
+ * nothing, this returns and mutates nothing. Folding a read into a writer is how a "check" ends up
+ * being the write it was meant to gate.
+ *
+ * It resolves to a bit. It never resolves to a value, and there is no shape of request that would make
+ * it.
+ */
+export interface SecretProbe {
+  probe(request: SecretProbeRequest): Promise<boolean>;
+}
+
+/** Open one rotation row, in one environment's manager, before anything is rolled. */
+export interface SecretRotationOpenRequest {
+  /** Which environment's ledger. The rotation table is per-environment, like the store it describes. */
+  env: ManagedEnvironment;
+  /** The secret being rotated, by registry name. */
+  name: string;
+  /** What caused it. `manual` from a command, `cron` from a schedule — never `baseline`, which is a first write. */
+  trigger: RotationTrigger;
+  /** Who asked. See `./rotationLedger.ts` for what the CLI can honestly put here. */
+  rotatedBy: string;
+}
+
+/** Close a row opened by {@link SecretRotationRecorder.openRotation}, with what the run did in that environment. */
+export interface SecretRotationCloseRequest {
+  /** The environment whose row this is. */
+  env: ManagedEnvironment;
+  /** The row id that environment's manager handed back when it opened. */
+  rotationId: number;
+  /** How it closes there. A code and never free text — a value cannot be pasted into an enum. */
+  closure: RotationClosure;
+}
+
+/**
+ * **The rotation-ledger seam, and it is deliberately its own.**
+ *
+ * `pithy_secrets_rotations` lives in the per-environment secrets D1, which the CLI cannot reach — the same
+ * reason {@link SecretProbe} exists. So a rotation records the way it writes: one dispatch to that
+ * environment's manager Workflow, which holds the database.
+ *
+ * Separate from {@link SecretDispatcher} because the contracts differ in the way that matters: a write
+ * returns nothing, and opening a row returns the id the close needs. Folding an id-returning call into a
+ * `Promise<void>` writer is how the id gets dropped and the row never closes.
+ */
+export interface SecretRotationRecorder {
+  /** Open an `in_progress` row and return its id. */
+  openRotation(request: SecretRotationOpenRequest): Promise<number>;
+  /** Close a row previously opened in the same environment. */
+  closeRotation(request: SecretRotationCloseRequest): Promise<void>;
+}
+
+/** A value-touching command before routing — the CLI resolves backend/scope from the registry. */
+export interface SecretWrite {
+  mode: "create" | "update" | "delete";
+  name: string;
+  backend: SecretBackend;
+  scope: SecretScope;
+  rotatable: boolean;
+  valueType: SecretValueType;
+  /** The validated value for create/update; omitted for delete. */
+  value?: string;
+  /**
+   * The environment the operator named, or `undefined` when they named none.
+   *
+   * Optional, and that is the point. A missing `--env` on a `global` secret used to be resolved to the
+   * canonical environment before it got here, which erased the difference between *narrow this write*
+   * and *say nothing* — and `secretWriteTargets` refuses on exactly that difference. An
+   * `environment`-scoped write still requires one; the rule says so rather than a default hiding it.
+   */
+  requested?: ManagedEnvironment;
+}
+
+/** Every environment written before an interrupted fan-out threw. See {@link environmentsWrittenBeforeFailure}. */
+const dispatched = partialWriteReport<ManagedEnvironment[]>(
+  "pithy.secrets.dispatchedBeforeFailure",
+  (value): value is ManagedEnvironment[] => Array.isArray(value) && value.every((env) => typeof env === "string"),
+);
+
+/**
+ * The environments an interrupted {@link dispatchSecretWrite} actually reached, in order. Empty when the
+ * thrown thing carries no report — which is the honest answer for a throw from anywhere else.
+ *
+ * **This is the whole of what the product can offer against a mid-fan-out fault.** There is no
+ * transaction across environments and no rollback — each is a separate Workflow in a separate Worker,
+ * and a compensating write is itself a Workflow that can fail. So a split that a fault created is not
+ * prevented; it is *reported*, by name, to the operator who has to repair it. `runSecretWrite` puts these
+ * environments in the failure audit and `pithy secrets` prints them before the error.
+ */
+export function environmentsWrittenBeforeFailure(error: unknown): ManagedEnvironment[] {
+  return dispatched.read(error) ?? [];
+}
+
+/**
+ * Decide where a write may land (`secretWriteTargets`), then dispatch it to each target environment's
+ * manager, in order. A `global` write reaches every declared environment; an `environment` write reaches
+ * exactly one. Returns the environments written, for the CLI to report.
+ *
+ * **The decision is taken before the first dispatch, and it is not taken here.** `secretWriteTargets`
+ * owns it, `mintDeclaredSecrets` asks the same function, and a `global` write that names an environment
+ * is refused with nothing sent. That is what keeps an operator from creating a split by asking for one.
+ *
+ * **What it cannot do is undo a fan-out that died in the middle**, so it does not pretend to. The
+ * environments already written are attached to whatever ended the run and read back with
+ * {@link environmentsWrittenBeforeFailure}. Grown one at a time and pushed only *after* the write it
+ * describes lands, because an environment named before its dispatch resolved is a plan, and a plan
+ * printed as a result is how a partial run reports work it never did (#324).
+ *
+ * `declared` is the project's environment set, from the root `pithy.config.ts`. It is what a `global`
+ * write fans out across, so passing the wrong one writes a shared secret into some environments and not
+ * others — which is why it is an argument here rather than a default anything can forget.
+ */
+export async function dispatchSecretWrite(
+  dispatcher: SecretDispatcher,
+  write: SecretWrite,
+  declared: DeclaredEnvironments | readonly string[],
+): Promise<ManagedEnvironment[]> {
+  const targets = secretWriteTargets({
+    name: write.name,
+    backend: write.backend,
+    scope: write.scope,
+    mode: write.mode,
+    requested: write.requested,
+    declared,
+  });
+  const written: ManagedEnvironment[] = [];
+  try {
+    for (const env of targets) {
+      await dispatcher.dispatch({
+        env,
+        mode: write.mode,
+        name: write.name,
+        value: write.value,
+        valueType: write.valueType,
+        rotatable: write.rotatable,
+      });
+      written.push(env);
+    }
+  } catch (error) {
+    throw dispatched.carry(error, written);
+  }
+  // What landed, not what was planned. They agree on every run that finishes, and the one that does not
+  // is the run whose answer matters.
+  return written;
+}

package/src/cli/partialWrite.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **How a run that failed part-way still says what it wrote.**
+ *
+ * A fan-out across environments has no transaction. The third write throws, the first two already
+ * landed, and the return value that would have named them never happens — so the operator is told
+ * nothing was done while two environments hold a brand-new signing key. That is the state #324 found in
+ * `mintDeclaredSecrets` and #325 found again in `dispatchSecretWrite`, which is the path every
+ * `pithy secrets create`, `update` and `rm` takes.
+ *
+ * The fix is the same both times, so it is written once here rather than twice at the call sites — two
+ * producers of one rule is the defect class this repository has produced four times over.
+ *
+ * **Carried, never replaced.** The report is attached to whatever ended the run and the same thing is
+ * rethrown: same class, same payload, same `instanceof`. The failure an operator has to read is
+ * unchanged, and what the run wrote is what makes the remedy in it safe to perform.
+ *
+ * **A symbol, non-enumerable, and not a payload field.** The payload is what the HTTP codec encodes and
+ * what `--json` prints as `{ error }`; this is the command's own output, on its own stream. Non-enumerable
+ * so nothing serializing an error picks it up by accident.
+ *
+ * **The one thing it cannot carry: a thrown primitive.** Nothing can be attached to a thrown string, so a
+ * caller that throws one loses its report. Replacing it with a wrapper would fix that and break the rule
+ * this is built on — the failure an operator reads must be the failure that happened. Everything in this
+ * repository throws a `PithyError`, and the kit's own linting says so; a dependency that throws a string
+ * is the case this trades away deliberately.
+ *
+ * **`Symbol.for`, and one key per report.** The key is registry-global, so a report attached inside
+ * `@pithy-sh/secrets` is readable from `@pithy-sh/cli` however the module graph resolved. Distinct keys
+ * because there are genuinely two reports with two shapes — what a mint run created, and which
+ * environments one dispatch reached — and a single shared key would let one reader decode the other's
+ * payload as its own.
+ */
+
+/** Attach a report to a failing run, and read one back off whatever it threw. */
+export interface PartialWriteReport<P> {
+  /** Attach `report` to `error` and hand the same thing back, to be rethrown unchanged. */
+  carry<E>(error: E, report: P): E;
+  /** The report this run attached, or `undefined` for a throw from anywhere else. */
+  read(error: unknown): P | undefined;
+}
+
+/**
+ * One report channel, keyed by `key`. Call this once per module, at module scope: the key is the
+ * contract between the writer and the reader, and one built per call would be a channel nobody else
+ * can open.
+ *
+ * `isReport` is what makes reading safe. A carried value arrives as `unknown` — the error may have
+ * crossed a package boundary, or been constructed by something else entirely — so the reader narrows it
+ * rather than casting, exactly as every other boundary in this repository does.
+ */
+export function partialWriteReport<P>(key: string, isReport: (value: unknown) => value is P): PartialWriteReport<P> {
+  const symbol = Symbol.for(key);
+  return {
+    carry<E>(error: E, report: P): E {
+      if (typeof error === "object" && error !== null) {
+        Object.defineProperty(error, symbol, { value: report, enumerable: false, configurable: true });
+      }
+      return error;
+    },
+    read(error: unknown): P | undefined {
+      if (typeof error !== "object" || error === null) return undefined;
+      const carried = (error as Record<symbol, unknown>)[symbol];
+      return isReport(carried) ? carried : undefined;
+    },
+  };
+}

package/src/cli/rotationLedger.ts

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { RotationTrigger } from "../data/secretRotations";
+import type { OpenRotation, RotationLedger } from "../rotation/rotationLedger";
+import { rotationClosure } from "../rotation/rotationLedger";
+import type { ManagedEnvironment } from "../scope";
+import type { SecretRotationRecorder } from "./dispatch";
+
+/**
+ * **The out-of-process {@link RotationLedger}: the same rows, written the only way the CLI can write them.**
+ *
+ * A rotation's history belongs in the environment's own secrets D1, and the CLI holds no handle to one —
+ * the master key is worker-only, which is why every value-touching command is a dispatch. So the ledger is
+ * dispatched too, through {@link SecretRotationRecorder}, and lands on the same `RotationTracker` the
+ * in-Worker ledger uses. That is the whole of `#379`'s fix: not a second mechanism for the command line,
+ * the same mechanism reached over a different wire.
+ *
+ * ## One row per target environment
+ *
+ * A `global` secret rotates in every declared environment at once, and each has its own ledger. A single
+ * aggregate row would have to live somewhere, and wherever it lived it would answer *is this environment's
+ * credential fresh* for environments it was not about. So this opens one row per target and closes each
+ * with {@link rotationClosure} against that environment — a fan-out that reached staging and stranded prod
+ * closes `success` in one ledger and `failed` in the other, which is what actually happened.
+ *
+ * ## A manager that cannot be reached costs a row, never the rotation
+ *
+ * Each open and each close is attempted independently and a failure is dropped. The rotation is the act;
+ * the row is the record of it. Refusing to roll a credential during the incident that demanded it, because
+ * one environment's manager would not answer, is the wrong trade in both directions — and the missing row
+ * is itself visible, as a gap in the history and a `lastRotatedAt` that did not move.
+ */
+
+/**
+ * Who a command-line rotation is recorded as.
+ *
+ * **It names the path, not the person, and that is deliberate rather than a shortcut.** `createCliAudit`
+ * resolves an operator from the Cloudflare API token and falls back to `system, actorResolutionFailed`
+ * when there is none — so the honest answer to *who* is on the `secrets/rotated` audit event, where the
+ * resolver already runs. Writing a guessed name into the rotation row would put a second, weaker answer to
+ * the same question in a second place, and an incident review comparing them would have no way to tell
+ * which one was resolved. What this row does say — and what the audit trail cannot — is which of the two
+ * paths performed the act.
+ */
+export const CLI_ROTATED_BY = "pithy secrets rotate";
+
+/** What a dispatched ledger needs: where the rotation lands, and how the rows are labeled. */
+export interface DispatchedRotationLedgerOptions {
+  /** Every environment this rotation writes to. One row is opened in each. */
+  targets: readonly ManagedEnvironment[];
+  /** What caused it. Defaults to `manual` — a person at a terminal. */
+  trigger?: Exclude<RotationTrigger, "baseline">;
+  /** Who to record. Defaults to {@link CLI_ROTATED_BY}. */
+  rotatedBy?: string;
+}
+
+/** A row this ledger managed to open, and where. */
+interface OpenedRow {
+  env: ManagedEnvironment;
+  rotationId: number;
+}
+
+/** The CLI's {@link RotationLedger}, over the manager write-Workflow. */
+export function dispatchedRotationLedger(
+  recorder: SecretRotationRecorder,
+  options: DispatchedRotationLedgerOptions,
+): RotationLedger {
+  const trigger = options.trigger ?? "manual";
+  const rotatedBy = options.rotatedBy ?? CLI_ROTATED_BY;
+  return {
+    async open(name: string): Promise<OpenRotation> {
+      const opened: OpenedRow[] = [];
+      for (const env of options.targets) {
+        try {
+          opened.push({ env, rotationId: await recorder.openRotation({ env, name, trigger, rotatedBy }) });
+        } catch {
+          // One manager short of a full history is a gap. It is not a reason to leave the credential alone.
+        }
+      }
+      return {
+        async close(outcome): Promise<void> {
+          for (const row of opened) {
+            try {
+              await recorder.closeRotation({
+                env: row.env,
+                rotationId: row.rotationId,
+                closure: rotationClosure(outcome, row.env),
+              });
+            } catch {
+              // The row stays `in_progress`, which reads as an attempt whose end is unknown — true.
+            }
+          }
+        },
+      };
+    },
+  };
+}

package/src/cli/validate.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SecretInvalidValueError } from "../error/errors";
+import type { SecretRegistryEntry } from "../registry";
+
+/**
+ * The CLI's authoritative, client-side value validation (the A2 model). The worker cannot validate
+ * a not-yet-deployed secret's shape, so the CLI — which runs from the user's repo with the fresh
+ * registry — is the validator. A `text` value passes through; a `json` value is parsed and validated
+ * against the entry's schema, then returned re-serialized (canonical form) for dispatch.
+ *
+ * Errors are redacted: only `path:code`, never `issue.message`/the payload, which can echo the
+ * secret material. This mirrors the read seam's `parseValue` so write-time and read-time validation
+ * report identically.
+ */
+export function validateSecretValue(entry: SecretRegistryEntry, name: string, raw: string): string {
+  if (entry.valueType === "text") return raw;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new SecretInvalidValueError(
+      { message: `Secret '${name}' is not valid JSON.`, detail: `json secret '${name}' failed to parse` },
+      { cause },
+    );
+  }
+  const result = entry.schema.safeParse(parsed);
+  if (!result.success) {
+    const summary = result.error.issues.map((i) => `${i.path.join(".") || "<root>"}:${i.code}`).join(", ");
+    throw new SecretInvalidValueError({
+      message: `Secret '${name}' failed validation.`,
+      detail: `json secret '${name}' failed registry validation: ${summary}`,
+    });
+  }
+  return JSON.stringify(result.data);
+}