@pithy-sh/secrets 0.1.0

package/src/manager/worker.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import { CloudflareSecretsStoreManager } from "@pithy-sh/cloudflare/src/secrets/secretsStoreManager";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { resolveEncryptionConfig, type SecretBinding, type SecretsStoreEnv } from "../env/bindings";
+import { isRotationDue } from "../rotation/keyRotation";
+import type { ManagedEnvironment } from "../scope";
+import { configureSharedSecrets, sharedSecretsStore } from "../sharedSecretsStore";
+import { managerRegistry } from "./managerRegistry";
+import { secretsWorkflowRetry } from "./retryPolicy";
+import { runRotationWorkflow } from "./rotationWorkflow";
+import { rotationConfigWriter } from "./secretsConfigWriter";
+import { runWriteWorkflow, type WriteWorkflowPayload, type WriteWorkflowResult } from "./writeWorkflow";
+
+/**
+ * The prebuilt per-environment secrets manager worker. `pithy add secrets` deploys one per managed
+ * environment (`<project>-staging-secrets`, `<project>-prod-secrets`); the user authors no code for it.
+ * It hosts two Workflows and a cron:
+ *
+ *   - `SecretsWriteWorkflow` — the CLI's dispatch target for create/update/remove.
+ *   - `AtRestKeyRotationWorkflow` — re-encrypts the store under a fresh master key.
+ *   - `scheduled()` — fires the rotation Workflow when the configured interval has elapsed.
+ *
+ * The Workflow bodies (`runWriteWorkflow`, `runRotationWorkflow`) are tested against Miniflare; these
+ * classes are the thin durable-execution shells over them. This module imports `cloudflare:workers`,
+ * so it runs only in the Workers runtime (excluded from the node meta-test).
+ */
+
+const DEFAULT_ROTATION_INTERVAL_DAYS = 30;
+
+// This is a standalone worker, not assembled by `createBackend`, so its `compose` hook never runs.
+// Configure the shared per-invocation accessor directly from the manager's own registry, so reads go
+// through the one cached path (a rotation run reads `CLOUDFLARE_API_TOKEN` once) like every other worker.
+configureSharedSecrets({ registry: managerRegistry });
+
+/** The manager worker's env: the secrets D1 + key binding, the rotation Workflow binding, CF creds for the write-back. */
+export interface SecretsManagerEnv extends SecretsStoreEnv {
+  /** The at-rest rotation Workflow binding, triggered by the cron. */
+  AT_REST_ROTATION: { create(): Promise<unknown> };
+  /**
+   * The scoped CF API token for the at-rest config write-back — the only live-CF write. A
+   * `cf-secrets-store` binding read via `sharedSecretsStore(env, managerRegistry).get("CLOUDFLARE_API_TOKEN")`,
+   * a string from `.dev.vars` in local dev. Never a plaintext env var.
+   */
+  CLOUDFLARE_API_TOKEN: SecretBinding | string;
+  CLOUDFLARE_ACCOUNT_ID: string;
+  SECRETS_STORE_ID: string;
+  /**
+   * This manager's environment. The rotation write-back uses it to target the project- and env-scoped
+   * master-key store entry — the same entry the `SECRETS_ENCRYPTION_KEYS` binding reads — so a rotation
+   * persists to the entry the worker actually binds. Filled at provision from `managedEnvironments()`;
+   * still `ManagedEnvironment.parse`d at the read site, since a wrangler var is external config.
+   */
+  ENVIRONMENT: ManagedEnvironment;
+  /**
+   * This manager's project — the other half of the master-key entry name
+   * (`<project>-<env>-secrets-encryption-keys`). Stamped at provision from the root `pithy.config.ts`
+   * `name`. It is here because the account's Secrets Store is flat: the entry name is the only thing
+   * separating this project's key from another project's in the same account, and the rotation has to
+   * reproduce that name inside the Worker to write the new key set back where the binding reads it.
+   */
+  PROJECT: string;
+  /** Rotation cadence in days; defaults to 30. Sourced from the `rotationIntervalDays` config option. */
+  ROTATION_INTERVAL_DAYS?: string;
+}
+
+/**
+ * The management write Workflow — the CLI dispatches create/update/remove here.
+ *
+ * The step runs under {@link secretsWorkflowRetry}, so a refusal the store has already decided
+ * (`create` over a name that exists, `update` of a name that does not) fails the instance on its first
+ * attempt instead of backing off into the same answer. See `retryPolicy.ts` for the whole classification.
+ */
+export class SecretsWriteWorkflow extends WorkflowEntrypoint<SecretsManagerEnv, WriteWorkflowPayload> {
+  override async run(event: WorkflowEvent<WriteWorkflowPayload>, step: WorkflowStep): Promise<WriteWorkflowResult> {
+    const steps = classifiedSteps(step, secretsWorkflowRetry, NonRetryableError);
+    return await steps.do("write-secret", () => runWriteWorkflow(this.env, event.payload));
+  }
+}
+
+/** The at-rest key-rotation Workflow — re-encrypts the store under a fresh master key. */
+export class AtRestKeyRotationWorkflow extends WorkflowEntrypoint<SecretsManagerEnv, unknown> {
+  override async run(_event: WorkflowEvent<unknown>, step: WorkflowStep): Promise<void> {
+    // Build the manager's secret accessor once; read the CF API token at the point of need. Every
+    // place a secret is consumed is a visible `secrets.get(...)` call site (grep-able), never hidden
+    // behind a wrapper.
+    const secrets = await sharedSecretsStore(this.env, managerRegistry);
+    const manager = new CloudflareSecretsStoreManager({
+      accountId: this.env.CLOUDFLARE_ACCOUNT_ID,
+      apiToken: secrets.get("CLOUDFLARE_API_TOKEN"),
+      storeId: this.env.SECRETS_STORE_ID,
+    });
+    // The writer targets the project- and env-scoped master-key entry this worker actually binds
+    // (see rotationConfigWriter), so the rotation persists exactly where it is read — and never into
+    // another project's key entry in the same account-wide Secrets Store.
+    //
+    // Its steps run under the same classification the write does: the CF API being unreachable is worth
+    // another attempt, and ciphertext that will not decrypt under the bound key set is not.
+    await runRotationWorkflow(
+      this.env,
+      rotationConfigWriter(manager, this.env.PROJECT, this.env.ENVIRONMENT),
+      classifiedSteps(step, secretsWorkflowRetry, NonRetryableError),
+    );
+  }
+}
+
+export default {
+  /** Cron entry: trigger the at-rest rotation Workflow only when the interval has elapsed. */
+  async scheduled(_controller: unknown, env: SecretsManagerEnv): Promise<void> {
+    const config = await resolveEncryptionConfig(env);
+    const intervalDays = Number(env.ROTATION_INTERVAL_DAYS ?? DEFAULT_ROTATION_INTERVAL_DAYS);
+    if (isRotationDue(config.lastRotatedAt, intervalDays)) {
+      await env.AT_REST_ROTATION.create();
+    }
+  },
+};

