@pithy-sh/cloudflare 0.3.0 → 0.4.0

package/src/client/errors.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import { PithyError, UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+import { PithyError, UpstreamError, UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
 import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
 import { MAX_WORKFLOW_STEP_TEXT } from "@pithy-sh/core/src/workflow/stepMessage";
 import type { z } from "zod";
@@ -196,7 +196,7 @@ const ACCOUNT_PERMISSIONS: Record<string, string> = {
 };
 
 /**
- * Run a Cloudflare SDK call and turn any failure into a `CloudflareRequestError`, preserving the
+ * Run a Cloudflare SDK call and turn any failure into a typed refusal, preserving the
  * original error as `cause` and its message as internal `detail`. `operation` names the call for
  * the audit trail (`"KV get for key 'x'"`). A `PithyError` already in flight (e.g. a
  * not-configured guard) passes through untouched — only foreign throws get wrapped.
@@ -267,8 +267,11 @@ export async function cloudflareRequest<T>(
  * translating client can render them under the error code. "Add this grant, then re-run" names a
  * console the operator is sitting in front of, so it is an `action`. The raw body stays `detail`.
  *
- * The code stays `cloudflare/request_failed` at 502: a dedicated sibling of `core/upstream_failed`,
- * already the upstream class CLAUDE.md asks for, and pinned by `core`'s payload test.
+ * **The code is keyed on the status, because a retry policy reads it and nothing else can.** See
+ * {@link isTransientStatus}. A refusal Cloudflare answered with a 4xx stays `cloudflare/request_failed`
+ * at 502 — a dedicated sibling of `core/upstream_failed`, already the upstream class CLAUDE.md asks
+ * for, and pinned by `core`'s payload test. The words are composed the same way either side of that
+ * branch, so only the two machine-readable fields differ.
  *
  * **The message is one line, and that is a kit-wide rule this had to learn the hard way.** Round one
  * of #534 made it a small document — problem line, `errors[]` indented beneath, action last — which
@@ -299,20 +302,81 @@ export function cloudflareRefusal(args: {
   detail: string;
   /** The original throw. */
   cause?: unknown;
-}): CloudflareRequestError {
+}): PithyError {
   // Sliced here for `permissionAction`; `cloudflareSaid` bounds what it is given for itself, so a call
   // site reaching it directly cannot exceed the same limit by arriving from somewhere else.
   const shown = args.apiErrors.slice(0, MAX_API_ERRORS);
   const said = cloudflareSaid(args.problem, shown);
-  return new CloudflareRequestError(
-    {
-      message: said.message,
-      action: permissionAction(shown, args.status, args.permission),
-      params: said.params,
-      detail: args.detail,
-    },
-    { cause: args.cause },
-  );
+  const refusal = {
+    message: said.message,
+    action: permissionAction(shown, args.status, args.permission),
+    params: said.params,
+    detail: args.detail,
+  };
+  if (isTransientStatus(args.status) || isConnectionFailure(args.cause)) {
+    return new UpstreamError(refusal, { cause: args.cause });
+  }
+  return new CloudflareRequestError(refusal, { cause: args.cause });
+}
+
+/**
+ * Whether the status Cloudflare answered under means "ask again" rather than "this request is wrong".
+ *
+ * **The classification lives here because here is where the status is still in hand.** Everything a
+ * refusal crosses afterwards — a durable step record, a `--json` line, a retry policy — sees the
+ * `code` and nothing else, so a fault that is worth retrying has to say so in the code at the moment
+ * it is raised. `@pithy-sh/secrets`' `secretsWorkflowRetry` lists `core/upstream_failed` and
+ * `core/upstream_timeout` and treats everything absent as terminal; with every non-timeout failure
+ * arriving as `cloudflare/request_failed`, a 503 on the at-rest master-key write ended the rotation
+ * instance permanently, in the one state where ending it is expensive.
+ *
+ * **It is keyed here and not relaxed in the policy, and the difference is a revoked token.** Making
+ * the whole `cloudflare/*` family retryable would loop a 403 forever at whatever cadence the Workflow
+ * sleeps on, and nothing would ever say why. 4xx is Cloudflare answering and refusing — the same call
+ * refuses again — so it stays terminal, and CLAUDE.md §Errors is what says the other half belongs to
+ * the upstream pair: a failure in something we do not control is never a code that says we broke.
+ *
+ * 5xx is every server-side status, Cloudflare's own `52x` family included; `429` is rate limiting,
+ * which is the transient failure by definition. The timeout statuses never reach here — `isTimeout`
+ * claims 408, 504 and 524 first, and they are the 504 half of the same pair.
+ *
+ * **A statusless failure is not covered here, and deliberately so (#647 review).** A connection that reset
+ * mid-write is genuinely transient and ending a rotation on one is expensive — but "carries no status" is
+ * far wider than "the network faltered". A `TypeError` raised in our own request builder carries no status
+ * either, and a predicate that called it transient would retry a code defect on the Workflow's own cadence,
+ * forever, silently. `errors.test.ts` pins that: a throw that never reached Cloudflare stays terminal.
+ * {@link isConnectionFailure} names the narrow case instead, the way {@link statesTimeout} already does.
+ */
+function isTransientStatus(status: number | undefined): boolean {
+  return status !== undefined && (status === 429 || status >= 500);
+}
+
+/**
+ * The producer names for "the connection did not hold", as distinct from "out of time" and from a defect
+ * in our own code.
+ *
+ * Duck-typed by name and `code`, for the reason {@link TIMEOUT_NAMES} gives: the SDK is one producer and
+ * `fetch` is another, and an `instanceof` across two copies of the SDK answers false.
+ */
+const CONNECTION_NAMES = new Set(["APIConnectionError", "FetchError"]);
+const CONNECTION_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET"]);
+
+/**
+ * Whether a failure is a connection that did not hold — a reset, a refused socket, a name that would not
+ * resolve. Cloudflare never answered, so nothing was refused, and the next attempt may well succeed.
+ *
+ * Narrow on purpose. This is the half of "no status" that is genuinely worth another attempt; everything
+ * else with no status stays terminal, so a defect in our own code still stops rather than looping.
+ */
+function isConnectionFailure(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current !== null && typeof current === "object"; depth++) {
+    const { name, code } = current as { name?: unknown; code?: unknown };
+    if (typeof name === "string" && CONNECTION_NAMES.has(name)) return true;
+    if (typeof code === "string" && CONNECTION_CODES.has(code)) return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
 }
 
 /**

package/src/secrets/secretsStoreManager.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { JsonDate } from "@pithy-sh/core/src/data/codecs";
-import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
 import { z } from "zod";
 import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors";
 import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
@@ -22,10 +22,46 @@ export const CfSecretEntry = z
     status: z.enum(["pending", "active", "deleted"]).describe("The secret's lifecycle status in the store."),
     created: JsonDate.describe("When the secret was created (ISO string on the wire, Date in app)."),
     modified: JsonDate.describe("When the secret was last modified (ISO string on the wire, Date in app)."),
+    comment: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "Freeform text Cloudflare stores beside the value and returns on list and get. The one field of an entry a write sets and a read answers, so it is the only REST-readable fact *about* a value — never key material, and never a substitute for reading the value through its binding. Nullable **and** optional because the live API returns an explicit `null` for an entry nothing annotated, not an absent key: declared `.optional()` alone, every list against a store holding one un-annotated entry failed its own schema and threw `cloudflare/invalid_response`, which took `entriesNamed` and therefore the rotation's edit-only write with it. Found against a real store, not a mock (#647).",
+      ),
   })
   .describe("A single Cloudflare Secrets Store secret's metadata (never its plaintext value).");
 export type CfSecretEntry = z.output<typeof CfSecretEntry>;
 
+/** What {@link CloudflareSecretsStoreManager.createSecretIfAbsent} did — see it for each value. */
+export type CreateSecretOutcome = "created" | "present" | "unconfirmed";
+
+/** Oldest first, the smaller id breaking a tie — one order whoever asks, so two readers never disagree. */
+function byAge(a: CfSecretEntry, b: CfSecretEntry): number {
+  return a.created.getTime() - b.created.getTime() || a.id.localeCompare(b.id);
+}
+
+/**
+ * A `deleted` entry is not there (#643); a `pending` one is, since creating over it would duplicate it.
+ * Cloudflare lists the three statuses without saying what each means, and a deleted entry is the one
+ * reading that cannot be "there".
+ */
+function isLive(entry: CfSecretEntry): boolean {
+  return entry.status !== "deleted";
+}
+
+/**
+ * The `comment` a write sends, or no such field at all when the caller passed none.
+ *
+ * Omitted rather than sent empty, so a write with no comment is byte-identical to what this manager
+ * sent before the field existed — and so a caller that has nothing to say cannot blank an annotation
+ * somebody else wrote. The comment is a plain string here on purpose: what belongs in one is
+ * `@pithy-sh/secrets`' question, and the codec lives where it is read rather than where it is posted.
+ */
+function commentField(comment: string | undefined): { comment?: string } {
+  return comment === undefined ? {} : { comment };
+}
+
 /** Config for the Secrets Store manager: the shared client config plus the store it targets. */
 export interface SecretsStoreManagerConfig extends CloudflareManagerConfig {
   /** The CF Secrets Store id (the REST API addresses stores by id). */
@@ -73,11 +109,20 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
    * update leaves the prior value intact and bound — there is no window where the secret is absent
    * from the store (which, for a secret like the master encryption key, is a platform-level outage).
    * Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+   *
+   * **It upserts, and at a name nothing reads that is the whole problem.** A caller replacing a value
+   * that must already exist wants {@link updateExistingSecret}: here a stale or misspelled name finds
+   * nothing, creates an entry, and answers 200 — leaving live key material at an address no binding
+   * resolves while the value the caller meant to replace goes on being served. This one is for a
+   * caller that genuinely means either branch.
+   *
+   * `comment` is the non-secret text written beside the value, and the only thing about a value REST
+   * can read back. Omit it and whatever comment is on the entry is left exactly as it stands.
    */
-  async putSecret(name: string, value: string): Promise<void> {
+  async putSecret(name: string, value: string, comment?: string): Promise<void> {
     const existing = await this.findByName(name);
     if (!existing) {
-      await this.createSecret(name, value);
+      await this.createSecret(name, value, comment);
       return;
     }
 
@@ -87,8 +132,102 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
         store_id: this.storeId,
         value,
         scopes: [...DEFAULT_SCOPES],
+        ...commentField(comment),
+      }),
+    );
+  }
+
+  /**
+   * Create a secret only if no entry of that name is there, and say what happened — never "somebody else did"
+   * when this call cannot know that.
+   *
+   * - `created` — this call's create landed, and no older entry of the name exists beside it.
+   * - `present` — an entry of the name was there before this call, or appeared beside this one's and is older;
+   *   in the second case this call's own entry is deleted, so exactly one entry of the name remains.
+   * - `unconfirmed` — the create threw, and an entry of the name is there now. It may be this call's own, landed
+   *   server-side before the response was lost, or another run's. Nothing can tell which (F1 of #643's review), so
+   *   the answer says so rather than guess, and a caller must not make correctness depend on who created it.
+   *
+   * **Never an overwrite, even in a race (#643)**, and **never reliant on the store refusing a duplicate name**:
+   * Cloudflare does not document that it does. So after a create lands, the entries of that name are listed, and
+   * if another is older this one is the loser and removes itself. The oldest wins, deterministically, whichever
+   * run looks. A failure with no entry there afterwards — an outage, a refused token — is thrown as it came.
+   */
+  async createSecretIfAbsent(name: string, value: string, comment?: string): Promise<CreateSecretOutcome> {
+    if (await this.findByName(name)) return "present";
+    let ownId: string | undefined;
+    try {
+      ownId = await this.createSecret(name, value, comment);
+    } catch (error) {
+      if (await this.findByName(name)) return "unconfirmed";
+      throw error;
+    }
+    const oldest = (await this.entriesNamed(name))[0];
+    if (oldest === undefined || ownId === undefined || oldest.id === ownId) return "created";
+    // Another run's entry of the same name is older: it is the one that stands.
+    await cloudflareRequest(`delete duplicate secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.delete(ownId as string, {
+        account_id: this.accountId,
+        store_id: this.storeId,
+      }),
+    );
+    return "present";
+  }
+
+  /**
+   * Write a value to an entry that must already be there, refusing to create one.
+   *
+   * **The verb that exists because {@link putSecret} upserts.** A put addressed to a name nothing reads
+   * — a composed name gone stale, a misspelled binding, an environment segment that never got
+   * substituted — finds no entry, creates one, and answers 200. The caller hears success, the value it
+   * meant to replace is untouched and still bound, and an orphan entry nobody reads sits in the store
+   * holding live key material. That is how a sibling codebase lost an environment's secrets: the
+   * master-key envelope went to a name the `SECRETS_ENCRYPTION_KEYS` binding does not resolve, every
+   * row was re-encrypted under the new key, and the binding kept serving the old one. Nothing returned
+   * an error, anywhere.
+   *
+   * So the create branch is removed rather than guarded. A caller replacing a value has already
+   * asserted the entry exists — it is bound, something reads it — and where that assertion is false the
+   * honest answer is a refusal before any write, not a second entry. {@link createSecretIfAbsent}
+   * establishes a secret, this replaces one, and `putSecret` stays for a caller that means either.
+   *
+   * **Two live entries of one name is a refusal too, and the same one in spirit.** The oldest wins
+   * everywhere else here, which is right for a create that raced. It is wrong for a replace: editing
+   * one of two is a coin toss over which value the binding goes on serving. The store is ambiguous, so
+   * the caller is told, before anything is written.
+   *
+   * Name-addressed rather than id-addressed, deliberately: the name is what a caller composes and what
+   * a binding resolves, so addressing by it keeps the misaddressing this verb exists to catch inside
+   * the one thing that can catch it. Returns the entry id written, so a caller reading back afterwards
+   * can assert it is looking at the same address. `comment` is written beside the value when given.
+   */
+  async updateExistingSecret(name: string, value: string, comment?: string): Promise<string> {
+    const named = await this.entriesNamed(name);
+    const target = named[0];
+    if (!target) {
+      throw new NotFoundError({
+        message: `Secret '${name}' is not in the store, so there is nothing to update.`,
+        action: "Run `pithy secrets provision` to establish the entry, then run this again.",
+        detail: `update secret ${name}: no live entry of that name, and this verb never creates one`,
+      });
+    }
+    if (named.length > 1) {
+      throw new ConflictError({
+        message: `Secret '${name}' names ${named.length} live entries in the store, so a replacement is ambiguous.`,
+        action: "Delete the entries nothing binds from the Secrets Store in the Cloudflare dashboard, then re-run.",
+        detail: `update secret ${name}: ${named.map((entry) => entry.id).join(", ")}`,
+      });
+    }
+    await cloudflareRequest(`update secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.edit(target.id, {
+        account_id: this.accountId,
+        store_id: this.storeId,
+        value,
+        scopes: [...DEFAULT_SCOPES],
+        ...commentField(comment),
       }),
     );
+    return target.id;
   }
 
   /** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
@@ -150,6 +289,23 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
     });
   }
 
+  /**
+   * Every live entry carrying this name, oldest first.
+   *
+   * **The plural is the point.** Cloudflare does not document that the store refuses a duplicate name,
+   * and #643 established that it does not — so "the entry named X" is a claim rather than a given. A
+   * caller whose correctness depends on there being exactly one checks `length` here and says what it
+   * wants done when the store disagrees; {@link findByName} is the answer for a caller that only needs
+   * the entry the rest of this manager would act on.
+   *
+   * **A `deleted` entry is not one** (#643): Cloudflare lists a secret's lifecycle status as `pending`,
+   * `active` or `deleted` without saying what each means, and a deleted entry is the one reading that
+   * cannot be "there". `pending` is taken as there, since creating over it would duplicate it.
+   */
+  async entriesNamed(name: string): Promise<CfSecretEntry[]> {
+    return (await this.listSecrets()).filter((entry) => entry.name === name && isLive(entry)).sort(byAge);
+  }
+
   /** Whether a secret with the given name currently exists in the store. */
   async exists(name: string): Promise<boolean> {
     return (await this.findByName(name)) !== undefined;
@@ -160,18 +316,30 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
     return { storeId: this.storeId, accountId: this.accountId };
   }
 
