@pithy-sh/secrets 0.1.0

package/src/http/guards.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * The scopes the secrets capability's management surface demands, and the surface it advertises.
+ *
+ * ## Two scopes, and each is its own
+ *
+ * `secrets:status:read` is granted separately from everything else an adopter grants at connect. That
+ * separation is the point: the read is harmless in the sense that matters — it cannot disclose a value —
+ * and it is sensitive in a different sense, because the list of which credentials a project holds, which
+ * are stale, and which no automation will ever rotate is a map of where to push. An adopter who wants a
+ * dashboard reading purchases and users without also handing over that map says so by not granting this,
+ * and then it *cannot* be read, whatever the client intends.
+ *
+ * `scopeCovers` matches exactly, with no prefix or wildcard rule, so this confers nothing else and
+ * nothing else confers it.
+ *
+ * ## Why the history is not a second scope
+ *
+ * `@pithy-sh/ledger` splits balances from the entry log behind them, because a number and a behavioral
+ * record are different disclosures. Here they are the same disclosure at two resolutions: the listing
+ * already reports the last successful rotation and the count, and the history adds the attempts between
+ * them. Nothing appears in one that the other conceals, so a second grant would be a decision an adopter
+ * could not act on.
+ *
+ * ## The gate is core's, and this capability verifies nothing itself
+ *
+ * `requireControlPlane` lives in `@pithy-sh/core/src/controlPlane/http/guard` and the routes wear it
+ * directly. `@pithy-sh/core` is a hard dependency of every capability, so importing its gate cannot
+ * leave a deployment without one — and with the seam uncomposed it raises `controlplane/not_connected`
+ * rather than passing. There is no `requireAuth()` anywhere on this surface: the seam leaves
+ * `c.var.auth` null by design, so an auth gate would deny every legitimate management call permanently.
+ *
+ * The name is a constant rather than config, because a configurable scope name is a way to misconfigure
+ * a default-denied gate into a differently-named one — and it is the join key with what
+ * `pithy dashboard connect` offers an adopter to grant.
+ */
+
+/** Read every declared secret's status, and one secret's rotation history. Metadata only, never a value. */
+export const SECRETS_STATUS_READ_SCOPE: ControlPlaneScope = "secrets:status:read";
+
+/**
+ * **Replace one declared secret's value.** The capability's first write scope, and it is separate from the
+ * read for a stronger reason than symmetry.
+ *
+ * `scopeCovers` matches exactly, so a scope confers every route that requires it and nothing else. Folding
+ * a rotation behind `secrets:status:read` would mean every adopter who ever granted a dashboard the ability
+ * to see that a key is stale had also, retroactively and without being asked, granted it the ability to
+ * replace their production credentials. That is the escalation the whole scope model exists to make
+ * impossible, and a name ending in `:read` gating a write is how it would have happened quietly.
+ *
+ * **It is deliberately not in the default grant, and nothing here has to arrange that.** `defaultGrant`
+ * classifies a scope by the methods of the routes requiring it — every route requiring this one is a
+ * `POST`, so a fresh `pithy dashboard connect` does not hand it out and an adopter has to name it. That is
+ * the correct default for a credential that reaches other people's live systems: an adopter who wants a
+ * dashboard to rotate for them says so once, out loud, and can stop saying it at any time by revoking.
+ */
+export const SECRETS_ROTATE_SCOPE: ControlPlaneScope = "secrets:rotate";
+
+/**
+ * Every control-plane scope this capability defines — what `pithy dashboard connect` offers for it, and
+ * the list a manifest or a doc quotes rather than re-typing.
+ */
+export const SECRETS_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  SECRETS_STATUS_READ_SCOPE,
+  SECRETS_ROTATE_SCOPE,
+];
+
+/**
+ * The secrets capability's management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scope rather than in `routes.ts` so the scope a route demands and the scope a
+ * manifest advertises are the same constant, read from one place. `basePath` is a parameter and never a
+ * default: an adopter who mounted this at `/vault` must get a manifest naming `/vault/admin/status`, or
+ * a management client composing its calls from it would 404 against exactly the adopters who customized
+ * anything.
+ *
+ * Everything sits under `admin/` for consistency with every other capability's management surface, and
+ * so that a future non-management route under this mount point cannot collide with one of these.
+ */
+export function secretsAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/admin/status`,
+      scope: SECRETS_STATUS_READ_SCOPE,
+      summary: "Every declared secret's status: when it was last rotated, how often, and whether it is overdue.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/status/:name/rotations`,
+      scope: SECRETS_STATUS_READ_SCOPE,
+      summary: "One secret's rotation history, newest first — when, how it ended, what caused it, and who.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/status/:name/rotate`,
+      scope: SECRETS_ROTATE_SCOPE,
+      summary:
+        "Replace one declared secret in this environment, against its declared rotator. Reports per environment, never in aggregate.",
+    },
+  ];
+}

