@pithy-sh/secrets 0.1.0

package/src/keyspaceWrite.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { appendVersion, initialVersionedValue } from "./crypto/versionedValue";
+import { SecretAlreadyExistsError, SecretNotFoundError } from "./error/errors";
+import type { SecretValueType } from "./registry";
+import type { RotationTracker } from "./store/rotationTracker";
+import type { SystemSecretsStore } from "./store/systemSecretsStore";
+
+/**
+ * The **request-path** write for one keyspace member — the counterpart to `management/writeSecret.ts`,
+ * and a different operation rather than a nicer API for the same one.
+ *
+ * Sealing can only happen in a Worker: the master key is a binding, and the CLI does not have it. The
+ * management path respects that by dispatching a Workflow, which runs in the Worker — correct for a
+ * secret an operator provisions, because nobody is waiting on the response. It does not fit a
+ * credential an application mints *during* a request. A connect flow generates a keypair, must seal the
+ * private half, and must return the public half in the same response; it cannot dispatch a Workflow and
+ * wait. Returning a public key whose private half is not yet stored hands out a credential that cannot
+ * be used, and discovers it later, at the customer.
+ *
+ * So this runs inline, on the request, through the same {@link SystemSecretsStore} and therefore the
+ * same AES-256-GCM envelope, the same bound name (`<entry>/<key>`, so one tenant's ciphertext does not
+ * open under another's), and the same `pithy_secrets_system_secrets` row every other secret uses. That
+ * last part is not a detail: the at-rest key rotation re-encrypts *rows*, keyed on nothing but
+ * `keyVersion`, so a member written here is picked up by it. A second storage path would have been a
+ * set of rows the cron never visits — the ones that quietly cannot be opened after a rotation.
+ *
+ * The promise resolving **is** the persistence guarantee. Nothing is queued and nothing is deferred, so
+ * a caller that awaits this before returning a credential knows the sealed half is stored.
+ */
+
+/**
+ * What a write is allowed to do to a member that already exists.
+ *
+ * `create` refuses one — the default, because the failure worth designing against is a signing key
+ * silently overwritten mid-rotation, and a create-or-replace default makes that a typo away.
+ * `replace` is the explicit form: every prior version is discarded, which is what a compromised
+ * credential needs and what a retained one must never get by accident. `rotate` appends the value as
+ * the next version and keeps the old ones valid — the two-keys-during-rotation window `getKeyedVersions`
+ * exists to serve.
+ */
+export type KeyedWriteMode = "create" | "replace" | "rotate";
+
+/** One member write, as the accessor hands it to the store. */
+export interface KeyedMemberWrite {
+  /**
+   * The keyspace the member belongs to. Carried beside {@link storedName} because a refusal names the
+   * keyspace and never the key: `detail` reaches logs verbatim, and the key identifies one tenant.
+   */
+  keyspace: string;
+  /** The member's stored name, `<entry>/<key>`, composed by `keyedSecretName` and never by hand. */
+  storedName: string;
+  /** What the write may do to an existing member. */
+  mode: KeyedWriteMode;
+  /** The serialized value — a `text` value as it stands, a `json` value already stringified. */
+  value: string;
+  /** The keyspace's value type, persisted on the row so a read knows how to interpret it. */
+  valueType: SecretValueType;
+  /** Whether the keyspace is rotatable — drives the rotation baseline on a create. */
+  rotatable: boolean;
+}
+
+/** What a member write needs: the encrypted store, and the tracker that owns rotation history. */
+export interface KeyedWriteDeps {
+  store: SystemSecretsStore;
+  tracker: RotationTracker;
+}
+
+/**
+ * Write one member and return its current version key.
+ *
+ * The existence check and the write are two statements, as they are in `runWriteSecret` — D1 has no
+ * transaction to put around them. The window is real and it is the narrowest one available; what it
+ * cannot do is turn a `create` into a silent overwrite, because the write that follows a passed check
+ * still refuses nothing and *overwrites* nothing a concurrent create could have put there. Two
+ * simultaneous creates for one tenant is a shape the caller already has to make impossible, since it
+ * would mint two credentials whatever this did.
+ */
+export async function runKeyedWrite(deps: KeyedWriteDeps, params: KeyedMemberWrite): Promise<string> {
+  if (params.mode === "rotate") {
+    // The only mode that reads the plaintext: appending a version needs the versions already there.
+    const existing = await deps.store.getValue(params.storedName);
+    if (!existing) {
+      throw new SecretNotFoundError({
+        message: `Secret '${params.keyspace}' has no value for that key.`,
+        action: "Create the member before rotating it.",
+        detail: `keyspace '${params.keyspace}': rotate found no member stored under the requested key`,
+      });
+    }
+    const next = appendVersion(existing, params.value);
+    await deps.store.put(params.storedName, next, params.valueType);
+    return next.currentVersion;
+  }
+
+  const exists = await deps.store.has(params.storedName);
+  if (params.mode === "create" && exists) {
+    throw new SecretAlreadyExistsError({
+      message: `Secret '${params.keyspace}' already has a value for that key.`,
+      action: "Rotate the member to add a version, or pass replace to discard the stored one.",
+      detail: `keyspace '${params.keyspace}': create found a member already stored under the requested key`,
+    });
+  }
+
+  const next = initialVersionedValue(params.value);
+  await deps.store.put(params.storedName, next, params.valueType);
+
+  // Same rule the management write follows: a brand-new rotatable secret gets a baseline, so nothing
+  // that measures rotation age reports a member as overdue purely for having no history. It is when
+  // this tenant's credential was established, which is a question with an answer that does not touch
+  // the value.
+  //
+  // Unlike the management write there is no "has it any history" probe first, because a member that
+  // does not exist cannot have any: {@link runKeyedRemove} purges the history with the row, and so
+  // does the management delete. Paying a query per create to re-establish that on a request path is
+  // the wrong trade.
+  if (params.rotatable && !exists) await deps.tracker.recordBaseline(params.storedName);
+  return next.currentVersion;
+}
+
+/**
+ * Remove one member — every version of it, and its rotation history, as one operation.
+ *
+ * Every version goes because they are one row: a member's `{ currentVersion, versions }` envelope is a
+ * single sealed value, so there is no loop for a caller to write and no version that can survive the
+ * tenant it belonged to. The history goes for the reason the management delete purges it — rows naming
+ * a secret that no longer exists are rows nothing will ever explain.
+ *
+ * Idempotent. Removing a tenant twice is a normal shape (a retry, a redelivered webhook), and the
+ * second call must not be an error the caller has to special-case.
+ */
+export async function runKeyedRemove(deps: KeyedWriteDeps, storedName: string): Promise<void> {
+  await deps.store.delete(storedName);
+  await deps.tracker.purgeHistory(storedName);
+}