package/src/manager/wrangler.jsonc

@@ -0,0 +1,76 @@
+{
+  // The prebuilt per-environment secrets manager worker. This is a TEMPLATE, not a wrangler
+  // env-stanza file: staging and prod are two genuinely separate workers with distinct
+  // resources, not one logical worker with `[env.*]` overrides. So `pithy add secrets` resolves
+  // this into two complete standalone configs — replacing every name and `<...>` placeholder (the
+  // worker name, SECRETS D1 id and name, Secrets Store id and entry names, both Workflow names) per
+  // environment — and deploys each with its own config (`wrangler deploy --config <resolved>`). No
+  // `--env` name-mangling. The user authors none of it.
+  //
+  // Every literal name below is a placeholder, replaced rather than suffixed. The deployed names carry
+  // the project, and nothing here knows what the project is — see docs/NAMING.md.
+  "name": "pithy-secrets", // resolved → <project>-<env>-secrets
+  "main": "./worker.ts",
+  // The compatibility date every Worker in this repository runs on. Stated once in the repository
+  // root's `compatibility.ts` and copied here because JSONC cannot import it —
+  // `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // No public URL. This manager has no HTTP routes — it is reached only by Workflow dispatch (over the
+  // CF API) and its rotation cron. `workers_dev: false` keeps it off workers.dev so nothing accidentally
+  // exposes it. (The account still needs a registered workers.dev subdomain — Cloudflare requires one to
+  // deploy any Worker that hosts Workflows, regardless of this flag. Provisioning preflights that.)
+  "workers_dev": false,
+
+  // The dedicated per-environment secrets database — distinct from the app DB, durable, shared by
+  // every feature branch in this environment. Resolved to `<project>-<env>-secrets`, the same name the
+  // manager itself deploys under: the worker and its database are one unit.
+  "d1_databases": [{ "binding": "SECRETS", "database_name": "pithy-secrets", "database_id": "<filled-at-provision>" }],
+
+  // Worker-only secrets, both CF Secrets Store bindings read through the secretsStore accessor.
+  // The **binding** names are fixed and never scoped; every `secret_name` below is a placeholder that
+  // resolveManagerConfig replaces with the project-scoped entry provisioning actually wrote —
+  // <project>-<env>-secrets-encryption-keys for the master key, and
+  // <project>-global-secrets-manager-cf-api-token for the scoped CF API token that backs the rotation
+  // write-back. The account has one flat Secrets Store, so the name is the only partition between two
+  // Pithy projects sharing it. The manager reads the token via its registry, never a plaintext env var.
+  "secrets_store_secrets": [
+    {
+      "binding": "SECRETS_ENCRYPTION_KEYS",
+      "store_id": "<filled-at-provision>",
+      "secret_name": "<filled-at-provision>"
+    },
+    {
+      "binding": "CLOUDFLARE_API_TOKEN",
+      "store_id": "<filled-at-provision>",
+      "secret_name": "<filled-at-provision>"
+    }
+  ],
+
+  // The two Workflows this manager hosts. The write Workflow is the CLI's dispatch target — resolved to
+  // <project>-<env>-secrets-write, so two projects' managers in one account are addressable separately
+  // (see secretsWriteWorkflowName). The rotation Workflow, <project>-<env>-secrets-rotate, is triggered
+  // by the cron below. Both names are composed from the **binding**, so these literals never deploy.
+  "workflows": [
+    { "binding": "SECRETS_WRITE", "name": "pithy-secrets-write", "class_name": "SecretsWriteWorkflow" },
+    { "binding": "AT_REST_ROTATION", "name": "pithy-secrets-rotate", "class_name": "AtRestKeyRotationWorkflow" }
+  ],
+
+  // The at-rest key-rotation cron. Fires daily at 03:00 UTC; the worker's scheduled() handler then
+  // checks ROTATION_INTERVAL_DAYS and only triggers a rotation when the interval has actually
+  // elapsed — so the check is cheap and the rotation cadence stays at the configured interval.
+  "triggers": { "crons": ["0 3 * * *"] },
+
+  "vars": {
+    "ROTATION_INTERVAL_DAYS": "30", // exposed as the `rotationIntervalDays` config option (manifest)
+    "CLOUDFLARE_ACCOUNT_ID": "<filled-at-provision>",
+    "SECRETS_STORE_ID": "<filled-at-provision>",
+    // This manager's environment and project. The rotation write-back derives the master-key store
+    // entry name from both (<project>-<env>-secrets-encryption-keys) — the same entry the
+    // SECRETS_ENCRYPTION_KEYS binding reads. Omit either and the rotation re-encrypts every row under
+    // a key it then writes to an entry nobody binds: silent, total data loss at the next cold read.
+    "ENVIRONMENT": "<filled-at-provision>",
+    "PROJECT": "<filled-at-provision>"
+  }
+}