-  /** Create a single secret with the default scopes. */
-  private async createSecret(name: string, value: string): Promise<void> {
-    await cloudflareRequest(`create secret ${name}`, () =>
-      this.getClient().secretsStore.stores.secrets.create(this.storeId, {
+  /** Create a single secret with the default scopes, and return the id Cloudflare gave it when it says one. */
+  private async createSecret(name: string, value: string, comment?: string): Promise<string | undefined> {
+    return cloudflareRequest(`create secret ${name}`, async () => {
+      const response: unknown = await this.getClient().secretsStore.stores.secrets.create(this.storeId, {
         account_id: this.accountId,
-        body: [{ name, value, scopes: [...DEFAULT_SCOPES] }],
-      }),
-    );
+        body: [{ name, value, scopes: [...DEFAULT_SCOPES], ...commentField(comment) }],
+      });
+      // The SDK hands back a page of what was created. Read defensively: an id is a convenience here, and a
+      // response without one leaves `createSecretIfAbsent` answering `created` as it would have before.
+      const items = (response as { result?: unknown })?.result ?? response;
+      if (!Array.isArray(items)) return undefined;
+      for (const created of items as { id?: unknown; name?: unknown }[]) {
+        if (typeof created?.id === "string" && created.name === name) return created.id;
+      }
+      return undefined;
+    });
   }
 
+  /**
+   * The entry of this name every verb here acts on, or `undefined`. Of several entries of one name, the
+   * oldest — which is the one {@link createSecretIfAbsent} leaves standing. See {@link entriesNamed} for
+   * why there can be several, and for what counts as being there at all.
+   */
   private async findByName(name: string): Promise<CfSecretEntry | undefined> {
-    const all = await this.listSecrets();
-    return all.find((entry) => entry.name === name);
+    return (await this.entriesNamed(name))[0];
   }
 }

