@pithy-sh/secrets 0.1.0

package/src/rotation/rotationLedger.ts

@@ -0,0 +1,167 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { ManagedEnvironment } from "../scope";
+import type { SecretRotationOutcome } from "./rotateValue";
+
+/**
+ * **Where a rotation is recorded — stated once, so a third caller inherits it.**
+ *
+ * `#379` is what happens when it is not. `runWriteSecret` seeded a rotation row only on a *first* write,
+ * a rotation dispatches `mode: "update"`, and so a `pithy secrets rotate` that fully succeeded left
+ * `lastRotatedAt` untouched and the secret reporting **overdue forever** — while a rotation from the
+ * control-plane route recorded correctly. Two paths to one act, disagreeing about whether the act
+ * happened, and an operator rotating on the command line during an incident told by the product that they
+ * did not.
+ *
+ * The fix is not a second recorder beside the first. It is that {@link RotationLedger} is an argument to
+ * `rotateSecretValue`, and **required**: the one function that performs a rotation is the one that records
+ * it, and a caller that would rather not cannot express that.
+ *
+ * ## Two implementations, because there are two kinds of caller and only one of them holds the database
+ *
+ * The ledger is `pithy_secrets_rotations`, in the **per-environment secrets D1**. A Worker holds one
+ * directly (`trackerRotationLedger`, over `RotationTracker`). The CLI holds none — the master key is
+ * worker-only and every value-touching command is a dispatch to that environment's manager Workflow — so
+ * it records the same way it writes (`dispatchedRotationLedger`, in `../cli/rotationLedger.ts`). Same
+ * rows, same columns, same sentence on a failure, because both close through {@link rotationClosure}.
+ *
+ * ## Opened before the roll, closed after it
+ *
+ * A rotator that never returns still leaves a trace: an `in_progress` row naming the secret and who asked.
+ * That is the difference between an incident review that can see the attempt and one that reads a gap.
+ * It is opened only after every refusal, so a rotation that never started writes no history at all.
+ *
+ * ## A first write is not a rotation, and the ledger says which it was
+ *
+ * `RotationTracker.recordBaseline` still writes the `baseline` row a brand-new secret gets, and it stays
+ * exactly where it is — on the *create* branch of `runWriteSecret`. A first write and a rotation are
+ * different events: one establishes a value, the other replaces one. Conflating them to make a count come
+ * out would mean `pithy secrets update` — a typo fix, a value pasted from a console — silently advancing
+ * a freshness clock nobody rotated. So the writer never infers, the rotator declares, and the row's
+ * `trigger` column (`baseline` / `manual` / `cron`) is what tells a reader which of the two it is reading.
+ */
+
+/**
+ * Why a rotation row closed `failed`, as a code rather than as free text.
+ *
+ * **Free text is what a value gets pasted into.** `admin/status.ts` refuses to publish `error_message`
+ * for exactly that reason, and the CLI's closure crosses a process boundary before it reaches the column
+ * — so what crosses is one of these three, and the sentence is composed inside the Worker by
+ * {@link rotationFailureText}. There is no shape of close request that could carry a credential.
+ */
+export const RotationFailureReason = z
+  .enum(["roll-failed", "not-recorded", "not-rotated"])
+  .describe(
+    "Why a rotation row closed failed. `roll-failed` — the rotator never answered, so whether the issuer rolled is unknown. `not-recorded` — the issuer rolled and this environment's store did not take the value, which is the incident that needs a human now. `not-rotated` — nothing was rolled and nothing was written, so the previous value is still live.",
+  );
+export type RotationFailureReason = z.output<typeof RotationFailureReason>;
+
+/**
+ * How one rotation row closes, in one environment.
+ *
+ * The two members of `RotationStatus` a finished attempt can hold — `in_progress` is what the row already
+ * says, and closing to it would be closing nothing. A discriminated union rather than an optional reason
+ * so a `failed` closure cannot be constructed without one.
+ */
+export const RotationClosure = z
+  .discriminatedUnion("status", [
+    z
+      .object({
+        status: z
+          .literal("success")
+          .describe("The new value reached this environment's store, so the row closes success."),
+      })
+      .describe("A rotation that landed here."),
+    z
+      .object({
+        status: z.literal("failed").describe("The new value never reached this environment's store."),
+        reason: RotationFailureReason.describe("Which failure it was, as a code the Worker renders."),
+      })
+      .describe("A rotation that did not land here, and why."),
+  ])
+  .describe("How one rotation row closes in one environment: success, or failed with a reason.");
+export type RotationClosure = z.output<typeof RotationClosure>;
+
+/**
+ * Every code that may close a rotation row `failed` — the domain of the column's fixed text.
+ *
+ * **A superset of {@link RotationFailureReason}, and the two are not the same question.** A *reason* is
+ * how a value rotation's closure ended, and it crosses a process boundary as data, so it is a Zod enum
+ * parsed on arrival. A *code* is what `RotationTracker.markFailure` accepts, and the whole-store at-rest
+ * key rotation closes rows too — under `AT_REST_ROTATION_NAME`, from inside a Worker, never over a wire.
+ * Widening the wire enum to admit a code no closure can produce would let a caller name a rotation it
+ * cannot perform; keeping the code a TypeScript union keeps that impossible and still makes every reason
+ * a code by construction.
+ *
+ * The set is closed on purpose. `#386` is what an open one costs: the at-rest path composed `cause.message`
+ * into this column, and the exceptions reaching that catch come from decryption, envelope decoding and
+ * config parsing — the paths whose message text can carry key material.
+ */
+export type RotationFailureCode = RotationFailureReason | "at-rest-incomplete";
+
+/** The sentence written into a failed row's `error_message`. Fixed text, chosen by a code, never composed from an exception. */
+const FAILURE_TEXT: Record<RotationFailureCode, string> = {
+  "roll-failed": "the rotator did not answer, so nothing was recorded here",
+  "not-recorded": "rolled at the issuer, and not recorded here",
+  "not-rotated": "not rotated: nothing was rolled and nothing was written",
+  "at-rest-incomplete": "the at-rest key rotation did not finish",
+};
+
+/**
+ * The failure sentence for a code.
+ *
+ * It names no environment, because it does not have to: the row lives in that environment's own D1, so
+ * *here* is unambiguous and a name copied into the text is a name that can be wrong.
+ *
+ * It names no cause either, and that is the harder half. `at-rest-incomplete` covers a write-back that
+ * failed, a config that would not parse and a batch that would not decrypt, and it says none of them —
+ * the throw still carries that, in a `PithyError`'s `detail`, which the HTTP codec strips. What a caller
+ * wants here is one sentence a row can hold; what it must not be able to write is the exception's own.
+ */
+export function rotationFailureText(code: RotationFailureCode): string {
+  // **The fallback is not dead code, and it is the half a type cannot do.** `markFailure`'s parameter is
+  // the gate, and a gate in the type system is absent at runtime: a JavaScript consumer, a cast, or a code
+  // some future revision parses off a wire all reach here holding something that is not a member. Such a
+  // caller gets a fixed sentence too. What no caller gets is the string it arrived with — which is the
+  // whole invariant, and the reason it is stated here rather than trusted to the signature alone.
+  return FAILURE_TEXT[code] ?? "the rotation failed";
+}
+
+/**
+ * How the row in `environment` closes, given what the whole run did.
+ *
+ * **Per environment, and that is the point.** A fan-out that reached staging and stranded prod is a
+ * success in one ledger and an incident in the other, and one verdict written to both would either
+ * advance a freshness clock over a dead credential or report a landed value as lost. `recorded` is the
+ * list of environments the value actually reached, grown as each write landed, so it is the only thing
+ * here that can answer the question.
+ */
+export function rotationClosure(outcome: SecretRotationOutcome, environment: ManagedEnvironment): RotationClosure {
+  if (outcome.recorded.includes(environment)) return { status: "success" };
+  if (outcome.rollFailed === true) return { status: "failed", reason: "roll-failed" };
+  if (outcome.rolled) return { status: "failed", reason: "not-recorded" };
+  return { status: "failed", reason: "not-rotated" };
+}
+
+/** A rotation row that has been opened and is waiting to be closed. */
+export interface OpenRotation {
+  /**
+   * Close what was opened, with what the run actually did. Called once, on every path below the open —
+   * including the failing ones, which are the paths whose record matters most.
+   */
+  close(outcome: SecretRotationOutcome): Promise<void>;
+}
+
+/**
+ * The rotation ledger, from the two sides that can reach one.
+ *
+ * `open` takes the secret's name and nothing else: *who* asked and *what triggered it* belong to the
+ * implementation, which is the thing that knows — a Worker has a verified control-plane subject, the CLI
+ * has a command. Passing them per call would let one caller record a rotation as somebody else.
+ */
+export interface RotationLedger {
+  /** Open an `in_progress` row for `name`, before anything is rolled. */
+  open(name: string): Promise<OpenRotation>;
+}