package/src/management/writeSecret.ts

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { initialVersionedValue } from "../crypto/versionedValue";
+import { SecretAlreadyExistsError, SecretNotFoundError } from "../error/errors";
+import type { SecretValueType } from "../registry";
+import type { RotationTracker } from "../store/rotationTracker";
+import type { SystemSecretsStore } from "../store/systemSecretsStore";
+
+/**
+ * The management write core — the logic the per-env manager Workflow runs when the CLI dispatches
+ * a create/update/remove. Scoped to one environment: the CLI fans a `global` write out to each
+ * env's manager, so this core never replicates.
+ *
+ * **The worker does not validate the value's shape — the CLI does.** A brand-new secret's registry
+ * entry (and schema) is not bundled into any *deployed* manager yet, so the worker cannot be the
+ * authoritative validator without forcing a deploy before a secret can even be seeded (the
+ * chicken-and-egg). The CLI runs from the user's repo with the fresh registry and validates before
+ * dispatching. The worker is therefore a secure-but-dumb writer: enforce create/update intent
+ * (a store read, atomic with the write, so no TOCTOU), encrypt, store, and seed a rotation baseline.
+ *
+ * `create` refuses an existing name; `update` refuses a missing one — the guard that keeps a typo
+ * from creating a second secret or silently overwriting one. `probe` writes nothing and answers
+ * whether a name is there. A new value is written as a fresh one-version envelope
+ * (`initialVersionedValue`); value rotation (append) is a deferred feature.
+ */
+export type WriteSecretParams =
+  | {
+      /** `create` refuses an existing name; `update` refuses a missing one. */
+      mode: "create" | "update";
+      name: string;
+      value: string;
+      valueType: SecretValueType;
+      /** Whether the secret is rotatable — drives whether a rotation baseline is seeded. */
+      rotatable: boolean;
+    }
+  | {
+      /**
+       * **Is this name in the store?** The one read the CLI cannot do for itself: a `d1` value is
+       * sealed under a master key that never leaves this worker, so only the manager can answer.
+       *
+       * It writes nothing, decrypts nothing, and returns nothing but `present` or `absent` — a
+       * presence bit is not a secret, and no path here can be coaxed into returning a value.
+       *
+       * **It replaced `ensure`, and the replacement is the fix.** `ensure` wrote only when the name
+       * was absent and was otherwise a silent no-op, which is a *per-environment* answer to a
+       * *cross-environment* question. A `global` secret is defined by being identical everywhere, and
+       * a run that wrote staging, lost prod, and was re-run minted a second value, found staging
+       * present, skipped it, and wrote the second value to prod — two environments, two values, no
+       * error. Silence is what made that unnoticeable, so the mode that could be silent is gone. The
+       * caller asks first, decides across every environment at once, and writes with `create`, which
+       * cannot skip: it raises. See `cli/mintSecrets.ts` in the CLI.
+       */
+      mode: "probe";
+      name: string;
+    }
+  | { mode: "delete"; name: string };
+
+/**
+ * What one write actually did — the manager's answer, and the thing the caller could not otherwise
+ * know. A `d1` secret is sealed under a master key that never leaves this worker, so "was it already
+ * there" is a question only the store holder can be asked, and dropping the answer on the floor is how
+ * a partial fan-out completes silently.
+ *
+ * A Zod enum rather than a bare union because it crosses back out of the Worker as a Workflow
+ * instance's `output` and is decoded on the far side like every other external input.
+ */
+export const WriteSecretOutcome = z
+  .enum(["written", "present", "absent", "deleted"])
+  .describe(
+    "What a management write did: wrote a new value, found the name already present, found it absent, or removed it.",
+  );
+export type WriteSecretOutcome = z.output<typeof WriteSecretOutcome>;
+
+export interface WriteSecretDeps {
+  store: SystemSecretsStore;
+  tracker: RotationTracker;
+}
+
+export async function runWriteSecret(deps: WriteSecretDeps, params: WriteSecretParams): Promise<WriteSecretOutcome> {
+  if (params.mode === "delete") {
+    await deps.store.delete(params.name);
+    await deps.tracker.purgeHistory(params.name);
+    return "deleted";
+  }
+
+  const exists = await deps.store.has(params.name);
+  // The read, and only the read. Nothing is written, nothing is decrypted, and the answer is one bit.
+  if (params.mode === "probe") return exists ? "present" : "absent";
+  if (params.mode === "create" && exists) {
+    throw new SecretAlreadyExistsError({
+      message: `Secret '${params.name}' already exists.`,
+      detail: `create '${params.name}': already present in the store`,
+    });
+  }
+  if (params.mode === "update" && !exists) {
+    throw new SecretNotFoundError({
+      message: `Secret '${params.name}' does not exist.`,
+      action: "Use create to add a new secret.",
+      detail: `update '${params.name}': not present in the store`,
+    });
+  }
+
+  await deps.store.put(params.name, initialVersionedValue(params.value), params.valueType);
+
+  // Seed a rotation baseline for a brand-new rotatable secret so the cadence check never reports
+  // it immediately overdue purely for lacking history.
+  //
+  // **And nothing else here records anything, which is the point rather than the omission (`#379`).** A
+  // first write establishes a value; a rotation replaces one; they are different events and the ledger
+  // keeps them apart by `trigger`. This is a writer, and a writer cannot tell which it is being used for:
+  // an `update` is a rotation, a value pasted from a console, or a typo fix, and inferring a rotation from
+  // it would advance a freshness clock nobody rotated. The act declares itself — `rotateSecretValue` opens
+  // and closes the row around the roll, for every caller. See `../rotation/rotationLedger.ts`.
+  if (params.rotatable && !exists && (await deps.tracker.getLatestSuccess(params.name)) === null) {
+    await deps.tracker.recordBaseline(params.name);
+  }
+  return "written";
+}