package/src/manager/writeWorkflow.ts

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { currentValue } from "../crypto/versionedValue";
+import { RotationTrigger } from "../data/secretRotations";
+import type { SecretsStoreEnv } from "../env/bindings";
+import { runWriteSecret, WriteSecretOutcome, type WriteSecretParams } from "../management/writeSecret";
+import { RotationClosure, type RotationFailureCode } from "../rotation/rotationLedger";
+import { RotationTracker } from "../store/rotationTracker";
+import { SystemSecretsStore } from "../store/systemSecretsStore";
+
+/**
+ * The write Workflow payload: the write params plus an optional **test-only** `audit` flag. With
+ * `audit`, the workflow re-reads and decrypts the just-written secret and reports only whether it
+ * round-trips — never the value (see {@link runWriteWorkflow}).
+ */
+export type WriteWorkflowPayload =
+  | (WriteSecretParams & {
+      /** Test-only: verify the write decrypts back to the input. Only a boolean is returned, never a value. */
+      audit?: boolean;
+    })
+  | RotationLedgerCommand;
+
+/**
+ * **The rotation ledger, dispatched.** A `pithy secrets rotate` opens a row before it rolls and closes it
+ * after, and `pithy_secrets_rotations` lives in this database — so the two calls arrive here, on the same
+ * Workflow the value itself is written through. `#379`: without them a successful command-line rotation
+ * recorded nothing and the secret reported overdue forever.
+ *
+ * Parsed rather than trusted. The payload crosses the Workflows REST API from another process, which is a
+ * boundary like any other — and `rotationId` addresses a row, so an unvalidated one closes somebody else's.
+ * The closure carries a **code**, never the failure text: free text is where a value gets pasted by
+ * accident, so the sentence is composed further in, by `RotationTracker.markFailure`.
+ */
+export const RotationLedgerCommand = z
+  .discriminatedUnion("mode", [
+    z
+      .object({
+        mode: z.literal("rotation-open").describe("Open an `in_progress` rotation row and return its id."),
+        name: z.string().min(1).describe("The secret being rotated, by registry name."),
+        trigger: RotationTrigger.describe("What caused the rotation. `baseline` is a first write, not a rotation."),
+        rotatedBy: z.string().min(1).describe("Who or what asked, recorded verbatim in the row."),
+      })
+      .describe("Open a rotation row before anything is rolled, so a rotator that never returns leaves a trace."),
+    z
+      .object({
+        mode: z.literal("rotation-close").describe("Close a row this environment's manager previously opened."),
+        rotationId: z.number().int().positive().describe("The row id returned by the matching `rotation-open`."),
+        closure: RotationClosure.describe("How the row closes here: success, or failed with a reason code."),
+      })
+      .describe("Close a rotation row with what the run actually did in this environment."),
+  ])
+  .describe("One rotation-ledger call dispatched to an environment's manager: open a row, or close one.");
+export type RotationLedgerCommand = z.output<typeof RotationLedgerCommand>;
+
+/** Whether a dispatched payload is a ledger call rather than a write. */
+function isRotationLedgerCommand(payload: WriteWorkflowPayload): payload is RotationLedgerCommand {
+  return payload.mode === "rotation-open" || payload.mode === "rotation-close";
+}
+
+/**
+ * Everything one instance of this Workflow can report.
+ *
+ * Wider than {@link WriteSecretOutcome} because the Workflow does more than the write core does: it also
+ * carries the rotation ledger, which writes no secret and reports opening and closing rows. Derived from
+ * the write core's own enum rather than restated, so a member added there cannot go missing here.
+ */
+export const WriteWorkflowOutcome = z
+  .enum([...WriteSecretOutcome.options, "opened", "closed"])
+  .describe(
+    "What one management Workflow instance did: a write outcome, or a rotation row `opened` or `closed`. Never a value.",
+  );
+export type WriteWorkflowOutcome = z.output<typeof WriteWorkflowOutcome>;
+
+/**
+ * The write Workflow's result — its instance output, and the whole of what leaves this worker.
+ *
+ * A Zod object rather than an interface because it is read back **outside** the Worker, off the
+ * Workflows REST API, by a CLI that must validate it like any other external input: a `PithyError`
+ * raised on a shape nobody expected is a run that stops, and a silently-`undefined` `outcome` is a
+ * provisioning gate that passes because it could not read its own subject.
+ */
+export const WriteWorkflowResult = z
+  .object({
+    outcome: WriteWorkflowOutcome.describe("What the instance did — the manager's answer, never a value."),
+    rotationId: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "The rotation row just opened, present only on a `rotation-open`. A surrogate row id in this environment's ledger — it addresses a record and describes nothing about a secret.",
+      ),
+    audited: z
+      .boolean()
+      .optional()
+      .describe(
+        "Test-only: whether the stored secret decrypted back to the dispatched value. The value itself never leaves the worker.",
+      ),
+  })
+  .describe(
+    "One management write Workflow instance's output: what it did, and nothing that could reconstruct a value.",
+  );
+export type WriteWorkflowResult = z.output<typeof WriteWorkflowResult>;
+
+/**
+ * Open or close a rotation row in this environment's ledger.
+ *
+ * The failure sentence is composed by the tracker, from the closure's own code, and never from anything
+ * the caller wrote. `admin/status.ts` refuses to publish `error_message` precisely because it is free text
+ * written at a failure site — accepting one over the wire would be that hazard arranged in advance.
+ *
+ * Since `#386` this path could not do otherwise: `markFailure` takes a {@link RotationFailureCode}, so the
+ * dispatched closure hands over the code it already carries and there is no argument a sentence would fit.
+ */
+async function runRotationLedgerCommand(
+  env: SecretsStoreEnv,
+  command: RotationLedgerCommand,
+): Promise<WriteWorkflowResult> {
+  const tracker = RotationTracker.fromD1(env.SECRETS);
+  if (command.mode === "rotation-open") {
+    const rotationId = await tracker.startRotation(command.name, command.trigger, command.rotatedBy);
+    return { outcome: "opened", rotationId };
+  }
+  if (command.closure.status === "success") await tracker.markSuccess(command.rotationId);
+  else await tracker.markFailure(command.rotationId, command.closure.reason);
+  return { outcome: "closed" };
+}
+
+/**
+ * The management write Workflow's body: build the store + tracker from the worker env and run the
+ * write core. This is what the CLI's dispatch lands on. Decrypting/encrypting happens here because
+ * the master key (resolved by `SystemSecretsStore.fromEnv` from the worker-only binding) never
+ * leaves the worker. Tested against Miniflare with the `SECRETS_ENCRYPTION_KEYS` string binding.
+ *
+ * **Audit (test-only round-trip check).** With `payload.audit` on a create/update, after the write
+ * the workflow opens a *fresh* store (re-resolves the key, re-reads D1), decrypts the secret, and
+ * compares it to the dispatched value — returning only `{ audited: boolean }`. The plaintext is
+ * compared inside the worker and never returned or logged, so the round trip is proven without a
+ * secret ever leaving. This is how the live integration test confirms encrypt → store → decrypt.
+ */
+export async function runWriteWorkflow(
+  env: SecretsStoreEnv,
+  payload: WriteWorkflowPayload,
+): Promise<WriteWorkflowResult> {
+  // The ledger calls touch no value and need no master key, so they are answered before the store is even
+  // opened — which is also what lets a rotation record itself in an environment whose store is refusing.
+  if (isRotationLedgerCommand(payload))
+    return await runRotationLedgerCommand(env, RotationLedgerCommand.parse(payload));
+
+  const store = await SystemSecretsStore.fromEnv(env);
+  const tracker = RotationTracker.fromD1(env.SECRETS);
+  const outcome = await runWriteSecret({ store, tracker }, payload);
+
+  if (payload.audit && payload.mode !== "delete" && payload.mode !== "probe") {
+    const fresh = await SystemSecretsStore.fromEnv(env);
+    const stored = await fresh.getValue(payload.name);
+    return { outcome, audited: stored !== undefined && currentValue(stored) === payload.value };
+  }
+  return { outcome };
+}

