@pithy-sh/cli 0.1.0

package/src/tokens/engine.ts

@@ -0,0 +1,345 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareNotConfiguredError } from "@pithy-sh/cloudflare/src/client/errors";
+import type {
+  AccountTokenSummary,
+  MintedAccountToken,
+  TokenPermission,
+} from "@pithy-sh/cloudflare/src/tokens/accountTokensManager";
+import type { PermissionKey } from "@pithy-sh/cloudflare/src/tokens/permissions";
+import {
+  type ProfileOverride,
+  profilePermissions,
+  resolveProfile,
+  type TokenProfile,
+  type TokenStore,
+} from "@pithy-sh/cloudflare/src/tokens/profiles";
+import { kebab } from "@pithy-sh/core/src/naming/resource";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import type { StatePathOptions } from "../notifier/state";
+import { type SinkTarget, writeTokenToSink } from "./sinks";
+
+/** The account-token control plane the engine drives — the subset of `CloudflareAccountTokensManager` it needs. */
+export interface AccountTokenControl {
+  mintToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+  rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+  findTokenByName(name: string): Promise<AccountTokenSummary | null>;
+  listTokens(): Promise<AccountTokenSummary[]>;
+  deleteToken(id: string): Promise<void>;
+  deleteTokensByName(name: string): Promise<number>;
+}
+
+/** The audit action codes for token lifecycle events — the `cloudflare/token_*` federated taxonomy. */
+export const TokenAuditActions = {
+  minted: "cloudflare/token_minted",
+  rotated: "cloudflare/token_rotated",
+  revoked: "cloudflare/token_revoked",
+} as const;
+
+/** One token-lifecycle audit event. Never carries the token value — only its id and where it went. */
+export interface TokenAuditEvent {
+  action: string;
+  outcome: "success" | "failure";
+  profile: string;
+  env: string;
+  tokenId?: string;
+  store?: TokenStore;
+}
+
+/** The audit sink: records a token-lifecycle event. Absent → auditing is a no-op (audit not composed). */
+export type TokenAudit = (event: TokenAuditEvent) => Promise<void>;
+
+/** Everything the engine needs to mint, store, list, rotate, and revoke a project's scoped tokens. */
+export interface TokenEngine {
+  /** The account tokens target. */
+  accountId: string;
+  /**
+   * The project name (root `pithy.config.ts` `name`, via `requireProjectName` — never guessed). The
+   * first segment of every token name and of every Secrets Store entry a mint writes. Required, because
+   * Cloudflare's account token list and Secrets Store are both flat: without it, two Pithy projects in
+   * one account mint tokens of the same name, and `revoke` — which deletes *every* token of a name —
+   * revokes the other project's credential along with its own.
+   */
+  project: string;
+  /** The project root — for the audit sink's app-database lookup. Nothing minted is written into it (#182). */
+  projectDir: string;
+  /** Where the Pithy config directory is. Defaults to the real one; a seam so a test writes its own. */
+  paths?: StatePathOptions;
+  /** The CF account-token control plane (the bootstrap token authenticates it). */
+  tokens: AccountTokenControl;
+  /** The aggregated profile registry (`resolveTokenProfiles`). */
+  profiles: Record<string, TokenProfile>;
+  /** The declared backend of a secret name (from the composed secret registry), for the store destination. */
+  secretBackend?: (secretName: string) => string | undefined;
+  /** Writes to the CF Secrets Store, for the `secrets-store` destination. Absent → that destination errors. */
+  putSecret?: (name: string, value: string) => Promise<void>;
+  /** Records lifecycle events; a no-op when absent (audit not composed). */
+  audit?: TokenAudit;
+  /** Resolves an adopter's `pithy.config.ts` override for a profile. */
+  override?: (profile: string) => ProfileOverride | undefined;
+}
+
+/** Per-call overrides (CLI flags) that win over the profile default and the config override. */
+export interface MintOptions {
+  /** Override the store (`--store`). */
+  store?: TokenStore;
+  /** Override the permission keys (`--permission`). */
+  permissions?: PermissionKey[];
+}
+
+/**
+ * The stable CF token name for a (project, env, profile): `<project>-<env>-<profile>`. One identity per
+ * triple, rolled in place on re-mint.
+ *
+ * The account's API-token list is flat and account-wide, so this name is the only thing that separates
+ * one project's credentials from another's in the same account. The project segment goes first because
+ * that is the ownership boundary {@link tokenPrefix} filters on.
+ */
+export function tokenName(project: string, env: string, profile: string): string {
+  return resourceNames(project).env(env).apiToken(profile);
+}
+
+/**
+ * The prefix every one of a project's tokens for an environment shares — `<project>-<env>-`.
+ *
+ * This is the ownership filter for listing. It must be built from the same kebab-cased segments
+ * {@link tokenName} composes, and only the trailing `thing` segment of a resource name is ever
+ * truncated, so a prefix match here is exact: a token outside this project or this environment cannot
+ * pass it.
+ */
+export function tokenPrefix(project: string, env: string): string {
+  return `${kebab(project)}-${kebab(env)}-`;
+}
+
+/**
+ * The CF Secrets Store entry name a profile's minted value is written to.
+ *
+ * Distinct from `profile.secret`, which is the registry join key and the `.dev.vars` **variable** name.
+ * Only the store entry is scoped: the store is one flat account-wide namespace where an unscoped name
+ * would let one project's mint overwrite another's live credential, whereas `.dev.vars` is a file in
+ * this checkout and renaming its keys would break every CI pipeline reading `CF_TOKEN_CI_SYSTEM`.
+ *
+ * A `global` profile puts the literal `global` in the environment slot, so every environment resolves
+ * the one entry provisioning wrote instead of minting a per-environment entry nothing binds.
+ */
+export function tokenStoreEntryName(project: string, env: string, profile: TokenProfile): string {
+  const names = resourceNames(project);
+  return (profile.secretScope === "global" ? names.global : names.env(env)).secretEntry(profile.secret);
+}
+
+/** The outcome of a mint/rotate. `value` is for the caller's in-process use — never surface it in output. */
+export interface TokenResult {
+  profile: string;
+  env: string;
+  tokenId: string;
+  name: string;
+  /** The secret token value — for in-process use. NEVER include in CLI output or `--json`. */
+  value: string;
+  sink: SinkTarget;
+}
+
+/** Emit a lifecycle event through the audit sink; non-fatal — an audit failure never breaks the action. */
+async function emit(engine: TokenEngine, event: TokenAuditEvent): Promise<void> {
+  if (!engine.audit) return;
+  try {
+    await engine.audit(event);
+  } catch {
+    // Non-fatal by contract: an audit write never breaks the token action it records.
+  }
+}
+
+/** Merge the config override and the per-call CLI flags into one override (CLI flags win). */
+function mergeOverride(engine: TokenEngine, profile: string, options?: MintOptions): ProfileOverride | undefined {
+  const config = engine.override?.(profile);
+  const merged: ProfileOverride = { ...config };
+  if (options?.store) merged.store = options.store;
+  if (options?.permissions) merged.permissions = options.permissions;
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve where a profile's minted value is written: the `--store`/profile override if set, otherwise
+ * the token's **declared secret backend** — a token can't live in the encrypted D1 store (Worker-only),
+ * so a store-backed token must be declared `cf-secrets-store`; an undeclared secret with no override
+ * fails with actionable guidance. This is the registry-defined storage: the secret's definition decides
+ * where the value goes, and `dev-vars`/`ephemeral` are the explicit overrides.
+ */
+function resolveDestination(engine: TokenEngine, profile: TokenProfile): TokenStore {
+  // An explicit store (a profile's `defaultStore` or a `--store` override) is the declaration itself.
+  if (profile.defaultStore) return profile.defaultStore;
+  // No store declared → the destination comes from the token's declared secret-registry backend.
+  const backend = engine.secretBackend?.(profile.secret);
+  if (backend === "cf-secrets-store") return "secrets-store";
+  if (backend === "d1") {
+    throw new CloudflareNotConfiguredError({
+      message: `Token "${profile.name}" can't be stored in the encrypted D1 secrets store — its value is read outside the Worker.`,
+      action: `Declare ${profile.secret} as cf-secrets-store, or mint with --store dev-vars.`,
+    });
+  }
+  throw new CloudflareNotConfiguredError({
+    message: `No storage is declared for token "${profile.name}".`,
+    action: `Declare the secret ${profile.secret} (pithy secrets) as cf-secrets-store, or mint with --store dev-vars.`,
+  });
+}
+
+/**
+ * Mint the profile's token for an environment and return a usable value. **Rolls in place**: the token
+ * name is a stable `(profile, env)` identity, and each mint regenerates its value with the profile's
+ * *current* permissions — so adding a capability's `ciPermissions` (or an override) takes effect on the
+ * next mint, without hand-editing scopes. The fresh value is written to the resolved store and returned
+ * for in-process use. Audited on success/failure.
+ *
+ * It does not reuse a stored value: that would pin the token to its old scope, silently defeating the
+ * "add a capability → the CI token grows" contract. Roll keeps one identity, so re-minting never orphans
+ * a token; a Worker consumer reads the current value from its CFSS binding, and a `dev-vars` consumer
+ * re-reads the refreshed file.
+ */
+export async function mintProfileToken(
+  engine: TokenEngine,
+  profileName: string,
+  env: string,
+  options?: MintOptions,
+): Promise<TokenResult> {
+  const profile = resolveProfile(engine.profiles, profileName, mergeOverride(engine, profileName, options));
+  const store = resolveDestination(engine, profile);
+  const name = tokenName(engine.project, env, profileName);
+
+  try {
+    const minted = await engine.tokens.rollToken(name, profilePermissions(profile, engine.accountId));
+    const sink = await writeTokenToSink(store, minted.value, {
+      project: engine.project,
+      env,
+      secretName: profile.secret,
+      storeEntryName: tokenStoreEntryName(engine.project, env, profile),
+      putSecret: engine.putSecret,
+      ...(engine.paths !== undefined ? { paths: engine.paths } : {}),
+    });
+    await emit(engine, {
+      action: TokenAuditActions.minted,
+      outcome: "success",
+      profile: profileName,
+      env,
+      tokenId: minted.id,
+      store,
+    });
+    return { profile: profileName, env, tokenId: minted.id, name, value: minted.value, sink };
+  } catch (error) {
+    await emit(engine, { action: TokenAuditActions.minted, outcome: "failure", profile: profileName, env });
+    throw error;
+  }
+}
+
+/** One row of `pithy token list`: a minted token's identity, never its value. */
+export interface TokenListItem {
+  profile: string;
+  env: string;
+  name: string;
+  tokenId: string;
+  status?: string;
+}
+
+/**
+ * List **this project's** minted tokens for an environment — identities only, never values.
+ *
+ * Two gates, and both matter. The `<project>-<env>-` prefix is the ownership filter: the account token
+ * list is every token in the account, including other Pithy projects' and the operator's own, and
+ * anything the CLI lists is something it offers to rotate and revoke.
+ *
+ * The profile is then recovered by **reverse lookup** from the known profile names, not by slicing the
+ * prefix off the name. A token name is composed through the naming facade, which truncates and hashes a
+ * trailing segment past its namespace's budget — so the profile segment on the wire is not always
+ * the profile name, and a slice would hand back a mangled string that `rotate`/`revoke` cannot resolve.
+ * Composing each known profile's name and matching exactly is the only recovery that survives that. A
+ * prefixed token no profile claims is therefore not listed: it is not a profile token this CLI can act on.
+ */
+export async function listProfileTokens(engine: TokenEngine, env: string): Promise<TokenListItem[]> {
+  const prefix = tokenPrefix(engine.project, env);
+  const byName = new Map<string, string>();
+  for (const profile of Object.keys(engine.profiles)) {
+    byName.set(tokenName(engine.project, env, profile), profile);
+  }
+  const all = await engine.tokens.listTokens();
+  return all.flatMap((token) => {
+    if (!token.name.startsWith(prefix)) return [];
+    const profile = byName.get(token.name);
+    if (!profile) return [];
+    return [{ profile, env, name: token.name, tokenId: token.id, status: token.status }];
+  });
+}
+
+/** Options for `pithy token rotate`. */
+export interface RotateOptions extends MintOptions {
+  /** Keep the previous token instead of deleting it — a grace window for consumers to pick up the new one. */
+  keepPrevious?: boolean;
+}
+
+/**
+ * Rotate the profile's token with the proven two-step (Cloudflare has no single-call rotate): mint a
+ * **new** token with the same name and policies, store its value, then delete the prior token(s) by id.
+ * `keepPrevious` leaves the old token in place — a grace window while a Worker consumer picks up the
+ * new value (redeploy) before it is revoked. Audited on success/failure.
+ */
+export async function rotateProfileToken(
+  engine: TokenEngine,
+  profileName: string,
+  env: string,
+  options?: RotateOptions,
+): Promise<TokenResult> {
+  const profile = resolveProfile(engine.profiles, profileName, mergeOverride(engine, profileName, options));
+  const store = resolveDestination(engine, profile);
+  const name = tokenName(engine.project, env, profileName);
+  try {
+    // Snapshot the prior token id(s) before creating the replacement, so we delete exactly what predates it.
+    const priorIds = (await engine.tokens.listTokens()).filter((token) => token.name === name).map((token) => token.id);
+    const minted = await engine.tokens.mintToken(name, profilePermissions(profile, engine.accountId));
+    const sink = await writeTokenToSink(store, minted.value, {
+      project: engine.project,
+      env,
+      secretName: profile.secret,
+      storeEntryName: tokenStoreEntryName(engine.project, env, profile),
+      putSecret: engine.putSecret,
+      ...(engine.paths !== undefined ? { paths: engine.paths } : {}),
+    });
+    if (!options?.keepPrevious) {
+      for (const id of priorIds) await engine.tokens.deleteToken(id);
+    }
+    await emit(engine, {
+      action: TokenAuditActions.rotated,
+      outcome: "success",
+      profile: profileName,
+      env,
+      tokenId: minted.id,
+      store,
+    });
+    return { profile: profileName, env, tokenId: minted.id, name, value: minted.value, sink };
+  } catch (error) {
+    await emit(engine, { action: TokenAuditActions.rotated, outcome: "failure", profile: profileName, env });
+    throw error;
+  }
+}
+
+/** The outcome of a revoke — how many tokens of the profile's name were deleted. */
+export interface RevokeResult {
+  profile: string;
+  env: string;
+  name: string;
+  revoked: number;
+}
+
+/**
+ * Revoke the profile's token(s) for an environment — deletes **every** account token of that name.
+ * Audited. The name is project-scoped, which is what keeps that sweep inside this project: an unscoped
+ * name would make one project's revoke delete every other project's token of the same profile.
+ */
+export async function revokeProfileToken(engine: TokenEngine, profileName: string, env: string): Promise<RevokeResult> {
+  const name = tokenName(engine.project, env, profileName);
+  try {
+    const revoked = await engine.tokens.deleteTokensByName(name);
+    await emit(engine, { action: TokenAuditActions.revoked, outcome: "success", profile: profileName, env });
+    return { profile: profileName, env, name, revoked };
+  } catch (error) {
+    await emit(engine, { action: TokenAuditActions.revoked, outcome: "failure", profile: profileName, env });
+    throw error;
+  }
+}

package/src/tokens/mintedTokens.ts

@@ -0,0 +1,233 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join } from "node:path";
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { devSecretsDir } from "../devSecrets/location";
+import { ensureOwnerOnlyDirFor, tightenMode } from "../devSecrets/mode";
+import type { StatePathOptions } from "../notifier/state";
+import { writeFileAtomic } from "../project/atomic";
+import { type MergeBase, readMergeBase, readOptionalFile, requireRecord } from "../project/readOptionalFile";
+
+/**
+ * Where `pithy token mint --store dev-vars` puts a minted token: `<config>/<project>/tokens.json`,
+ * keyed by environment, mode `0600`, in the `0700` project directory (#182).
+ *
+ * **It used to be `.dev.vars.<env>`, inside the checkout.** `devVarsFileName` returned `.dev.vars` for
+ * dev and `.dev.vars.<env>` for anything else, so `pithy token mint --env production --store dev-vars`
+ * wrote a **live production Cloudflare token into the project directory** — one file per environment,
+ * each holding that environment's credential. They were gitignored, which is not sufficient on its own:
+ * #145 was an `npm pack` leak, and `npm pack` does not consult `.gitignore` when `files` is set in
+ * `package.json`. That path also had its own permissions defect on record — a private copy of the upsert
+ * that lacked the shared one's `0600`, so minting for an environment with no file yet left a production
+ * credential at the umask default, `0664`.
+ *
+ * The rule this file exists to make structural: **no minted credential is written into the checkout, for
+ * any environment.** There is no filename here a project directory can hold.
+ *
+ * **Per project, not per account.** Unlike the bootstrap pair in `<config>/cloudflare.json`, these are
+ * minted *for this project's* environments — the store entry name they mirror is project-scoped for
+ * exactly that reason, since the Secrets Store is one flat account-wide namespace.
+ *
+ * **One file, keyed by environment, rather than a file per environment.** A family of files is the shape
+ * that produced the defect above: each new environment is a new path, created by whichever call site got
+ * there first, at whatever mode that call site remembered. One document has one creation site and one
+ * mode.
+ */
+
+/** The file's name inside the project's config directory. Undotted: nothing here is hidden from anything. */
+export const MINTED_TOKENS_FILE_NAME = "tokens.json";
+
+/**
+ * The minted-token document: environment → variable name → value.
+ *
+ * Validated because it is read off disk and hand-editable, and because a non-string value would be
+ * handed to a later CLI run as a credential. The variable name is the profile's `secret` verbatim — a
+ * local environment-variable name like `CF_TOKEN_CI_SYSTEM`, never project-scoped, because that is what
+ * a pipeline reads.
+ */
+export const MintedTokens = z
+  .record(
+    z.string().describe("The environment the token was minted for — `dev`, `staging`, `production`."),
+    z
+      .record(
+        z.string().describe("The token's variable key, exactly as the profile declares it."),
+        z.string().describe("The minted token value. Never logged, never printed, never in --json."),
+      )
+      .describe("Every token minted for that environment, by variable key."),
+  )
+  .describe("Minted Cloudflare tokens this machine holds for one project, by environment. Mode 0600.");
+export type MintedTokens = z.output<typeof MintedTokens>;
+
+/**
+ * `<config>/<project>/tokens.json`, from a project name that has already been resolved.
+ *
+ * The **name**, never a directory. It is the same key `secrets.jsonc` and `dev.json` are filed under, so
+ * every worktree of one project reads one file — and the caller has already put the name through
+ * `requireProjectName`, which is the gate that stops a checkout's basename from becoming a second answer.
+ */
+export function mintedTokensPath(project: string, options: StatePathOptions = {}): string {
+  return join(devSecretsDir(project, options), MINTED_TOKENS_FILE_NAME);
+}
+
+/**
+ * Record one minted token under its environment, and answer the file it landed in.
+ *
+ * **Read-modify-write over a credential file, so every state but "there is no file" refuses.** Only
+ * `ENOENT` licenses starting from `{}`. A file that could not be read, one that is not JSON, one that
+ * parsed to something that is not a document, one that is a record of something else — writing this
+ * document over any of them deletes every other environment's live token with no copy anywhere, which is
+ * the exact shape of #142 and of the two `.dev.vars` losses before it. Each refusal is
+ * {@link mintedTokensBase}'s, because it is the one that can tell an absence from an answer, and the
+ * merge below takes a {@link MergeBase} so that no other read can be handed to it (#219).
+ */
+export async function writeMintedToken(
+  project: string,
+  env: string,
+  name: string,
+  value: string,
+  options: StatePathOptions = {},
+): Promise<string> {
+  const base = await mintedTokensBase(mintedTokensPath(project, options));
+  const merged = withMintedToken(base, env, name, value);
+  await ensureOwnerOnlyDirFor(base.path);
+  // The path comes off the base rather than being re-derived, so what is written can only ever land back
+  // on the file the base was read from.
+  await writeFileAtomic(base.path, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
+  // Unconditionally and after the write, the same rule every other credential file here follows: a file
+  // an editor or a `cp` created at the umask holds a live API token at 0644 until something narrows it.
+  await tightenMode(base.path);
+  return base.path;
+}
+
+/**
+ * The document to write: the base, with one token recorded under its environment.
+ *
+ * **It takes a {@link MergeBase} and that is the whole point.** Only {@link readMergeBase} mints one, so
+ * the lenient {@link readMintedTokens} below — which answers `{}` for a file it cannot make sense of,
+ * correctly, because it rewrites nothing — cannot reach this function. The accident that produced all
+ * five instances of this defect is a type error here rather than a replaced credential file on disk.
+ */
+function withMintedToken(base: MergeBase<MintedTokens>, env: string, name: string, value: string): MintedTokens {
+  const document = base.document;
+  return { ...document, [env]: { ...(document[env] ?? {}), [name]: value } };
+}
+
+/**
+ * The merge base for a write over `tokens.json`: the whole document, known-good, or a refusal.
+ *
+ * The strict half of the reader/writer split (#219). Absent is `{}`; unopenable, not JSON, not a record
+ * and not a document of minted tokens are four refusals, each in this file's own words — "Pithy won't
+ * rewrite a credential file it could not read" is the sentence, and the four spellings of "could not
+ * read" are the four ways a hand edit gets there.
+ */
+async function mintedTokensBase(path: string): Promise<MergeBase<MintedTokens>> {
+  return readMergeBase(path, MintedTokens, {
+    unreadable: ({ code, cause }) =>
+      new ConflictError(
+        {
+          message: `Cannot update ${path}: Pithy could not read what is already in it.`,
+          action:
+            "Fix the file's permissions, or move it aside, and run the command again. Pithy won't rewrite a credential file it could not read.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+    unparseable: () =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is there and is not JSON.`,
+        action:
+          "Fix the JSON, or move it aside, and run the command again. Pithy won't rewrite a credential file it could not parse — every other environment's token is still in it.",
+        // Never the parser's own message: it quotes the line it choked on, and these lines are tokens.
+        detail: `${MINTED_TOKENS_FILE_NAME} at ${path} did not parse`,
+      }),
+    notARecord: ({ found }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it holds ${found}, not a document of minted tokens.`,
+        action:
+          "Restore it to a JSON object keyed by environment, or move it aside, and run the command again. Pithy won't rewrite a credential file it could not make sense of.",
+        detail: `${MINTED_TOKENS_FILE_NAME} at ${path} parsed to ${found}`,
+      }),
+    invalid: ({ at }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is not a document of minted tokens.`,
+        action:
+          "Restore it to a JSON object of environment → variable name → token, or move it aside, and run the command again.",
+        // The key path, so the line can be found. Never the value on it, which is a credential.
+        detail: `${MINTED_TOKENS_FILE_NAME} at ${path} failed its schema at ${at}`,
+      }),
+  });
+}
+
+/**
+ * **The reporting read**, for a caller that wants to know what has been minted and will rewrite nothing.
+ *
+ * **It has no production caller today, and that is a true statement about this file rather than dead
+ * code left behind.** The one caller it had routed its planning pass through {@link mintedTokensBase}
+ * in #222 — because a plan computed against a file it could not read is a plan that may tell somebody a
+ * value is safe to delete — and was itself removed in #406. Nothing else reads `tokens.json` at all: #224
+ * established that the `dev-vars` sink's consumer is a person, who opens the file and pastes the
+ * `ci-system` token into CI.
+ *
+ * **It stays because the split is the design, not because something might want it.** #219's whole
+ * argument is that a reporting read and a merge base are different things and a call site must not be
+ * able to reach for the wrong one by accident. Deleting the reporting half would leave the next caller
+ * that wants to *report* on this file with only the strict read — which refuses where reporting should
+ * shrug — and the obvious move then is to re-add a lenient read locally, which is exactly how all five
+ * instances of that defect happened. The command #224 proposes, a `pithy token show` that puts a
+ * minted value on a terminal deliberately, is what this is for.
+ *
+ * The write goes through {@link writeMintedToken}, which reads its own base through
+ * {@link mintedTokensBase} — so this answer is never anybody's merge base, and the type says so, since
+ * a `MintedTokens` is not a {@link MergeBase} of one (#219).
+ *
+ * **Which of the two this is, stated, because that was the ambiguity that cost four files.** This is the
+ * one that may answer `{}`, and it does so for a file that is not there and for one that nothing can be
+ * made of at all — it will not parse, or it parses and is not a document of minted tokens. A reader has
+ * nothing to destroy, and a caller reading a token back gets an honest "nothing here" rather than a
+ * command that will not run.
+ *
+ * **Two failures are refusals even here, and they are the file's rather than the caller's.** A file that
+ * is there and will not open, because "absent" is a claim about the filesystem that this read cannot
+ * make ({@link readOptionalFile}, #190). And a value that parsed to something that is not a record,
+ * because that is a claim about what is in the file — something is here, this is not what it is
+ * ({@link requireRecord}, #209).
+ */
+export async function readMintedTokens(path: string): Promise<MintedTokens> {
+  const source = await readOptionalFile(path, {
+    unreadable: ({ code, cause }) =>
+      new ConflictError(
+        {
+          message: `Cannot update ${path}: Pithy could not read what is already in it.`,
+          action:
+            "Fix the file's permissions, or move it aside, and run the command again. Pithy won't rewrite a credential file it could not read.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+  });
+  if (source === null) return {};
+  const value = safeJson(source);
+  if (value === undefined) return {};
+  const document = requireRecord(path, value, {
+    notARecord: ({ found }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it holds ${found}, not a document of minted tokens.`,
+        action:
+          "Restore it to a JSON object keyed by environment, or move it aside, and run the command again. Pithy won't rewrite a credential file it could not make sense of.",
+        detail: `${MINTED_TOKENS_FILE_NAME} at ${path} parsed to ${found}`,
+      }),
+  });
+  const parsed = MintedTokens.safeParse(document);
+  return parsed.success ? parsed.data : {};
+}
+
+/** `JSON.parse` that answers `undefined` rather than throwing — this file is hand-edited. */
+function safeJson(source: string): unknown {
+  try {
+    return JSON.parse(source);
+  } catch {
+    return undefined;
+  }
+}

package/src/tokens/sinks.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareNotConfiguredError } from "@pithy-sh/cloudflare/src/client/errors";
+import type { TokenStore } from "@pithy-sh/cloudflare/src/tokens/profiles";
+import type { StatePathOptions } from "../notifier/state";
+import { writeMintedToken } from "./mintedTokens";
+
+/** Where a minted token landed — the store and a human location string. Never carries the value. */
+export interface SinkTarget {
+  sink: TokenStore;
+  /** A human location for output: a filename, "CF Secrets Store", or the ephemeral note. No secret value. */
+  location: string;
+}
+
+/**
+ * What a sink write needs: the project dir + env to target, the two names a value can be stored under,
+ * and a Secrets Store writer.
+ *
+ * The two names are deliberately separate. They were one string, and that string was doing two jobs
+ * with opposite requirements: a **variable key** in a file this checkout owns, and an **entry name** in
+ * one flat namespace shared by every project in the Cloudflare account. Only the second needs a project
+ * scope — and scoping the first would rename `CF_TOKEN_CI_SYSTEM` and break every pipeline reading it.
+ */
+export interface SinkContext {
+  /**
+   * The project's name, from the root `pithy.config.ts` via `requireProjectName` — never a directory.
+   * It keys `<config>/<project>/`, which is where a minted token goes now that nothing is written into
+   * the checkout (#182).
+   */
+  project: string;
+  env: string;
+  /**
+   * The `.dev.vars` variable key — a local environment-variable name, never project-scoped. This is
+   * what CI reads, so it stays exactly as the profile declares it.
+   */
+  secretName: string;
+  /**
+   * The CF Secrets Store entry name — project-scoped (`tokenStoreEntryName`). The store is one flat
+   * account-wide namespace, so this name is the only partition between two projects' entries: an
+   * unscoped one would silently overwrite another project's live credential.
+   */
+  storeEntryName: string;
+  /** Writes a value to the CF Secrets Store; required for the `secrets-store` sink. */
+  putSecret?: (name: string, value: string) => Promise<void>;
+  /** Where the Pithy config directory is. Defaults to the real one; a seam so a test writes its own. */
+  paths?: StatePathOptions;
+}
+
+/**
+ * Write a minted token value to its store and report where it landed — never the value. `ephemeral`
+ * persists nothing (the caller uses the value in-process); `dev-vars` records the token's **variable
+ * key** under its environment in `<config>/<project>/tokens.json`, for an operator to read out and paste
+ * into CI — **no command consumes that file**, and saying otherwise cost an issue (#224);
+ * `secrets-store` writes it to the CF Secrets Store under the project-scoped **entry name**, for a Worker
+ * to read via its binding.
+ *
+ * **The `dev-vars` sink writes nothing inside the project directory, for any environment (#182).** It
+ * used to write `.dev.vars` for dev and `.dev.vars.<env>` for everything else — so a production mint put
+ * a live production Cloudflare token in the checkout, gitignored but reachable by `npm pack`, which does
+ * not consult `.gitignore` when `files` is set (#145). The store name stays `dev-vars` because it is a
+ * public flag value and renaming it would break every documented invocation; what changed is where it
+ * puts the value. See {@link writeMintedToken}.
+ */
+export async function writeTokenToSink(store: TokenStore, value: string, context: SinkContext): Promise<SinkTarget> {
+  switch (store) {
+    case "ephemeral":
+      return { sink: store, location: "(ephemeral — not written)" };
+    case "dev-vars": {
+      const path = await writeMintedToken(context.project, context.env, context.secretName, value, context.paths ?? {});
+      return { sink: store, location: path };
+    }
+    case "secrets-store": {
+      if (!context.putSecret) {
+        throw new CloudflareNotConfiguredError({
+          message: "No CF Secrets Store is configured for the secrets-store store.",
+          action: "Run pithy add secrets to record SECRETS_STORE_ID, or mint with --store dev-vars.",
+        });
+      }
+      await context.putSecret(context.storeEntryName, value);
+      return { sink: store, location: "CF Secrets Store" };
+    }
+  }
+}