package/src/manager/configWriter.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The write-back seam for the master-key config. The at-rest rotation Workflow updates
+ * `SECRETS_ENCRYPTION_KEYS` (a CF Secrets Store entry) via the CF API — the binding itself is
+ * read-only. This interface decouples the rotation logic from the CF client so the core is
+ * testable with a stub; the real implementation (backed by `@pithy-sh/cloudflare`'s
+ * `CloudflareSecretsStoreManager`) is wired into the manager worker.
+ */
+export interface ConfigWriter {
+  /**
+   * Persist the new `SECRETS_ENCRYPTION_KEYS` value. The write is an in-place update, so a failure
+   * leaves the prior config intact and readable — losing this config would make every stored secret
+   * undecryptable, and no window exists in which it is absent. A failed write throws; the caller
+   * (the rotation Workflow step) retries.
+   */
+  write(value: string): Promise<void>;
+}

package/src/manager/dispatcher.ts

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareWorkflowsClient } from "@pithy-sh/cloudflare/src/workflows/workflowsClient";
+import { UpstreamError } from "@pithy-sh/core/src/error/pithyError";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import type {
+  SecretDispatcher,
+  SecretProbe,
+  SecretProbeRequest,
+  SecretRotationCloseRequest,
+  SecretRotationOpenRequest,
+  SecretRotationRecorder,
+  SecretWriteRequest,
+} from "../cli/dispatch";
+import type { ManagedEnvironment } from "../scope";
+import { WriteWorkflowResult } from "./writeWorkflow";
+
+/**
+ * The `<capability>` segment of every name the secrets manager deploys under — its Worker script, its
+ * D1, and both of its Workflows. One literal, so the manager, the dispatcher, and teardown cannot drift.
+ */
+export const SECRETS_CAPABILITY = "secrets";
+
+/**
+ * The canonical name of one project's manager write-Workflow in one environment —
+ * `<project>-<env>-secrets-write`. This is the contract between the deployed manager and every CLI
+ * dispatch site, so it is defined once here: a rename can't leave a caller dispatching to a Workflow
+ * that does not exist.
+ *
+ * The project segment is not decoration. Workflow names are **account-scoped**, so without it a second
+ * Pithy project in the same account dispatches into the first project's manager — writing its secrets
+ * into another project's database, under another project's master key.
+ *
+ * Named as a **Workflow** through core's facade: 64 characters, and refused rather than truncated. A
+ * Workflow name is a running instance's address, so a silently reshaped one loses whatever was in
+ * flight — and this particular name is also the contract every CLI dispatch resolves against.
+ */
+export function secretsWriteWorkflowName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).workflow(SECRETS_CAPABILITY, "write");
+}
+
+/**
+ * The canonical name of one project's at-rest key-rotation Workflow in one environment —
+ * `<project>-<env>-secrets-rotate`. Triggered by the manager's own cron rather than by the CLI, but
+ * named here beside the write Workflow because both are the same account-scoped namespace and the
+ * manager's resolved `wrangler.jsonc` declares them together.
+ */
+export function secretsRotateWorkflowName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).workflow(SECRETS_CAPABILITY, "rotate");
+}
+
+/**
+ * The real {@link SecretDispatcher}: dispatches a write to the target environment's manager
+ * write-Workflow over the CF Workflows REST API and polls to completion. This is the CLI's write
+ * path — the master key is worker-only, so the CLI never encrypts or stores locally. The dispatched
+ * params carry the (already validated) value, so failures never echo them (see the client).
+ *
+ * **Bound to one project.** The dispatcher resolves the target Workflow itself rather than taking an
+ * env-to-name function: the name needs both the project and the environment, and a seam that took only
+ * the environment quietly invited a caller to supply an unscoped name that resolves to whichever
+ * project provisioned the account last.
+ */
+export class WorkflowSecretDispatcher implements SecretDispatcher, SecretProbe, SecretRotationRecorder {
+  readonly #client: CloudflareWorkflowsClient;
+  readonly #project: string;
+
+  constructor(client: CloudflareWorkflowsClient, project: string) {
+    this.#client = client;
+    this.#project = project;
+  }
+
+  async dispatch(request: SecretWriteRequest): Promise<void> {
+    await this.#client.dispatchAndPoll(secretsWriteWorkflowName(this.#project, request.env), {
+      mode: request.mode,
+      name: request.name,
+      value: request.value,
+      valueType: request.valueType,
+      rotatable: request.rotatable,
+    });
+  }
+
+  /**
+   * Ask one environment's manager whether a name is in its store. The same Workflow, in the one mode
+   * that writes nothing (`management/writeSecret.ts`), so a presence check cannot drift from the write
+   * it gates: they read the same store, in the same worker, through the same code.
+   *
+   * The instance output is **decoded, never trusted**. It arrives over the Workflows REST API as
+   * `unknown`, and an unread field would default to absent — which is the answer that makes
+   * provisioning mint a second value over a live one. A shape nobody expected stops the run instead.
+   */
+  async probe(request: SecretProbeRequest): Promise<boolean> {
+    const output = await this.#client.dispatchAndPoll(secretsWriteWorkflowName(this.#project, request.env), {
+      mode: "probe",
+      name: request.name,
+    });
+    const parsed = WriteWorkflowResult.safeParse(output);
+    if (!parsed.success) {
+      throw new UpstreamError({
+        message: `The ${request.env} secrets manager gave no usable answer about '${request.name}'.`,
+        action: "Redeploy the manager with pithy secrets provision, then run this again.",
+        detail: `probe ${request.name} in ${request.env}: unexpected write-workflow output`,
+      });
+    }
+    return parsed.data.outcome === "present";
+  }
+
+  /**
+   * Open a rotation row in one environment's ledger and return its id.
+   *
+   * The same Workflow again, for the same reason the probe uses it: the rotation table sits in the manager's
+   * own D1, so the process that can write it is the one that can write the value. The output is decoded and
+   * the id demanded — a `rotation-open` that answered with no id would leave the close addressing nothing,
+   * and a row that never closes reads as a rotation still running long after it finished.
+   */
+  async openRotation(request: SecretRotationOpenRequest): Promise<number> {
+    const output = await this.#client.dispatchAndPoll(secretsWriteWorkflowName(this.#project, request.env), {
+      mode: "rotation-open",
+      name: request.name,
+      trigger: request.trigger,
+      rotatedBy: request.rotatedBy,
+    });
+    const parsed = WriteWorkflowResult.safeParse(output);
+    if (!parsed.success || parsed.data.outcome !== "opened" || parsed.data.rotationId === undefined) {
+      throw new UpstreamError({
+        message: `The ${request.env} secrets manager did not record a rotation of '${request.name}'.`,
+        action: "Redeploy the manager with pithy secrets provision so its rotation history is written again.",
+        detail: `rotation-open ${request.name} in ${request.env}: unexpected write-workflow output`,
+      });
+    }
+    return parsed.data.rotationId;
+  }
+
+  /** Close a row this dispatcher opened in the same environment. */
+  async closeRotation(request: SecretRotationCloseRequest): Promise<void> {
+    await this.#client.dispatchAndPoll(secretsWriteWorkflowName(this.#project, request.env), {
+      mode: "rotation-close",
+      rotationId: request.rotationId,
+      closure: request.closure,
+    });
+  }
+}

