@pithy-sh/cloudflare 0.3.1 → 0.4.1

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,6 +22,13 @@ 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>;
@@ -29,9 +36,30 @@ export type CfSecretEntry = z.output<typeof CfSecretEntry>;
 /** What {@link CloudflareSecretsStoreManager.createSecretIfAbsent} did — see it for each value. */
 export type CreateSecretOutcome = "created" | "present" | "unconfirmed";
 
-/** The oldest of some entries by creation time, the smaller id breaking a tie — one answer whoever asks. */
-function oldestEntry(entries: readonly CfSecretEntry[]): CfSecretEntry | undefined {
-  return [...entries].sort((a, b) => a.created.getTime() - b.created.getTime() || a.id.localeCompare(b.id))[0];
+/** 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. */
@@ -81,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;
     }
 
@@ -95,6 +132,7 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
         store_id: this.storeId,
         value,
         scopes: [...DEFAULT_SCOPES],
+        ...commentField(comment),
       }),
     );
   }
@@ -115,17 +153,16 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
    * 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): Promise<CreateSecretOutcome> {
+  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);
+      ownId = await this.createSecret(name, value, comment);
     } catch (error) {
       if (await this.findByName(name)) return "unconfirmed";
       throw error;
     }
-    const same = (await this.listSecrets()).filter((entry) => entry.name === name && entry.status !== "deleted");
-    const oldest = oldestEntry(same);
+    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}`, () =>
@@ -137,6 +174,62 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
     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. */
   async deleteSecret(name: string): Promise<void> {
     const existing = await this.findByName(name);
@@ -196,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;
@@ -207,11 +317,11 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
   }
 
   /** 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): Promise<string | undefined> {
+  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.
@@ -225,13 +335,11 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
   }
 
   /**
-   * The entry of this name, or `undefined`. **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. Of several entries of one name, the oldest, which is the one {@link createSecretIfAbsent} leaves standing.
+   * 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 oldestEntry(all.filter((entry) => entry.name === name && entry.status !== "deleted"));
+    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

package/src/tokens/profiles.ts

@@ -3,8 +3,14 @@
 
 import type { Capability, TokenProfileSeam } from "@pithy-sh/core/src/capability/capability";
 import { CloudflareNotConfiguredError } from "../client/errors";
-import { accountResource, type TokenPermission } from "./accountTokensManager";
-import { isPermissionKey, type PermissionKey, resolvePermissionKeys } from "./permissions";
+import { accountResource, type TokenPermission, zoneResources } from "./accountTokensManager";
+import {
+  isPermissionKey,
+  isZoneScopedPermission,
+  PERMISSION_GROUPS,
+  type PermissionKey,
+  resolvePermissionKeys,
+} from "./permissions";
 
 /**
  * Where a minted token's value is written.
@@ -221,17 +227,58 @@ export function resolveProfile(
   };
 }
 
+/**
+ * Refuse a zone-scoped key anywhere a policy is being built **account-scoped**.
+ *
+ * A zone-level permission group handed the account resource is the quiet failure (#651): Cloudflare
+ * mints the token without complaint and then answers "No access to the specified resource" at the call,
+ * which is a CI failure hours later with nothing in it naming the scope. Which zones a token gets is
+ * never a typed choice — it is the project's declared `domains`, resolved at mint time — so a key naming
+ * one in a profile or behind `--permission` is a mistake, and this is where it is caught.
+ */
+function assertAccountScoped(keys: readonly string[], where: string): void {
+  const zoneScoped = keys.filter(isZoneScopedPermission);
+  if (zoneScoped.length === 0) return;
+  throw new CloudflareNotConfiguredError({
+    message: `${where} names zone-scoped permission(s): ${zoneScoped.join(", ")}.`,
+    action:
+      "A zone permission is not chosen by hand — declare the Worker's `domains` in pithy.config.ts and the mint scopes the token to those zones. Remove the key.",
+    detail: `build token policy: ${zoneScoped.join(", ")} cannot take the account resource`,
+  });
+}
+
 /** Build the account-scoped {@link TokenPermission}s for a set of permission keys — the mint input. */
 export function permissionsForKeys(keys: PermissionKey[], accountId: string): TokenPermission[] {
+  assertAccountScoped(keys, "This token");
   return [{ permissionGroupNames: resolvePermissionKeys(keys), resources: accountResource(accountId) }];
 }
 
+/**
+ * The **zone-scoped** policy a project's declared domains require: Workers Routes Write on exactly those
+ * zones, and nothing else.
+ *
+ * This is the second policy on the `ci-system` token, beside the account-scoped one every profile
+ * builds. It exists because `pithy deploy` of an environment with a declared domain calls
+ * `POST /zones/<zone>/workers/routes`, the one deploy step the CI credential could not make (#651) — and
+ * it is a policy of its own rather than a permission on the profile because its resources are zones,
+ * which a profile cannot name: they are resolved from the domains at mint time.
+ *
+ * **Empty for an empty zone list, deliberately.** A project that declares no domain attaches no route,
+ * so it mints exactly the token it minted before this existed. No new permission for a project that
+ * needs none.
+ */
+export function routePermissions(zoneIds: readonly string[]): TokenPermission[] {
+  if (zoneIds.length === 0) return [];
+  return [{ permissionGroupNames: [...PERMISSION_GROUPS["routes:write"]], resources: zoneResources(zoneIds) }];
+}
+
 /**
  * Turn a resolved profile into the {@link TokenPermission}s the account-tokens manager mints from: the
  * profile's permission keys resolved to CF group names, scoped to the account (or the profile's
  * explicit resources). One policy per profile — a token carries exactly the access its profile declares.
  */
 export function profilePermissions(profile: TokenProfile, accountId: string): TokenPermission[] {
+  assertAccountScoped(profile.permissions, `Token profile "${profile.name}"`);
   const resources =
     profile.resources && profile.resources !== "account" ? profile.resources : accountResource(accountId);
   return [{ permissionGroupNames: resolvePermissionKeys(profile.permissions), resources }];

package/src/workers/buildsManager.ts

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
 import { z } from "zod";
 import {
   CloudflareInvalidResponseError,
-  CloudflareRequestError,
   cloudflareApiErrors,
   cloudflareRefusal,
   cloudflareRequest,
@@ -350,12 +350,19 @@ export class CloudflareBuildsManager extends CloudflareManager {
 }
 
 /**
- * Whether a thrown `CloudflareRequestError` carries the given CF error code. Reads the `[cf-codes:…]`
+ * Whether a thrown Cloudflare refusal carries the given CF error code. Reads the `[cf-codes:…]`
  * marker `call()` pins to the front of `detail` (stable across the 2000-char truncation); falls back
  * to a substring scan for errors raised without the structured marker.
+ *
+ * **Narrowed on `PithyError`, not on one subclass of it (#647).** This read used to require a
+ * `CloudflareRequestError`, which was true of every refusal for as long as `cloudflareRefusal` composed
+ * exactly one class. It no longer does: a 429 or a 5xx is now an `UpstreamError`, so that narrowing
+ * would have silently stopped seeing a CF error code the moment Cloudflare answered one under a status
+ * that retries. The code lives in `detail`, which every `PithyError` carries, so the payload is what to
+ * read and the class is not.
  */
 function hasErrorCode(error: unknown, code: number): boolean {
-  if (!(error instanceof CloudflareRequestError)) return false;
+  if (!(error instanceof PithyError)) return false;
   const detail = error.payload.detail ?? "";
   const marker = detail.match(/^\[cf-codes:([\d,]+)\]/);
   if (marker?.[1]) return marker[1].split(",").includes(String(code));