package/src/migrations/0001_init.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Create the two secrets tables in the per-environment secrets D1. Both carry the
+ * `pithy_secrets_` prefix so they never clash with an adopter's own tables.
+ *
+ * Identifiers — table, index, and column names — are declared in **camelCase**: the
+ * runner installs `CamelCasePlugin`, which snake-cases every identifier in the emitted
+ * DDL. So we never hand-write snake_case (CLAUDE.md §Data layer); the `pithy_secrets_`
+ * snake form exists only in the actual database. `pithySecretsSystemSecrets` becomes the
+ * SQL table `pithy_secrets_system_secrets`, and the column names match the Zod schemas.
+ *
+ * `down` is the tested inverse: drop both tables. D1 has no transactional DDL, so the
+ * order is deliberate — the rotations index and table first, then the secrets table.
+ */
+export const secrets_0001_init: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithySecretsSystemSecrets")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("name", "text", (c) => c.notNull().unique())
+      .addColumn("encryptedValue", "text", (c) => c.notNull())
+      .addColumn("iv", "text", (c) => c.notNull())
+      .addColumn("keyVersion", "integer", (c) => c.notNull())
+      .addColumn("valueType", "text", (c) => c.notNull().defaultTo("text"))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema
+      .createTable("pithySecretsRotations")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("name", "text", (c) => c.notNull())
+      .addColumn("startedAt", "integer", (c) => c.notNull())
+      .addColumn("completedAt", "integer")
+      .addColumn("status", "text", (c) => c.notNull())
+      .addColumn("trigger", "text", (c) => c.notNull())
+      .addColumn("rotatedBy", "text", (c) => c.notNull())
+      .addColumn("errorMessage", "text")
+      .addColumn("metadataSnapshot", "text")
+      .execute();
+
+    await db.schema.createIndex("pithySecretsRotationsNameIdx").on("pithySecretsRotations").column("name").execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropTable("pithySecretsRotations").execute();
+    await db.schema.dropTable("pithySecretsSystemSecrets").execute();
+  },
+};