package/src/manager/managerRegistry.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { defineSecretRegistry } from "../registry";
+
+/**
+ * The secrets-manager worker's own secret registry. The manager reads it the seam's standard way —
+ * `sharedSecretsStore(env, managerRegistry)`, then `.get("CLOUDFLARE_API_TOKEN")` at the point of need, so
+ * every secret use is a visible, grep-able call site. The token is read as a `cf-secrets-store`
+ * binding, never a plaintext env string.
+ *
+ * `CLOUDFLARE_API_TOKEN` is `global` (one value, written once canonically via prod, bound the
+ * same way by every manager) and `rotatable` (forward-looking — a future value-rotator may self-roll
+ * it; no value-rotation logic ships now). Provisioning owns the store-entry-name → binding-var
+ * mapping out of band: the entry lives in the account's one flat Secrets Store under the
+ * project-scoped name `<project>-global-secrets-manager-cf-api-token` (`managerCfApiTokenSecretName`)
+ * and binds into each manager as `CLOUDFLARE_API_TOKEN`, so this registry stays keyed by the binding
+ * var — which is not scoped, and must not be (see `provision/provisionSecrets`).
+ *
+ * **Least privilege — this token needs Secrets Store edit access and nothing else.** The manager's
+ * only runtime use of the token is the at-rest rotation's config write-back (`CloudflareSecretsStoreManager.putSecret`
+ * → list + delete + create on the store). The rotation's D1 re-encryption runs entirely through the
+ * `SECRETS` binding, so the token grants no D1 or Workers access. Scope it to **Account › Secrets
+ * Store › Edit** on the one store. (It is distinct from the broad bootstrap token the CLI uses to
+ * deploy and provision — see `provision/provisionSecrets` for that boundary.)
+ */
+export const managerRegistry = defineSecretRegistry({
+  CLOUDFLARE_API_TOKEN: {
+    backend: "cf-secrets-store",
+    scope: "global",
+    rotatable: true,
+    valueType: "text",
+    // `helped` to create, `provider` to rotate — the case a single axis cannot express, and the reason
+    // #322 has two. We cannot mint a Cloudflare token: that needs credentials for their account, which
+    // this product must never hold. We can say exactly what one needs, so nothing downstream keeps its
+    // own table of permission groups — `needs.cloudflare` is `secretsTokenProfile.permissions`, and
+    // `capability.test.ts` holds the two to each other rather than trusting this copy.
+    origin: {
+      kind: "helped",
+      issuer: "cloudflare",
+      needs: { cloudflare: ["secrets:read", "secrets:write"] },
+      documentation: "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/",
+    },
+    // Cloudflare rolls a token and returns the new value, so this one can replace itself. Declared per
+    // secret and never per issuer: some Cloudflare secrets roll and some do not, and `issuer` says
+    // nothing about which.
+    rotation: {
+      kind: "provider",
+      issuer: "cloudflare",
+      documentation: "https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/update/",
+    },
+  },
+});