package/src/rotation/valueRotator.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SecretRegistryEntry } from "../registry";
+import type { ManagedEnvironment } from "../scope";
+
+/**
+ * **The value-rotation seam, live since #367.** It was declared inert by #322 — "no concrete provider
+ * ships yet, and nothing in the package calls it" — because the tag was landing ahead of the act. The tag
+ * is `rotation.kind: "provider"`: *replaced by calling the issuer, which returns the new value.* This is
+ * the code behind that tag, and `pithy secrets rotate` is what calls it.
+ *
+ * A function cannot cross into `pithy.manifest.json`, so the declaration and the implementation are two
+ * things by construction: the manifest carries `rotation`, which any client branches on, and the registry
+ * carries this, which only the process performing a rotation ever holds. `defineSecretRegistry` refuses a
+ * pair that disagrees — see `SecretRegistryEntryBase.rotator`.
+ *
+ * ## The one rule this interface exists to state
+ *
+ * **`roll` mutates somebody else's system, so it runs exactly once and is never retried.** Everything
+ * downstream — storing the value, recording the rotation — retries against what this returned. Rolling
+ * again does not repair a failed store; it issues a *third* credential and loses the second, which is the
+ * failure the retry was meant to prevent, arriving by way of the retry. `rotateSecretValue` is where that
+ * ordering is enforced, and it is enforced there rather than trusted here.
+ *
+ * ## Retiring the old credential is not here, deliberately
+ *
+ * #322's first draft hung a `cleanup` off this to deactivate the previous credential once its overlap had
+ * elapsed. It is gone: retirement runs on its own clock, long after the rotation, and the overlap window
+ * exists precisely so that things issued under the old value keep working. A method called at rotation
+ * time that ends the overlap early is data loss wearing a tidy name. `ROTATION_SWEEP` is the kit's existing
+ * shape for a scheduled retirement, and that is where it belongs when it lands.
+ */
+
+/** What a rotator is told about the secret it is replacing. */
+export interface ValueRotationContext {
+  /** The registry name of the secret being rotated. */
+  name: string;
+  /** The environment whose value is being replaced. A rotator holding per-environment credentials needs it. */
+  env: ManagedEnvironment;
+  /** The registry entry, for a rotator that reads its own declaration rather than restating it. */
+  entry: SecretRegistryEntry;
+  /**
+   * The value being replaced, **when the caller can read it** — and the CLI cannot.
+   *
+   * Optional, and the optionality is a fact about the architecture rather than a convenience. A `d1`
+   * secret is sealed under a master key that never leaves its environment's manager Worker; the CLI's only
+   * read seam (`SecretProbe`) resolves to a bit, and "there is no shape of request that would make it"
+   * return a value. So `pithy secrets rotate` calls a rotator with this absent, always.
+   *
+   * A rotator whose provider authenticates with the credential being replaced — GitLab's token rotation is
+   * the case — therefore cannot be driven from the CLI, and must say so plainly rather than fail obscurely.
+   * It has its own credentials, or it refuses.
+   */
+  currentValue?: string;
+}
+
+/** What a rotator gives back. The successor value, and nothing else — there is nothing else to carry. */
+export interface ValueRotationResult {
+  /** The freshly-issued value. Stored, never returned to a caller, never printed, never logged. */
+  newValue: string;
+}
+
+/**
+ * A per-secret value rotator. Supplied on the registry entry by whoever owns the secret — the capability
+ * that declares it, or the adopter who declared their own.
+ */
+export interface ValueRotator {
+  /**
+   * Roll the credential at its issuer and return the successor.
+   *
+   * **Called at most once per rotation, and never speculatively.** By the time this returns, the previous
+   * value may already be dead at the provider and this value may be the only copy in existence.
+   */
+  roll(context: ValueRotationContext): Promise<ValueRotationResult>;
+}