package/src/http/responses.ts

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SecretRotation } from "@pithy-sh/core/src/capability/secretOrigin";
+import { z } from "zod";
+import { RotationStatus, RotationTrigger } from "../data/secretRotations";
+import { SecretBackend, SecretValueType } from "../registry";
+import { SecretRotationStatus, SecretRotationUnchangedReason } from "../rotation/rotateValue";
+import type { CarriesNoValue } from "../valueBearing";
+
+/**
+ * What the secrets management routes return, as Zod objects a client can validate against.
+ *
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves are
+ * runtime values rather than interfaces because a management client reading a customer's Worker is
+ * crossing a trust boundary and must validate what comes back — and a TypeScript interface is erased
+ * before it can help, so every client that had only an interface hand-wrote a mirror and the mirror
+ * drifted the first time a field landed here.
+ *
+ * **No codecs and no transforms.** These describe JSON on the wire, so parsing one hands back exactly
+ * what went in. Dates render as ISO-8601 strings: they are ms-epoch integers in SQLite and `Date`s in
+ * TypeScript, and a JSON number would leave every client guessing the unit.
+ *
+ * **One deliberate exception, and it is a rewrite rather than a decode: `rotation.issuer`.** `SecretRotation`
+ * comes from core with `SecretIssuer.catch("other")` on its issuer field, so a client parsing a response
+ * from a Worker running a *newer* kit than itself renders `other` instead of throwing. That is the right
+ * failure here for the same reason it is right on the manifest — this is third-party data from somebody
+ * else's deployment, and a pane blanked over an issuer name a client did not need to understand is worse
+ * than an honest *somebody issues this, and I cannot help you with them.* It rewrites a field, never a key,
+ * so nothing merges and nothing is lost; see `secretOrigin.ts`'s `IssuerKey` for why that distinction is
+ * load-bearing.
+ *
+ * **Nothing here can carry a value.** The field lists are the same argument `admin/status.ts` makes
+ * about its reader shapes, restated at the wire, and {@link SECRET_RESPONSES_CARRY_NO_VALUE} is the
+ * compile-time tripwire that keeps it true. A ciphertext, an IV, a metadata snapshot and a rotation's
+ * error message are all absent from the type rather than omitted by a projection.
+ *
+ * **A browser imports this file, so it reaches no module that needs the Workers runtime** — which is
+ * why `CarriesNoValue` comes from `../valueBearing.ts` and not from `admin/status.ts`, where it was
+ * declared until #419. The reader is a Kysely module; importing a *type* out of it still put the D1
+ * layer in the browser program's file set, and `@pithy-sh/support` shipped the version of that mistake
+ * where the reached module named a bare Workers global and the adopter's client build went red.
+ * `tooling/browser-scopes` compiles this module with `types: []` and asks the compiler which files that
+ * program included.
+ *
+ * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
+ * version boundary — a management client validates a response with this schema against a customer's
+ * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
+ * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
+ * say*, which is a different fact from `null`.
+ */
+
+/** One rotation attempt on the wire. */
+export const SecretRotationView = z
+  .object({
+    startedAt: z.iso.datetime().describe("When the rotation attempt began, ISO-8601."),
+    completedAt: z.iso.datetime().nullable().describe("When it finished, ISO-8601; null while it is still running."),
+    status: RotationStatus.describe("How it ended: `in_progress`, `success`, or `failed`."),
+    trigger: RotationTrigger.describe("What caused it: `cron`, `manual`, or the `baseline` marker on first write."),
+    rotatedBy: z.string().describe("Who or what initiated it — a workflow instance id, an operator id, or `baseline`."),
+  })
+  .describe("One rotation attempt as a client reads it. A failure is a status, never a message.");
+export type SecretRotationView = z.output<typeof SecretRotationView>;
+
+/** One secret's status on the wire. */
+export const SecretStatusView = z
+  .object({
+    name: z.string().describe("The secret's registry name."),
+    backend: SecretBackend.describe("Where the value lives. Decides what a null `createdAt` means."),
+    valueType: SecretValueType.describe("How the value is interpreted: `text` or `json`."),
+    rotatable: z.boolean().describe("Whether a value-rotator may manage it. Never changes what is reported."),
+    rotation: SecretRotation.nullable().describe(
+      "How this secret is replaced: `local`, `provider`, or `manual` — with the issuer, and the page a human goes to. Null when the registry declares nothing, which is not the same as `manual`. **This is the field a client branches on to decide whether a rotation control exists at all**, and it is metadata by construction: a kind, an issuer and an `https:` documentation URL are all it can hold. An issuer this client has never heard of parses as `other` rather than failing, so a Worker newer than its reader still renders.",
+    ),
+    keyVersion: z
+      .number()
+      .int()
+      .nullable()
+      .describe("Which master-key version the stored envelope sits under, or null when nothing is stored here."),
+    createdAt: z.iso
+      .datetime()
+      .nullable()
+      .describe("When it was first written to this store, ISO-8601; null when it is not stored here."),
+    updatedAt: z.iso
+      .datetime()
+      .nullable()
+      .describe("When its value was last written, ISO-8601; null when it is not stored here."),
+    lastRotatedAt: z.iso
+      .datetime()
+      .nullable()
+      .describe(
+        "The newest successful rotation, ISO-8601, or **null for never rotated** — not zero, and not the epoch.",
+      ),
+    rotationCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("How many rotation attempts are recorded, successful or not."),
+    rotateEveryDays: z
+      .number()
+      .int()
+      .positive()
+      .nullable()
+      .describe("The cadence the registry declares for this secret, or null when it declares none."),
+    overdue: z
+      .boolean()
+      .nullable()
+      .describe("Whether it is past that cadence. Null when the question has no answer, which is not the same as no."),
+  })
+  .describe("One secret's status as a client reads it. Metadata only — this shape cannot express a value.");
+export type SecretStatusView = z.output<typeof SecretStatusView>;
+
+/** `GET {base}/admin/status` — every declared secret. */
+export const SecretsStatusResponse = z
+  .object({
+    secrets: z
+      .array(SecretStatusView)
+      .describe("Every named secret the composed Worker declares, by name. Keyed entries are excluded."),
+    unreadable: z
+      .array(z.string())
+      .describe(
+        "Declared secrets whose stored rows would not decode, by registry name — so one bad row costs its own entry and names itself, instead of costing the read (#387). Registry names only: keyed entries are excluded from this read, so no stored `<keyspace>/<key>` name can appear here. Carries no reason; why a row is malformed is a question for the database, not for a client.",
+      ),
+  })
+  .describe("The status of every declared secret, and any whose stored rows would not decode.");
+export type SecretsStatusResponse = z.output<typeof SecretsStatusResponse>;
+
+/** `GET {base}/admin/status/:name/rotations` — one secret's history. */
+export const SecretRotationsResponse = z
+  .object({
+    name: z.string().describe("The secret this history belongs to, echoed so a client can label it."),
+    rotations: z.array(SecretRotationView).describe("Its rotation attempts, newest first, capped by `limit`."),
+    unreadable: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        "How many rows in this page would not decode (#387). A count and not a list, because every row here is the same secret's and what identifies one is its place in the history — which is exactly what a row with an undecodable `startedAt` cannot supply. Reported so a client can say the history is incomplete rather than render a short list as a whole one.",
+      ),
+  })
+  .describe("One secret's rotation history, and how much of the page would not decode.");
+export type SecretRotationsResponse = z.output<typeof SecretRotationsResponse>;
+
+/**
+ * `POST {base}/admin/status/:name/rotate` — what one rotation did, **per environment and never in
+ * aggregate**.
+ *
+ * This is `SecretRotationOutcome` projected for the wire, field by field, and the projection is where two
+ * things are dropped on purpose:
+ *
+ * - **`cause`.** The core carries whatever the store threw, typed `unknown`, for the command to render into
+ *   a `detail`. An `unknown` on a response schema is a hole of arbitrary shape pointed at a management
+ *   client, filled by an exception raised at a site that was handling a value. It does not cross.
+ * - **Anything a value could sit in.** There is no such field, which is the same structural argument the
+ *   core makes about its own outcome: a payload with nowhere to put a secret cannot leak one by a later
+ *   caller's oversight. {@link SECRET_RESPONSES_CARRY_NO_VALUE} is the tripwire.
+ *
+ * **It answers 200 for every one of the four statuses, including `unrecorded`**, and that is a decision
+ * rather than an oversight. The alternative — throwing `secrets/rotation_unrecorded` so the incident
+ * arrives as a 500 — renders one sentence and drops `recorded` and `stranded` on the floor, which is
+ * exactly the "all rotated" summary over a partial failure that this whole design refuses. The status is a
+ * required field of a closed enum, so a client that validates its response cannot fail to see it, and the
+ * audit event for that member is `critical`.
+ */
+export const SecretRotationOutcomeView = z
+  .object({
+    name: z.string().describe("The secret that was rotated, echoed so a client can label the result."),
+    status: SecretRotationStatus.describe(
+      "How it ended: `rotated`, `unchanged`, `unrecorded`, or `failed`. `unrecorded` is the one that needs a human in a console now — read it before `recorded`.",
+    ),
+    kind: z
+      .enum(["local", "provider", "manual"])
+      .describe(
+        "How the registry says this secret is replaced — the same fact `rotation.kind` reports on a status read.",
+      ),
+    rolled: z
+      .boolean()
+      .describe(
+        "Whether the issuer's credential was actually replaced. True only for a `provider` rotation that reached its rotator; a `local` mint rolls nothing anywhere.",
+      ),
+    rollFailed: z
+      .boolean()
+      .describe(
+        "Whether the **rotator itself** threw, rather than the store after it. With `rolled`, this is the difference between *was rolled* and *may have been rolled*: a call that reached the issuer and lost its answer cannot be told from one that never landed, and a report claiming either is wrong half the time about the fact being acted on. False on every run that never called a rotator.",
+      ),
+    recorded: z
+      .array(z.string())
+      .describe("The environments this run wrote the new value to, in the order each write landed."),
+    stranded: z
+      .array(z.string())
+      .describe(
+        "The environments the new value never reached. Empty on a run that finished. With `rolled` true these hold a credential the issuer has already retired.",
+      ),
+    reason: SecretRotationUnchangedReason.nullable().describe(
+      "Why nothing was called, when nothing was — `manual` for a secret only a human can replace. Null whenever something was attempted.",
+    ),
+    attempts: z
+      .number()
+      .int()
+      .positive()
+      .nullable()
+      .describe("How many store attempts the failing environment cost. Null when nothing was stored."),
+  })
+  .describe(
+    "What one rotation did, per environment. Facts only, no prose, and no field a value or an exception could sit in.",
+  );
+export type SecretRotationOutcomeView = z.output<typeof SecretRotationOutcomeView>;
+
+/** `POST {base}/admin/status/:name/rotate` — one secret, one outcome. */
+export const SecretRotateResponse = z
+  .object({
+    rotation: SecretRotationOutcomeView.describe(
+      "The outcome. One secret per call, so there is no summary line to hide a partial failure behind.",
+    ),
+  })
+  .describe("One secret's rotation outcome.");
+export type SecretRotateResponse = z.output<typeof SecretRotateResponse>;
+
+/**
+ * The wire half of the constraint. `true` only while no response shape names a value-bearing field; add
+ * one and this assignment stops compiling.
+ */
+export const SECRET_RESPONSES_CARRY_NO_VALUE: CarriesNoValue<SecretStatusView> &
+  CarriesNoValue<SecretRotationView> &
+  CarriesNoValue<SecretRotationOutcomeView> = true;