package/src/manager/retryPolicy.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What the secrets manager's Workflows retry, and what they refuse to.**
+ *
+ * The manager hosts two Workflows — the CLI's write dispatch and the at-rest key rotation — and both run
+ * against exactly two storage systems: this environment's D1, and the account's CF Secrets Store. That is
+ * a short list of ways a write can fail, so the classification is short too (pithy-sh/pithy#338).
+ *
+ * ## Terminal, and why
+ *
+ * - **`secrets/already_exists`** — `create` refusing a name that is already there. This is the write path
+ *   *succeeding at its job*: the refusal is what closes the concurrent-write race, and it is what stops a
+ *   typo minting a second secret over a live one. A name does not stop existing because you asked twice,
+ *   so the retry is pure delay dressed as resilience.
+ * - **`secrets/not_found`** — `update` refusing a name that is not there. The same argument, mirrored.
+ * - **`secrets/invalid_value`**, **`validation/invalid_input`** — a value or a payload the schema refuses.
+ *   Deterministic in the input; a second attempt parses the same bytes.
+ * - **`secrets/crypto_failed`** — a missing key version or unreadable ciphertext. A key that is not in the
+ *   bound key set will not be in it on the next attempt either; this one wants an operator, not a backoff.
+ * - **A value too large for the Secrets Store** — a limit, and a refusal, not an outage.
+ *
+ * ## Retryable, and why
+ *
+ * - **`core/upstream_failed` / `core/upstream_timeout`** — the Cloudflare API, unreachable or out of time.
+ *   Only the rotation write-back talks to it; the next attempt may well reach it.
+ * - **A transient D1 fault** — busy, timed out, connection lost, storage reset, internal. Core classifies
+ *   those (`withD1Retry`), the write path already retries them in-process, and a step re-drive is the
+ *   second, much longer backoff for a database that is still recovering. Nothing is stated here because
+ *   nothing should be: one D1 vocabulary, in core, or the two drift.
+ *
+ * Everything absent is terminal. That is the whole point of the record: a code is retried because someone
+ * wrote down what a second attempt would see, not because nobody classified it.
+ */
+export const secretsWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "secrets",
+  retryable: {
+    "core/upstream_failed": "The Cloudflare API could not be reached; the rotation write-back may reach it next time.",
+    "core/upstream_timeout": "The Cloudflare API ran out of time; the write-back is idempotent on the key set.",
+  },
+};