package/src/scope.ts

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type DeclaredEnvironments, isValidEnvironment } from "@pithy-sh/core/src/naming/environment";
+import { z } from "zod";
+import type { SecretBackend, SecretScope } from "./registry";
+
+/**
+ * The environments Pithy manages remotely — **every environment the project declares, and no other**.
+ *
+ * ## Declared and managed are one set. The decision, and the argument for it.
+ *
+ * This was a closed enum, `["staging", "prod"]`, pinned against core's `ENVIRONMENTS` by a test. That made
+ * the type system say a custom environment could not be managed while the rest of the CLI cheerfully
+ * accepted one: `pithy migrate --env live` ran, `<project>-live-db` would have been created, and
+ * `pithy secrets provision` — iterating the enum — gave `live` no master key, no manager, and no store
+ * entry, silently, until the first request. The gap was not that the enum held the wrong two names. It was
+ * that a project had no way to say which environments it had, so three parts of the CLI guessed
+ * differently.
+ *
+ * Now the project says, in the root `pithy.config.ts` (core's `DeclaredEnvironments`), and this reads it.
+ *
+ * **Managed could have stayed narrower than declared, and deliberately does not.** The cost of widening is
+ * real and is worth naming: everything that iterates this set multiplies with it, and the largest item is
+ * a manager Worker deployed per environment, each with its own rotation cron and its own D1. A project
+ * declaring five environments gets five managers. The tempting alternative is a second, smaller list —
+ * "declared, but only these are managed" — so the common project pays for two.
+ *
+ * That alternative is the bug, restated. An environment that is deployed and *not* managed is an
+ * environment whose secrets have no master key: exactly the silent state `live` was already in, except now
+ * with a config field that made it look intentional. There is no useful meaning for "this project deploys
+ * to `live` but `live` gets no secrets" — the Worker still starts, still reads `SECRETS_ENCRYPTION_KEYS`,
+ * and still fails at the first request. So the second list would only ever be a way to reintroduce the
+ * silence with paperwork.
+ *
+ * The cost is therefore charged where it belongs: **declaring an environment is what costs a manager.** A
+ * project that does not want five managers declares fewer environments, which is also true of five D1
+ * databases, five KV namespaces, and five sets of resource names. The declaration is the one place that
+ * decision is made and the one place `pithy doctor` can see it.
+ *
+ * **`dev` is still never here**, and does not need excluding: it is local-only — resolved from the
+ * project's own Miniflare-backed store, seeded from the dev secrets file — and core refuses to let a
+ * declaration name it at all.
+ */
+export const ManagedEnvironment = z
+  .string()
+  .refine((value) => isValidEnvironment(value) && value !== "dev", {
+    error:
+      "A deployed environment is a legal environment name that is not `dev`. Declare it in the root pithy.config.ts.",
+  })
+  .describe("A deployed environment with its own secrets store and manager (everything except local dev).");
+
+/**
+ * One deployed environment. **A validated `string`, not a union of two literals** — the union was the bug
+ * this module's header describes, and a type cannot know a name the project writes down at `init`.
+ */
+export type ManagedEnvironment = z.output<typeof ManagedEnvironment>;
+
+/**
+ * Every managed environment, in order — the set a `global` D1 secret fans out across, and the order
+ * provisioning walks. It is the declaration, unchanged: see the header for why nothing narrows it.
+ *
+ * The declaration is a **required** argument rather than one defaulted to `["staging", "prod"]`, because a
+ * default here is indistinguishable from the silence this replaced — a caller that forgot to load the
+ * project would skip `live` exactly as the closed enum did, and nothing would say so. Required, the
+ * compiler names every call site instead.
+ */
+export function managedEnvironments(declared: DeclaredEnvironments | readonly string[]): ManagedEnvironment[] {
+  return [...declared];
+}
+
+/**
+ * The environment a `global` CF-Secrets-Store secret is canonically written through — **the last declared
+ * one**.
+ *
+ * A Secrets Store entry is a single account-level secret that every environment binds, so it is written
+ * once rather than per environment, and *which* manager does the writing has to be a stable function of
+ * the project rather than of whichever environment the operator happened to type. It used to be the
+ * literal `prod`, which is right for a project that has one and writes through a manager that was never
+ * deployed for a project that does not.
+ *
+ * Last, because the declaration is ordered least-production first: the canonical writer is the most
+ * production-class environment, which is the one that certainly exists and the one whose credentials are
+ * scoped hardest. `["staging", "prod"]` gives `prod`, so nothing about the default project changes.
+ */
+export function canonicalGlobalEnvironment(
+  declared: DeclaredEnvironments | readonly string[],
+): ManagedEnvironment | undefined {
+  return declared[declared.length - 1];
+}
+
+/**
+ * The environments a write must reach, given its backend and scope — the routing the CLI applies
+ * before dispatching to each env's manager (issue #26's backend × scope table):
+ *
+ *   - `environment` scope → exactly the requested env (its value legitimately differs per env).
+ *   - `global` + `d1` → **every** declared env: each env's store is separate and keyed by its own
+ *     master key, so the same value is written into each (fan-out, kept in lockstep).
+ *   - `global` + `cf-secrets-store` → **the canonical env only**: a CF Secrets Store entry is one
+ *     account-level secret every env binds, so it is written once, via
+ *     {@link canonicalGlobalEnvironment}.
+ *
+ * A `global` write therefore reaches every environment by construction; an `environment` write touches
+ * exactly one.
+ */
+export function resolveWriteTargets(
+  backend: SecretBackend,
+  scope: SecretScope,
+  requested: ManagedEnvironment,
+  declared: DeclaredEnvironments | readonly string[],
+): ManagedEnvironment[] {
+  if (scope === "environment") return [requested];
+  if (backend === "cf-secrets-store") {
+    const canonical = canonicalGlobalEnvironment(declared);
+    // A declaration is never empty — core refuses that — so this only guards the caller who passed a
+    // list core never validated. Falling back to the requested env writes the secret somewhere real.
+    return [canonical ?? requested];
+  }
+  return managedEnvironments(declared);
+}