@pithy-sh/secrets 0.1.0

package/src/provision/provisionSecrets.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import type { EncryptionConfig } from "../crypto/envelope";
+import { generateKeyB64 } from "../rotation/keyRotation";
+import { type ManagedEnvironment, managedEnvironments } from "../scope";
+
+/**
+ * The CF Secrets Store entry name holding an environment's master key — `<project>-<env>-secrets-encryption-keys`.
+ *
+ * A Cloudflare account has **one** Secrets Store, flat and unpartitionable, so the entry name is the
+ * only partition there is. Without the project segment, two Pithy projects in one account would both
+ * resolve to the same entry: the second `pithy secrets provision` would find the first's key already
+ * there, adopt it, and encrypt its rows under another project's key — and either project's teardown
+ * would then orphan both. The environment segment keeps staging and prod distinct within a project.
+ *
+ * Composed through core's naming facade as a **Secrets Store entry**, not through the generic composer.
+ * The kind is what carries the limit: a store entry has no documented Cloudflare cap, so it is held to
+ * Pithy's own ceiling rather than to R2's 63 — which is why this reads `…-secrets-encryption-keys`
+ * rather than the hashed `…-secrets-encryp-91c2e9` a 63-character budget once produced. The facade also
+ * validates the environment, so a stale spelling fails here rather than naming an entry nothing binds.
+ *
+ * The worker still binds this entry under the fixed `SECRETS_ENCRYPTION_KEYS` **binding** name; only the
+ * store entry is scoped (see the manager's resolved `wrangler.jsonc`).
+ */
+export function masterKeySecretName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).secretEntry("secrets-encryption-keys");
+}
+
+/**
+ * The profile/`.dev.vars` **secret name** the manager's CF API token is known by — the registry join
+ * key, not a Secrets Store entry name. Deliberately unscoped: it is a variable key, and scoping it
+ * would rename an environment variable rather than partition an account-wide namespace.
+ */
+export const MANAGER_CF_API_TOKEN_SECRET = "SECRETS_MANAGER_CF_API_TOKEN";
+
+/**
+ * The CF Secrets Store entry name holding the scoped CF API token, bound into each manager as
+ * `CLOUDFLARE_API_TOKEN` — `<project>-global-secrets-manager-cf-api-token`.
+ *
+ * The token is `global` (one value, written once canonically and bound the same way by every manager
+ * of this project), so the literal `global` fills the environment slot rather than being omitted — the
+ * naming rule has no exception to remember. The facade makes that a property rather than a string:
+ * `names.global` is the same interface an environment gets, so no call site can typo the scope into a
+ * near-miss of a real environment. Provisioning owns this store-entry-name → binding-var mapping out of
+ * band; the manager registry stays keyed by the binding var (see `manager/managerRegistry`).
+ */
+export function managerCfApiTokenSecretName(project: string): string {
+  return resourceNames(project).global.secretEntry(MANAGER_CF_API_TOKEN_SECRET);
+}
+
+/**
+ * The Cloudflare account-token **name** under which provisioning mints the manager's runtime
+ * credential — `<project>-global-secrets-manager`. Distinct from
+ * {@link managerCfApiTokenSecretName}, the Secrets Store entry name that holds the token's value:
+ * this is the token's identity in the account's API-token list, the key idempotent re-mint and
+ * teardown match on.
+ *
+ * The account's token list is flat too, and teardown deletes **every** token of this name. An
+ * unscoped name would therefore make one project's `pithy secrets deprovision` revoke every other
+ * project's manager credential in the same account — every one of their rotations failing at once.
+ *
+ * Named as an **API token** through the facade, which is the only reason the two functions can differ
+ * in budget as well as in suffix: a token label is a free-text field Cloudflare puts no cap on.
+ */
+export function managerCfApiTokenName(project: string): string {
+  return resourceNames(project).global.apiToken("secrets-manager");
+}
+
+/**
+ * Mint a fresh master key and build the initial encryption config to store as the env's
+ * `SECRETS_ENCRYPTION_KEYS` at provision time: version 1, one key, current. A real
+ * `ensureMasterKey` JSON-stringifies this and writes it to CF Secrets Store — but only when no key
+ * exists yet, since replacing it would orphan every stored secret.
+ */
+export async function initialMasterKeyConfig(now: Date = new Date()): Promise<EncryptionConfig> {
+  return { currentVersion: "1", versions: { "1": await generateKeyB64() }, lastRotatedAt: now.toISOString() };
+}
+
+/**
+ * The provisioning orchestration for `pithy add secrets`. It stands up the durable, per-environment
+ * secrets infrastructure that the rest of the capability assumes: a dedicated D1, a minted master
+ * key, the migrated schema, and the deployed manager worker — once per managed environment.
+ *
+ * The live Cloudflare/wrangler operations are behind the {@link SecretsProvisioner} seam so the
+ * orchestration is unit-tested (the sequence, the per-env fan-out, idempotency contract) without
+ * touching Cloudflare; the real seam implementation is the live-CF glue, verified by the integration
+ * suite. Each `ensure*` step must be **idempotent** — re-running `pithy add secrets` is a no-op.
+ */
+export interface SecretsProvisioner {
+  /**
+   * Verify the account prerequisites before any resource is created — most importantly that a
+   * `workers.dev` subdomain is registered, which Cloudflare requires to deploy the Workflow-hosting
+   * managers. Throws a clear error if a prerequisite is missing, so provisioning fails fast and clean
+   * (nothing half-created) rather than partway through a deploy.
+   */
+  preflight(): Promise<void>;
+  /**
+   * Ensure the manager's least-privilege CF API token (Secrets Store Read + Write) and write it into
+   * the Secrets Store as the manager's runtime credential — once, before any per-env work, since the
+   * token is `global`. Runs first so a bootstrap token that **cannot** mint account tokens fails the
+   * whole provision fast and clean, before any resource is created. Idempotent: reuse the stored token
+   * if present, otherwise roll the existing manager token's value in place (or mint one if none exists).
+   */
+  ensureManagerToken(): Promise<void>;
+  /** Create (or reuse) the per-env secrets D1; returns its id. Idempotent. */
+  ensureDatabase(env: ManagedEnvironment): Promise<{ databaseId: string }>;
+  /**
+   * Mint the initial master key and store it as `SECRETS_ENCRYPTION_KEYS` for this environment;
+   * returns the Secrets Store id. Idempotent — if the key already exists, it is left untouched (a
+   * fresh key would orphan every stored secret).
+   */
+  ensureMasterKey(env: ManagedEnvironment): Promise<{ storeId: string }>;
+  /** Run the `secrets_*` migrations against this environment's D1. Idempotent (already-applied are skipped). */
+  migrate(env: ManagedEnvironment, databaseId: string): Promise<void>;
+  /** Deploy the prebuilt manager worker for this environment, wired to the resolved resource ids. */
+  deployManager(env: ManagedEnvironment, resolved: { databaseId: string; storeId: string }): Promise<void>;
+}
+
+/** What provisioning produced, per environment — the resource ids the manager's `wrangler.jsonc` needs. */
+export interface ProvisionResult {
+  perEnv: Array<{ env: ManagedEnvironment; databaseId: string; storeId: string }>;
+}
+
+/**
+ * Provision every managed environment in order: mint the global manager token, then per env create
+ * the D1, mint the master key, migrate, deploy the manager. The order matters — the manager token is
+ * minted first (one global credential, and a bootstrap token that cannot mint fails fast before
+ * anything is created), the database and key exist before migrations run, and the manager is deployed
+ * last, once its resources are in place. Idempotent end to end (each step is).
+ *
+ * `environments` is the project's declaration, and **the loop is over all of it**: an environment the
+ * project deploys to and this skips is one whose secrets have no master key — the exact silence #241
+ * found. One manager per declared environment is the price of declaring it (see `scope.ts`).
+ */
+export async function provisionSecrets(
+  provisioner: SecretsProvisioner,
+  environments: DeclaredEnvironments | readonly string[],
+): Promise<ProvisionResult> {
+  await provisioner.preflight();
+  await provisioner.ensureManagerToken();
+  const perEnv: ProvisionResult["perEnv"] = [];
+  for (const env of managedEnvironments(environments)) {
+    const { databaseId } = await provisioner.ensureDatabase(env);
+    const { storeId } = await provisioner.ensureMasterKey(env);
+    await provisioner.migrate(env, databaseId);
+    await provisioner.deployManager(env, { databaseId, storeId });
+    perEnv.push({ env, databaseId, storeId });
+  }
+  return { perEnv };
+}
+
+/**
+ * The teardown seam — the inverse of {@link SecretsProvisioner}, removing each environment's secrets
+ * infrastructure. Behind the seam so the orchestration (order, the key-deletion guard, idempotency)
+ * is unit-tested without Cloudflare; the live implementation is verified by the integration suite.
+ * Every step is idempotent — a missing resource is a no-op, so re-running teardown is safe.
+ */
+export interface SecretsDeprovisioner {
+  /** Delete the env's manager worker. Idempotent (a missing worker is a no-op). */
+  deleteManager(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Delete the env's master key from the Secrets Store. Destructive — every stored secret becomes
+   * undecryptable — so the orchestration only calls it when explicitly asked. Idempotent.
+   */
+  deleteMasterKey(env: ManagedEnvironment): Promise<void>;
+  /** Delete the env's secrets D1. Idempotent (a missing database is a no-op). */
+  deleteDatabase(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Remove the manager's CF API token entirely: delete the minted account token from Cloudflare
+   * **and** its `<project>-global-secrets-manager-cf-api-token` entry from the Secrets Store. Both
+   * names are project-scoped, so this never reaches another project's credential. It is `global` —
+   * one token shared by both managers — so it is removed once, after every manager is gone. Safe and
+   * ungated: the token is a re-mintable access credential, not a key, so removing it orphans no
+   * secrets. Idempotent (a missing token or entry is a no-op).
+   */
+  deleteManagerToken(): Promise<void>;
+}
+
+/** Teardown options. By default the master keys are **kept** — deleting them is irreversible. */
+export interface DeprovisionOptions {
+  /** Also delete each environment's master key. Off by default; only a full destroy sets it. */
+  deleteKeys?: boolean;
+}
+
+/**
+ * Tear down every managed environment, reversing {@link provisionSecrets}: delete the manager worker
+ * first (it binds the other resources), then — only when `deleteKeys` is set — the master key, then
+ * the D1. The master key is preserved unless explicitly requested: losing it orphans every secret,
+ * and a re-provision can reuse the existing key. The shared manager CF API token is deleted once at
+ * the end, after every manager that binds it is gone. Idempotent end to end.
+ */
+export async function deprovisionSecrets(
+  deprovisioner: SecretsDeprovisioner,
+  environments: DeclaredEnvironments | readonly string[],
+  options: DeprovisionOptions = {},
+): Promise<void> {
+  for (const env of managedEnvironments(environments)) {
+    await deprovisioner.deleteManager(env);
+    if (options.deleteKeys) await deprovisioner.deleteMasterKey(env);
+    await deprovisioner.deleteDatabase(env);
+  }
+  await deprovisioner.deleteManagerToken();
+}

package/src/provision/resolveManagerConfig.ts

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { SECRETS_CAPABILITY, secretsRotateWorkflowName, secretsWriteWorkflowName } from "../manager/dispatcher";
+import { type ManagedEnvironment, managedEnvironments } from "../scope";
+import { managerCfApiTokenSecretName, masterKeySecretName } from "./provisionSecrets";
+
+/**
+ * The manager's `wrangler.jsonc` template shape — only the fields provisioning resolves. The
+ * committed template (`src/manager/wrangler.jsonc`) is the source of truth for the static fields
+ * (compatibility date, crons, class names); this resolver fills the per-environment placeholders.
+ */
+export interface ManagerWranglerTemplate {
+  name: string;
+  main: string;
+  compatibility_date: string;
+  compatibility_flags: string[];
+  /** Off — the manager has no public URL (Workflow dispatch + cron only). Passed through unchanged. */
+  workers_dev: boolean;
+  d1_databases: Array<{ binding: string; database_name: string; database_id: string }>;
+  secrets_store_secrets: Array<{ binding: string; store_id: string; secret_name: string }>;
+  workflows: Array<{ binding: string; name: string; class_name: string }>;
+  triggers: { crons: string[] };
+  vars: Record<string, string>;
+}
+
+/** The resolved resource ids for one environment's manager deploy. */
+export interface ManagerConfigParams {
+  env: ManagedEnvironment;
+  databaseId: string;
+  storeId: string;
+  accountId: string;
+  /**
+   * The project name (root `pithy.config.ts` `name`, via `requireProjectName` — never guessed). Every
+   * name in the resolved config leads with it: the Worker script, its D1, both Workflows, and both
+   * Secrets Store entries. It is also stamped into the worker as the `PROJECT` var, so the at-rest
+   * rotation writes its new key set back to the entry this worker actually binds.
+   */
+  project: string;
+}
+
+/**
+ * One project's manager for one environment — `<project>-<env>-secrets`. It is three things at once:
+ * the deployed Worker script name, the resolved config's basename, and the `database_name` of that
+ * environment's secrets D1 (the manager and its database are one unit, so they share one name).
+ *
+ * **This is the sharpest project-scoping case in the toolset.** A Worker script name is account-scoped
+ * and `wrangler deploy` upserts: unscoped, a second Pithy project's `pithy secrets provision` does not
+ * collide with the first — it silently *replaces* the first project's running secrets manager, pointing
+ * it at the second project's D1 and master key. Every subsequent write and rotation for the first
+ * project then lands in, or fails against, resources it does not own. The D1 name shares the same flat
+ * namespace and the same fate.
+ *
+ * Named as a **Worker script** through core's facade, so it is held to 63 — the workers.dev cap, the
+ * only one that survives an adopter enabling a subdomain — rather than to the Workflow's 64 the two
+ * numbers used to share. The database takes the same string deliberately: the manager and its D1 are
+ * one unit, and a D1 name is the looser of the two limits, so the tighter one governs both.
+ */
+export function managerWorkerName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).worker(SECRETS_CAPABILITY);
+}
+
+/**
+ * The deployed name behind one of the manager's Workflow bindings.
+ *
+ * Derived from the binding, never from the template's own `name`. The template says
+ * `pithy-secrets-write`, and no amount of suffixing recovers a project from that — so, exactly like
+ * every other capability's host resolver, the name is composed from `(project, capability, job, env)`
+ * and the template's literal is documentation. An unrecognized binding is an authoring bug: it would
+ * deploy a Workflow under a name nothing dispatches to, so it fails loudly here.
+ */
+function managerWorkflowName(binding: string, project: string, env: ManagedEnvironment): string {
+  switch (binding) {
+    case "SECRETS_WRITE":
+      return secretsWriteWorkflowName(project, env);
+    case "AT_REST_ROTATION":
+      return secretsRotateWorkflowName(project, env);
+    default:
+      throw new InternalError({
+        message: "The secrets manager template declares a Workflow provisioning cannot name.",
+        action: "Give the binding a project-scoped name in resolveManagerConfig, or drop it from the template.",
+        detail: `unresolved workflows binding: ${binding}`,
+      });
+  }
+}
+
+/**
+ * Resolve the manager `wrangler.jsonc` template into one environment's standalone config — no
+ * `[env.*]` stanzas (CLAUDE.md: staging and prod are genuinely separate workers). The template
+ * carries `<filled-at-provision>` placeholders; this fills the project-scoped worker and Workflow
+ * names, the D1 id and name, the Secrets Store id and entry names, and the account id, leaving every
+ * static field untouched. Pure: the caller parses the template and writes the result.
+ *
+ * Every name it composes leads with the project, and every one goes through core's naming facade under
+ * its own kind — a Worker script for the host, a Workflow for each job, a Secrets Store entry for each
+ * bound secret — rather than suffixing the template's own literals, which carry no project to suffix.
+ * Picking the kind is what picks the limit; no call here passes a budget.
+ */
+export function resolveManagerConfig(
+  template: ManagerWranglerTemplate,
+  params: ManagerConfigParams,
+): ManagerWranglerTemplate {
+  const { env, databaseId, storeId, accountId, project } = params;
+  const name = managerWorkerName(project, env);
+  const resolved: ManagerWranglerTemplate = structuredClone(template);
+
+  resolved.name = name;
+  resolved.d1_databases = resolved.d1_databases.map((db) => ({ ...db, database_name: name, database_id: databaseId }));
+  // Both secrets live in the one account-wide store, so every entry gets `storeId` — and **every**
+  // entry name is resolved here, never passed through. The template's literals are placeholders: an
+  // entry name provisioning did not write is an entry the worker cannot bind, so an unrecognized
+  // binding is an authoring bug and fails loudly rather than deploying a worker that dies on first read.
+  resolved.secrets_store_secrets = resolved.secrets_store_secrets.map((entry) => ({
+    ...entry,
+    store_id: storeId,
+    secret_name: managerStoreEntryName(entry.binding, project, env),
+  }));
+  // The write Workflow's name is the CLI's dispatch target (<project>-<env>-secrets-write). Both are
+  // composed from the binding, so two projects' managers are addressable separately in one account.
+  resolved.workflows = resolved.workflows.map((wf) => ({ ...wf, name: managerWorkflowName(wf.binding, project, env) }));
+  resolved.vars = {
+    ...resolved.vars,
+    CLOUDFLARE_ACCOUNT_ID: accountId,
+    SECRETS_STORE_ID: storeId,
+    ENVIRONMENT: env,
+    PROJECT: project,
+  };
+
+  return resolved;
+}
+
+/**
+ * The Secrets Store entry name behind one of the manager's store bindings. The master key is
+ * per-environment; the CF API token is `global`. Both are project-scoped, because the account has
+ * one flat Secrets Store and the name is the only partition in it.
+ */
+function managerStoreEntryName(binding: string, project: string, env: ManagedEnvironment): string {
+  switch (binding) {
+    case "SECRETS_ENCRYPTION_KEYS":
+      return masterKeySecretName(project, env);
+    case "CLOUDFLARE_API_TOKEN":
+      return managerCfApiTokenSecretName(project);
+    default:
+      throw new InternalError({
+        message: "The secrets manager template declares a Secrets Store binding provisioning never writes.",
+        action: "Give the binding a project-scoped entry name in resolveManagerConfig, or drop it from the template.",
+        detail: `unresolved secrets_store_secrets binding: ${binding}`,
+      });
+  }
+}
+
+/**
+ * Resolve the manager config for every declared environment, given each env's provisioned ids.
+ *
+ * An environment with no entry in `perEnv` is skipped rather than resolved against `undefined` ids: the
+ * ids are what provisioning produced, so a gap means that environment was not provisioned, and writing a
+ * manager config with an empty `database_id` would deploy a manager bound to nothing.
+ */
+export function resolveAllManagerConfigs(
+  template: ManagerWranglerTemplate,
+  account: { accountId: string; project: string },
+  perEnv: Record<ManagedEnvironment, { databaseId: string; storeId: string }>,
+  environments: DeclaredEnvironments | readonly string[],
+): Array<{ env: ManagedEnvironment; config: ManagerWranglerTemplate }> {
+  const resolved: Array<{ env: ManagedEnvironment; config: ManagerWranglerTemplate }> = [];
+  for (const env of managedEnvironments(environments)) {
+    const ids = perEnv[env];
+    if (!ids) continue;
+    resolved.push({ env, config: resolveManagerConfig(template, { env, ...account, ...ids }) });
+  }
+  return resolved;
+}