package/src/manager/rotationWorkflow.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createDatabase } from "@pithy-sh/core/src/data/db";
+import { secretsTables } from "../data/tables";
+import { resolveEncryptionConfig, type SecretsStoreEnv } from "../env/bindings";
+import { type AtRestRotationResult, runAtRestKeyRotation, type StepRunner } from "../rotation/atRestKeyRotation";
+import { RotationTracker } from "../store/rotationTracker";
+import type { ConfigWriter } from "./configWriter";
+
+/**
+ * The at-rest key-rotation Workflow's body: build the store, config, and tracker from the worker
+ * env and run the rotation core in durable steps. The `configWriter` is injected so this is testable
+ * against Miniflare with a stub (the only thing that needs a live CF Secrets Store is the write-back
+ * itself); the deployed worker passes the real `SecretsStoreConfigWriter`.
+ */
+export async function runRotationWorkflow(
+  env: SecretsStoreEnv,
+  configWriter: ConfigWriter,
+  step: StepRunner,
+): Promise<AtRestRotationResult> {
+  const config = await resolveEncryptionConfig(env);
+  const db = createDatabase(env.SECRETS, secretsTables);
+  const tracker = RotationTracker.fromD1(env.SECRETS);
+  return runAtRestKeyRotation({ db, config, configWriter, tracker }, step);
+}