package/src/test-utils/fixtures.ts

@@ -202,6 +202,13 @@ export const LIVE_FIXTURES = {
     consequence: "Turnstile sign-in gating on a workers.dev hostname (#84) skips.",
     doc: "docs/FIXTURES.md#turnstile-widget",
   },
+  "workers-route-zone": {
+    name: "workers-route-zone",
+    keys: ["WORKERS_ROUTE_ZONE"],
+    shape: "credential",
+    consequence: "The route-scoped CI token round trip (#651) skips: nothing proves a minted token can attach a route.",
+    doc: "docs/FIXTURES.md#workers-route-zone",
+  },
 } as const satisfies Record<string, LiveFixture>;
 
 /** Every declared fixture name. A typo is a type error rather than a silently skipped suite. */

package/src/tokens/accountTokensManager.ts

@@ -56,6 +56,36 @@ export function accountResource(accountId: string): Record<string, string> {
   return { [`com.cloudflare.api.account.${accountId}`]: "*" };
 }
 
+/**
+ * The resource scope for a **zone-level** policy: one `com.cloudflare.api.account.zone.<id>` key per
+ * zone, each `"*"`.
+ *
+ * Every zone is named individually, and that is the point (#651). Cloudflare also spells "every zone in
+ * this account" — `{ "com.cloudflare.api.account.<id>": { "com.cloudflare.api.account.zone.*": "*" } }` —
+ * and a `ci-system` token must never carry it: the credential a pipeline runs under gets the zones the
+ * project's own declared domains sit in and no others, so an account holding a customer's zone beside
+ * this project's is not one compromise away from both. De-duped, because two environments and two
+ * Workers routinely share one zone.
+ */
+export function zoneResources(zoneIds: readonly string[]): Record<string, string> {
+  const resources: Record<string, string> = {};
+  for (const zoneId of zoneIds) resources[`${ZONE_RESOURCE_PREFIX}${zoneId}`] = "*";
+  return resources;
+}
+
+/**
+ * Read an explicit `null` as "the response did not say", keeping the field **optional** rather than
+ * required-and-undefined.
+ *
+ * Every optional field decoded off a token list goes through this, and it is load-bearing rather than
+ * defensive (#651): `listTokens` decodes each entry with `safeParse` and drops what fails, so one `null`
+ * where a schema wanted a value makes a live token invisible to `findTokenByName` — and the next roll
+ * mints a *second* credential of the same name beside the first, with nothing saying so.
+ */
+function nullAsAbsent<T extends z.ZodTypeAny>(schema: T) {
+  return z.preprocess((value) => value ?? undefined, schema);
+}
+
 /**
  * A permission group available to account-owned tokens, as returned by the permission-groups list.
  * Only the id and name matter for resolution — the manager maps a requested name to its id.
@@ -78,21 +108,83 @@ export const MintedAccountToken = z
     id: z.string().describe("The CF-assigned token id, used to address the token for get/delete."),
     value: z.string().describe("The secret token value — returned once on create, never again. Store immediately."),
     name: z.string().optional().describe("The token name as registered with Cloudflare."),
-    status: z.enum(["active", "disabled", "expired"]).optional().describe("The token's lifecycle status."),
+    status: nullAsAbsent(
+      z
+        .enum(["active", "disabled", "expired"])
+        .describe("The lifecycle state Cloudflare holds for the token.")
+        .optional(),
+    ).describe("The token's lifecycle status."),
   })
   .describe("A newly created account-owned API token, including its one-time secret value.");
 export type MintedAccountToken = z.output<typeof MintedAccountToken>;
 
+/**
+ * One access policy on an existing token, as the token list returns it.
+ *
+ * **Every field is `nullish`, and that is load-bearing rather than defensive.** `listTokens` decodes
+ * each entry with `safeParse` and drops what fails, so a single `null` where this expected a value
+ * makes a live token invisible to `findTokenByName` — and the next roll mints a *second* credential of
+ * the same name beside the first, with nothing saying so (#651).
+ */
+export const AccountTokenPolicy = z
+  .object({
+    effect: nullAsAbsent(
+      z.enum(["allow", "deny"]).describe("Allow or deny, as Cloudflare states it on the policy.").optional(),
+    ).describe(
+      "Whether this policy grants its groups on its resources or refuses them. Cloudflare evaluates explicit denies first, so a policy naming a group is not evidence the token may use it. Absent is an allow, which is the API's own default.",
+    ),
+    permission_groups: nullAsAbsent(
+      z
+        .array(
+          z
+            .object({ id: z.string().describe("The permission-group id this policy grants.") })
+            .describe("One permission group referenced by a live token's policy, by the id the account assigned it."),
+        )
+        .optional(),
+    ).describe(
+      "The permission groups this policy grants, by id. **Read together with `resources`, never apart**: a zone resource says which zone a policy is about and nothing about what it may do there, so coverage judged from resources alone reads a zone-scoped `Zone Read` as a route grant. Absent has not said the policy grants nothing.",
+    ),
+    resources: z
+      .record(z.string(), z.unknown())
+      .describe(
+        "The resource scope keys this policy applies to — `com.cloudflare.api.account.<id>` for an account policy, `com.cloudflare.api.account.zone.<id>` for a zone one, and either nested inside the other. Read to tell what a live token is scoped to; the values are not interpreted beyond that nesting.",
+      ),
+  })
+  .describe("One access policy on an existing token: the groups it grants, and the resources it grants them on.");
+export type AccountTokenPolicy = z.output<typeof AccountTokenPolicy>;
+
 /**
  * An existing account-owned token's metadata, as returned by list/get. No `value` — Cloudflare never
- * returns a token's secret after creation — so this is only enough to find a token by name and
- * address it for deletion.
+ * returns a token's secret after creation — so this is only enough to find a token by name, report on
+ * it, and address it for deletion.
+ *
+ * **It reads what it uses and nothing more.** It briefly carried `expires_on`, `not_before` and
+ * `condition` so a re-scoping mint could resend them; that mint is gone (see {@link
+ * CloudflareAccountTokensManager.rollToken}), and reading a field only to hand it straight back is a
+ * field that can be read wrong.
  */
 export const AccountTokenSummary = z
   .object({
     id: z.string().describe("The CF-assigned token id, used to address the token for deletion."),
     name: z.string().describe("The token name, the key callers match on for idempotent re-mint."),
-    status: z.enum(["active", "disabled", "expired"]).optional().describe("The token's lifecycle status."),
+    status: nullAsAbsent(
+      z
+        .enum(["active", "disabled", "expired"])
+        .describe("The lifecycle state Cloudflare holds for the token.")
+        .optional(),
+    ).describe(
+      "The token's lifecycle status. Reported, because a `disabled` or `expired` token cannot attach a route however its policies read. `nullish` for the reason {@link AccountTokenPolicy} gives.",
+    ),
+    policies: nullAsAbsent(z.array(AccountTokenPolicy).optional())
+      // **An undecodable policy set costs the scope, never the token.** `resources` is required inside a
+      // policy, so one shape Cloudflare returns that this does not model would fail the whole entry —
+      // `listTokens` drops what fails, `findTokenByName` answers null, and the roll mints a *second* live
+      // credential of the same name beside the first. A token's identity does not depend on its policies
+      // being readable, and "the scope could not be read" is a state the reporting already has a word for.
+      .catch(undefined)
+      .describe(
+        "The token's access policies, when the list response carries them. **A live token's own scope is the record of how it was minted** — it is how a `ci-system` token minted before zone-scoped routes (#651) can be told from one minted after, without reading the token record (which needs a grant these least-privilege tokens deliberately lack). Absent and empty are different facts: a response that says nothing means the scope could not be read, never that the token has none.",
+      ),
   })
   .describe("An existing account-owned API token's metadata (never its secret value).");
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
@@ -230,7 +322,7 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
         throw new CloudflareNotConfiguredError(
           {
             message: said.message,
-            action: "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.",
+            action: delegationAction(permissions),
             params: said.params,
             detail: `mint account token '${name}': ${messageOf(error)}`,
           },
@@ -365,6 +457,18 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
    * Either way the caller gets a usable secret to store — the idempotent path for a credential that
    * lives in the Secrets Store, since Cloudflare never returns a token's existing secret. Mirrors the
    * dashboard's roll-or-create.
+   *
+   * **A roll never changes the policy set, and that is a decision rather than an omission (#651).** It
+   * briefly did: `pithy token list` tells an adopter their CI token predates zone-scoped routes, and
+   * re-scoping here made the remedy one command. But Cloudflare's token update is a full
+   * representation, so doing it meant every mint had to resend the whole token correctly — `condition`,
+   * `expires_on`, `not_before`, `status` — and three review rounds each found a new way that went
+   * wrong: a cleared IP allowlist, a re-enabled disabled token, a `null` that hid the token and minted a
+   * duplicate beside it.
+   *
+   * {@link mintToken} plus a delete is what actually re-scopes, and `pithy token rotate` has always been
+   * exactly that. So the remedy names rotate, and this stays the one thing it can be relied on to be:
+   * a new secret on the same token, with nothing else touched.
    */
   async rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken> {
     const existing = await this.findTokenByName(name);
@@ -374,6 +478,29 @@ export class CloudflareAccountTokensManager extends CloudflareManager {
   }
 }
 
+/**
+ * The remedy line for a 403 on a mint, which depends on **what was being delegated**.
+ *
+ * Cloudflare only lets a token create a token whose permissions it already holds, so a mint carrying a
+ * zone-scoped policy (#651's Workers Routes Write, on the project's declared zones) fails for a
+ * bootstrap token that holds every account grant and no zone one. Telling that operator to grant
+ * "Account API Tokens Write" is true, useless, and sends them to a checkbox that is already ticked.
+ *
+ * So the zone half is named when a zone policy is in the set, and only then.
+ */
+function delegationAction(permissions: readonly TokenPermission[]): string {
+  const base = "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.";
+  const zoneScoped = permissions.filter((permission) =>
+    Object.keys(permission.resources).some((key) => key.startsWith(ZONE_RESOURCE_PREFIX)),
+  );
+  if (zoneScoped.length === 0) return base;
+  const groups = [...new Set(zoneScoped.flatMap((permission) => permission.permissionGroupNames))].join(", ");
+  return `${base} It must also already hold what it is delegating: ${groups} on the zones being scoped (Zone → Workers Routes → Edit), because Cloudflare only lets a token create a token whose permissions it has.`;
+}
+
+/** The resource-key prefix every zone-scoped policy is written under. */
+const ZONE_RESOURCE_PREFIX = "com.cloudflare.api.account.zone.";
+
 /** The rolled secret value Cloudflare returns from a value-roll — a non-empty bearer string. */
 const RolledTokenValue = z.string().min(1);
 

package/src/tokens/permissions.ts

@@ -34,16 +34,45 @@ export const PERMISSION_GROUPS = {
   // so `pithy init` and `pithy worker add` can offer the account's real zones instead of asking someone
   // to paste an id off a dashboard page.
   "zone:read": ["Zone Read"],
+  // *Attaching* the route, which is the other half of the sentence above and the half nothing could do
+  // (#651). `pithy deploy` of an environment with a declared domain calls
+  // `POST /zones/<zone>/workers/routes`, and no group in this catalog reached it — a `ci-system` token
+  // met "No access to the specified resource" on the first CI deploy that served a custom domain.
+  //
+  // **Zone-scoped**, and therefore listed in {@link ZONE_SCOPED_PERMISSIONS}: Cloudflare publishes this
+  // group under `com.cloudflare.api.account.zone`, so a token carrying it needs a *zone* resource, and
+  // the account resource every other key here uses grants it nothing. Which zones is not a choice —
+  // it is the project's declared `domains`, resolved at mint time.
+  //
+  // Still not a group that can alter a zone. "Workers Routes Write" writes routes on a zone; changing
+  // the zone itself would be "Zone Write", which this catalog does not have and will not get.
+  "routes:write": ["Workers Routes Write"],
 } as const;
 
 /** A known permission key — one of {@link PERMISSION_GROUPS}'s keys. */
 export type PermissionKey = keyof typeof PERMISSION_GROUPS;
 
+/**
+ * The keys whose Cloudflare permission group is **zone-scoped**: a policy carrying one must name zone
+ * resources (`com.cloudflare.api.account.zone.<id>`), never the account resource.
+ *
+ * A minted token's resources are account-scoped by default, which is why this distinction has to be
+ * stated rather than inferred: hand a zone-level group the account resource and Cloudflare accepts the
+ * token and refuses the call, which is exactly the failure #651 opened with. The zones themselves are
+ * never picked by hand — they are the zones the project's declared domains sit in.
+ */
+export const ZONE_SCOPED_PERMISSIONS: readonly PermissionKey[] = ["routes:write"];
+
 /** Narrow an arbitrary string to a {@link PermissionKey}. */
 export function isPermissionKey(key: string): key is PermissionKey {
   return key in PERMISSION_GROUPS;
 }
 
+/** Whether a key's permission group is zone-scoped — see {@link ZONE_SCOPED_PERMISSIONS}. */
+export function isZoneScopedPermission(key: string): boolean {
+  return (ZONE_SCOPED_PERMISSIONS as readonly string[]).includes(key);
+}
+
 /**
  * Resolve permission keys to the CF permission-group display names they grant, de-duped in first-seen
  * order. An unknown key fails with an actionable error naming the valid keys — caught at the CLI/config