package/src/http/rotate.ts

@@ -0,0 +1,224 @@
+// 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 { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { Context } from "hono";
+import type { SecretBinding, SecretsStoreEnv } from "../env/bindings";
+import { MASTER_KEY_BINDING } from "../env/bindings";
+import { SecretNotFoundError, SecretRotationUnsupportedError } from "../error/errors";
+import { runWriteSecret } from "../management/writeSecret";
+import type { SecretRegistryEntry } from "../registry";
+import { refuseUnrotatable, rotateSecretValue, type SecretRotationOutcome } from "../rotation/rotateValue";
+import { ManagedEnvironment } from "../scope";
+import { RotationTracker, trackerRotationLedger } from "../store/rotationTracker";
+import { SystemSecretsStore } from "../store/systemSecretsStore";
+
+/**
+ * **What a Worker can rotate, and the honest refusal for everything else.**
+ *
+ * `#367` gave the CLI a rotation and `#372` asks for the same act from a browser, and the two are not the
+ * same act performed by different callers. `pithy secrets rotate` runs in a process holding *the project*:
+ * the registry from source, a Cloudflare API token, and a dispatcher to every environment's manager Worker.
+ * A Worker holds **one environment's D1 and its own master key**. So the interesting question is not how to
+ * call `rotateSecretValue` from a handler — that part is easy — it is which secrets the answer is true for.
+ *
+ * ## The two refusals, and why they are refusals rather than partial successes
+ *
+ * - **A `cf-secrets-store` backend.** The value is one account-level Secrets Store entry, written through
+ *   Cloudflare's REST API with a token the secrets *manager* holds. An app Worker binds that store
+ *   read-only and must never hold that token — `env/bindings.ts` and the capability's token profile both
+ *   say so. There is no write to attempt.
+ * - **`scope: "global"`.** A global secret is *defined* by being byte-identical in every environment;
+ *   `resolveWriteTargets` fans a global `d1` write across all of them for exactly that reason. A Worker
+ *   can reach one. Writing its own and reporting success would leave staging and prod holding different
+ *   values for one name, which is the mixed state `#38` names as the shape to refuse — and, worse, it
+ *   would arrive labeled `rotated`.
+ *
+ * Both are answered with `secrets/rotation_unsupported` **before anything is called**, naming the command
+ * that can. A client renders the free path instead of a dead button, which is the same answer `#38` already
+ * gives for a `manual` secret and for the same reason: an instruction that works beats a control that does
+ * not.
+ *
+ * ## Three more things are refused before the irreversible step
+ *
+ * {@link refuseUnrotatable} is asked first — a keyspace, an undeclared rotation, a `provider` secret with
+ * no rotator, the master key, a `local` secret with no recipe. Then the environment: a Worker that cannot
+ * name which environment it is cannot report where a value landed, and an outcome that cannot name its
+ * environments is the aggregate this design exists to refuse. Then presence: `runWriteSecret` in `update`
+ * mode raises on a name the store does not hold, and discovering that *after* a provider roll would
+ * manufacture the unrecorded incident out of a configuration gap that was knowable for free.
+ *
+ * ## The rotation row is opened before the roll, and closed after it
+ *
+ * Nothing else advances `lastRotatedAt`. A rotation that succeeded and recorded nothing leaves the secret
+ * reported overdue forever, so the button would appear to do nothing — and the history an incident review
+ * reads (`GET {base}/admin/status/:name/rotations`) would have no entry for the act it is reviewing. The row
+ * opens `in_progress` with the **management client's own subject** as `rotatedBy`, which is what makes *who
+ * rolled the production key on the twelfth* a question with an answer. It is opened before the roll so a
+ * rotator that never returns still leaves a trace, and only after every refusal above, so a refused call
+ * writes no history at all.
+ *
+ * The failure text written into the closing row is composed here from the outcome's own status — never from
+ * `cause`. `admin/status.ts` refuses to publish `error_message` precisely because it is free text written at
+ * a failure site, which is where a value gets pasted by accident; writing one from an exception message
+ * would be that accident, arranged in advance.
+ */
+
+/** What one Worker-side rotation needs: this environment's store, and its rotation history. */
+export interface WorkerRotationDeps {
+  store: SystemSecretsStore;
+  tracker: RotationTracker;
+}
+
+/** One Worker-side rotation request, already verified and already looked up. */
+export interface WorkerRotationRequest {
+  /** The secret's registry name, matched exactly against the composed registry by the caller. */
+  name: string;
+  /** Its registry entry — every refusal below is read off this declaration. */
+  entry: SecretRegistryEntry;
+  /** The environment this Worker is, verified. The one environment a write can reach. */
+  environment: ManagedEnvironment;
+  /** Who asked, for the rotation row. The verified control-plane subject, never a claim from a body. */
+  actor: string;
+  /** Store attempts per environment. Defaults to the core's 3. Never a re-roll. */
+  attempts?: number;
+}
+
+/**
+ * The environment this Worker is, from the **verified** control-plane context rather than from a raw
+ * binding.
+ *
+ * `verifyControlPlaneCall` has already refused a credential bound to a different environment than the one
+ * this Worker's `ENVIRONMENT` var names, so by the time a handler reads it the two agree — and reading the
+ * checked value rather than the var means there is no second, unchecked source of the same fact.
+ *
+ * `dev` and an unstamped Worker are both refused. `ManagedEnvironment` excludes `dev` because local dev has
+ * no manager and no deployed store; an unstamped Worker yields the empty string, which is not a legal
+ * environment name. Either way the answer is the same: this deployment cannot say where a value would land,
+ * so it does not roll one.
+ */
+export function workerRotationEnvironment(environment: string): ManagedEnvironment {
+  const parsed = ManagedEnvironment.safeParse(environment);
+  if (!parsed.success) {
+    throw new SecretRotationUnsupportedError({
+      message: "This deployment cannot say which environment it is, so it will not replace a credential.",
+      action:
+        "Stamp ENVIRONMENT on the Worker's vars (pithy provision does), or rotate from a machine that holds the project: pithy secrets rotate <NAME> --env <env>.",
+      detail: `rotate refused: the verified control-plane environment '${environment}' is not a deployed environment`,
+    });
+  }
+  return parsed.data;
+}
+
+/**
+ * Refuse a secret **this Worker** cannot replace, whatever the declaration says about rotating in general.
+ *
+ * Separate from {@link refuseUnrotatable}, deliberately: that one answers *can this secret be rotated at
+ * all*, and its answers are true everywhere. These two are true only of a Worker, and the same secret is
+ * rotatable from the CLI — so the refusal names the command rather than suggesting the declaration is
+ * wrong.
+ */
+export function refuseUnrotatableHere(name: string, entry: SecretRegistryEntry): void {
+  if (entry.backend === "cf-secrets-store") {
+    throw new SecretRotationUnsupportedError({
+      message: `Secret '${name}' lives in Cloudflare's Secrets Store, which no application Worker writes to. Rotate it with pithy secrets rotate ${name}.`,
+      action: `Run pithy secrets rotate ${name} --env <env>. The secrets manager holds the Cloudflare credential this write needs; an application Worker binds that store read-only and must not hold one.`,
+      detail: `rotate refused: '${name}' is backend cf-secrets-store, which is written through the CF REST API and not from this Worker`,
+    });
+  }
+  if (entry.scope === "global") {
+    throw new SecretRotationUnsupportedError({
+      message: `Secret '${name}' is the same in every environment, and this Worker can only write its own. Rotate it with pithy secrets rotate ${name}.`,
+      action: `Run pithy secrets rotate ${name}. It writes every declared environment in one run, which is what keeps a global secret identical everywhere.`,
+      detail: `rotate refused: '${name}' is scope global, and a Worker-side rotation would write one of its environments and strand the rest`,
+    });
+  }
+}
+
+/** The store and the tracker for this request, from the Worker's own bindings. Built per request. */
+export async function workerRotationDeps(c: Context<PithyHonoEnv>): Promise<WorkerRotationDeps> {
+  const bindings = c.env as Record<string, unknown>;
+  const database = bindings.SECRETS as D1Database | undefined;
+  const masterKey = bindings[MASTER_KEY_BINDING] as SecretBinding | string | undefined;
+  if (!database || masterKey === undefined) {
+    throw new InternalError({
+      message: "The secrets store is not configured.",
+      action: `Bind a D1 database named SECRETS and the ${MASTER_KEY_BINDING} secret in wrangler.jsonc.`,
+      detail: `A Worker-side rotation requires the SECRETS D1 binding and ${MASTER_KEY_BINDING}; ${
+        database ? MASTER_KEY_BINDING : "SECRETS"
+      } was absent on env.`,
+    });
+  }
+  const env: SecretsStoreEnv = { SECRETS: database, SECRETS_ENCRYPTION_KEYS: masterKey };
+  return { store: await SystemSecretsStore.fromEnv(env), tracker: RotationTracker.fromD1(database) };
+}
+
+/**
+ * Rotate one secret in this Worker's own environment, and record the attempt.
+ *
+ * Refuse, open the row, produce once, store with retries, close the row, hand back the outcome. It never
+ * throws for a rotation that *happened* and went wrong — that is what the outcome is for, and a throw would
+ * take `recorded` and `stranded` with it. It throws only for the refusals, every one of which lands before
+ * anything is called.
+ */
+export async function runWorkerRotation(
+  deps: WorkerRotationDeps,
+  request: WorkerRotationRequest,
+): Promise<SecretRotationOutcome> {
+  const { name, entry } = request;
+  refuseUnrotatable(name, entry);
+  refuseUnrotatableHere(name, entry);
+
+  // A human in a console, and nothing to call. The core answers this too, and answering it here is what
+  // keeps a rotation row from being opened for an act that never starts: a history of attempts that logs
+  // the ones that were never attempted is a history nobody can read.
+  if (entry.rotation?.kind === "manual") {
+    return {
+      name,
+      kind: "manual",
+      status: "unchanged",
+      rolled: false,
+      recorded: [],
+      stranded: [],
+      reason: "manual",
+    };
+  }
+
+  // Knowable for free, and catastrophic to discover late: `runWriteSecret` in `update` mode raises on a
+  // name the store does not hold, and for a `provider` secret that raise would land *after* the issuer had
+  // rolled — manufacturing the one failure this design is built around out of a configuration gap.
+  if (!(await deps.store.has(name))) {
+    throw new SecretNotFoundError({
+      message: `Secret '${name}' has never been stored in this environment, so there is nothing to replace.`,
+      action: `Create it first: pithy secrets create ${name} --env ${request.environment}.`,
+      detail: `rotate refused: '${name}' has no row in this environment's store`,
+    });
+  }
+
+  // **The bracket is the core's, not this route's (`#379`).** This function opened the row and closed it
+  // by hand, which was right when `rotateSecretValue` recorded nothing. `#379` moved the bracket into the
+  // function that *performs* a rotation — same order, refuse then open then roll then close — and made
+  // the ledger a required option, so the CLI cannot omit it the way it did. Keeping this bracket as well
+  // would write the row twice.
+  return rotateSecretValue({
+    name,
+    entry,
+    targets: [request.environment],
+    ledger: trackerRotationLedger(deps.tracker, {
+      environment: request.environment,
+      trigger: "manual",
+      rotatedBy: request.actor,
+    }),
+    store: ({ value }) =>
+      runWriteSecret(deps, {
+        mode: "update",
+        name,
+        value,
+        valueType: entry.valueType,
+        rotatable: entry.rotatable,
+      }).then(() => undefined),
+    ...(request.attempts === undefined ? {} : { attempts: request.attempts }),
+  });
+}