package/src/manager/secretsConfigWriter.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareSecretsStoreManager } from "@pithy-sh/cloudflare/src/secrets/secretsStoreManager";
+import { fromZodError } from "@pithy-sh/core/src/error/pithyError";
+import { masterKeySecretName } from "../provision/provisionSecrets";
+import { ManagedEnvironment } from "../scope";
+import type { ConfigWriter } from "./configWriter";
+
+/**
+ * The real {@link ConfigWriter}: writes the master-key config back to CF Secrets Store over REST
+ * during at-rest rotation (the binding itself is read-only). `putSecret` updates the entry in place,
+ * so a failed write leaves the prior config bound and decryptable — losing this config would make
+ * every stored secret undecryptable. This is the one write to CF Secrets Store that cannot run
+ * locally, so it is exercised by the integration suite, not the local one.
+ *
+ * `secretName` has no default on purpose: there is no safe unscoped entry name to fall back to, and a
+ * default here would be a silent write to somebody else's key entry.
+ */
+export class SecretsStoreConfigWriter implements ConfigWriter {
+  readonly #manager: CloudflareSecretsStoreManager;
+  readonly #secretName: string;
+
+  constructor(manager: CloudflareSecretsStoreManager, secretName: string) {
+    this.#manager = manager;
+    this.#secretName = secretName;
+  }
+
+  async write(value: string): Promise<void> {
+    await this.#manager.putSecret(this.#secretName, value);
+  }
+}
+
+/**
+ * Build the at-rest rotation's config writer, targeting the **project- and env-scoped** master-key
+ * entry the manager actually binds (`<project>-<env>-secrets-encryption-keys`) — never a bare default.
+ * Both segments come from wrangler vars stamped at provision (`PROJECT`, `ENVIRONMENT`); they are
+ * external config, so the environment is validated here via `ManagedEnvironment.parse` and the project
+ * by the naming facade `masterKeySecretName` composes through (which refuses an empty or illegal one).
+ *
+ * Getting either wrong is not a failed write — it is a successful write to the wrong entry. The
+ * rotation would re-encrypt every row under a fresh key, persist that key where nothing binds it, and
+ * leave the old key bound: every secret in the store becomes undecryptable, silently, at the next read.
+ * With an unscoped name in a shared account it would be worse still — a rotation would land on another
+ * project's key entry and take their store down too.
+ */
+export function rotationConfigWriter(
+  manager: CloudflareSecretsStoreManager,
+  project: string,
+  environment: string,
+): SecretsStoreConfigWriter {
+  const parsed = ManagedEnvironment.safeParse(environment);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The secrets manager's ENVIRONMENT var is not a managed environment.",
+      action: "Redeploy the manager with `pithy secrets provision`, which stamps it.",
+      detail: `rotation write-back: ENVIRONMENT=${environment}`,
+    });
+  }
+  return new SecretsStoreConfigWriter(manager, masterKeySecretName(project, parsed.data));
+}