package/src/mintValue.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DevSecretValue } from "@pithy-sh/core/src/capability/devSecret";
+
+/** Bytes of entropy behind a minted value — 256 bits, the same budget as the master key. */
+const RANDOM_BYTES = 32;
+
+/**
+ * A fresh random string: 32 bytes of CSPRNG entropy, base64url and unpadded.
+ *
+ * **`crypto.getRandomValues`, and it must stay that way.** This is the only source of key material the
+ * kit generates — for local dev and for a deployed environment alike — so a substitution here that is
+ * not cryptographically secure would silently weaken every session signature, every signed link, and
+ * every key-encryption key the tool creates. There is no fallback path and there must not be one: on
+ * Workers, Node 22 and Bun, `crypto` is global and this always resolves.
+ *
+ * base64url rather than base64 so the value survives every place a minted value is carried by hand — a
+ * `.dev.vars` line, a shell export, a URL — without quoting or an `=` that reads as a second separator.
+ */
+function randomValue(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(RANDOM_BYTES));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Mint a value for a secret whose registry entry declares one may be minted.
+ *
+ * **For every environment, including production.** This was documented as local-dev-only, and named for
+ * it, through four releases in which that was true. #321 made it the sole producer of key material
+ * written into a real account's Secrets Store and into a deployed environment's secrets D1 — by
+ * `pithy provision --env staging`, `--env prod`, `pithy secrets provision` and `pithy feature` — and
+ * left the contract saying the opposite. A security requirement documented as applying to dev, on the
+ * function that generates production keys, is a requirement nobody is checking. So the name and the
+ * sentence now say what the function is for; see `randomValue` for the property that must hold.
+ *
+ * The declaration is what limits it, not the environment. An entry carries a mintable value only when
+ * the value is *arbitrary* — a session signing key, a link signing key — and that is a fact about the
+ * value rather than about where it runs: nothing outside the project validates one, in prod for exactly
+ * the reason it does not on a laptop. A secret that must match something already issued carries no
+ * declaration and nothing here invents one. See {@link isMintableSecret}.
+ *
+ * The switch is exhaustive on purpose. A second {@link DevSecretValue} kind that this cannot produce
+ * fails the build here, rather than silently writing a random string where something else was meant.
+ */
+export function mintSecretValue(kind: DevSecretValue): string {
+  switch (kind) {
+    case "random":
+      return randomValue();
+  }
+}