@pithy-sh/cloudflare 0.3.1 → 0.4.1

package/dist/tokens/accountTokensManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAkB1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;iBAK8E,CAAC;AAC7G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAO6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;iBAMuD,CAAC;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAKhD;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe1D;IAED,qGAAqG;IAC/F,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAezD;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAE7E;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgDzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,2GAA2G;IACrG,UAAU,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAajD;IAED,oGAAoG;IAC9F,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAYvE;IAED,qCAAqC;IAC/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBtD;IAED;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOrD;IAED;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}
+{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"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"}

package/dist/tokens/accountTokensManager.js

@@ -29,6 +29,34 @@ function accountResource(accountId) {
 	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.
+*/
+function zoneResources(zoneIds) {
+	const resources = {};
+	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(schema) {
+	return z.preprocess((value) => value ?? void 0, 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.
 */
@@ -45,25 +73,44 @@ const MintedAccountToken = z.object({
 	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([
+	status: nullAsAbsent(z.enum([
 		"active",
 		"disabled",
 		"expired"
-	]).optional().describe("The token's lifecycle status.")
+	]).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.");
 /**
+* 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).
+*/
+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.");
+/**
 * 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.
 */
 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([
+	status: nullAsAbsent(z.enum([
 		"active",
 		"disabled",
 		"expired"
-	]).optional().describe("The token's lifecycle status.")
+	]).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()).catch(void 0).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).");
 /**
 * Out-of-Worker control plane for **account-owned** Cloudflare API tokens: mint scoped, least-privilege
@@ -173,7 +220,7 @@ var CloudflareAccountTokensManager = class extends CloudflareManager {
 				const said = cloudflareSaid("The Cloudflare API token is not allowed to create account tokens.", cloudflareApiErrors(error));
 				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)}`
 				}, { cause: error });
@@ -270,6 +317,18 @@ var CloudflareAccountTokensManager = class 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, permissions) {
 		const existing = await this.findTokenByName(name);
@@ -283,6 +342,24 @@ var CloudflareAccountTokensManager = class 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) {
+	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;
+	return `${base} It must also already hold what it is delegating: ${[...new Set(zoneScoped.flatMap((permission) => permission.permissionGroupNames))].join(", ")} 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);
 /** Just the token's name, the piece the account-token actor path needs. */
@@ -302,4 +379,4 @@ function indexByName(groups) {
 	return index;
 }
 //#endregion
-export { AccountTokenSummary, CfPermissionGroup, CloudflareAccountTokensManager, MintedAccountToken, accountResource };
+export { AccountTokenPolicy, AccountTokenSummary, CfPermissionGroup, CloudflareAccountTokensManager, MintedAccountToken, accountResource, zoneResources };

package/dist/tokens/permissions.d.ts

@@ -24,11 +24,24 @@ export declare const PERMISSION_GROUPS: {
     readonly "vectorize:write": readonly ["Vectorize Write"];
     readonly "ai:read": readonly ["Workers AI Read"];
     readonly "zone:read": readonly ["Zone Read"];
+    readonly "routes:write": readonly ["Workers Routes Write"];
 };
 /** 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 declare const ZONE_SCOPED_PERMISSIONS: readonly PermissionKey[];
 /** Narrow an arbitrary string to a {@link PermissionKey}. */
 export declare function isPermissionKey(key: string): key is PermissionKey;
+/** Whether a key's permission group is zone-scoped — see {@link ZONE_SCOPED_PERMISSIONS}. */
+export declare function isZoneScopedPermission(key: string): boolean;
 /**
  * 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/dist/tokens/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/tokens/permissions.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,YAAG,SAAS;aAIrB,UAAU,YAAG,UAAU;aACvB,eAAe,YAAG,uBAAuB;aACzC,cAAc,YAAG,oBAAoB;aACrC,eAAe,YAAG,qBAAqB;aACvC,eAAe,YAAG,2BAA2B;aAC7C,UAAU,YAAG,0BAA0B;aACvC,SAAS,YAAG,yBAAyB;aACrC,UAAU,YAAG,0BAA0B;aACvC,gBAAgB,YAAG,gBAAgB;aACnC,iBAAiB,YAAG,iBAAiB;aACrC,SAAS,YAAG,iBAAiB;aAK7B,WAAW,YAAG,WAAW;CACjB,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/tokens/permissions.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,YAAG,SAAS;aAIrB,UAAU,YAAG,UAAU;aACvB,eAAe,YAAG,uBAAuB;aACzC,cAAc,YAAG,oBAAoB;aACrC,eAAe,YAAG,qBAAqB;aACvC,eAAe,YAAG,2BAA2B;aAC7C,UAAU,YAAG,0BAA0B;aACvC,SAAS,YAAG,yBAAyB;aACrC,UAAU,YAAG,0BAA0B;aACvC,gBAAgB,YAAG,gBAAgB;aACnC,iBAAiB,YAAG,iBAAiB;aACrC,SAAS,YAAG,iBAAiB;aAK7B,WAAW,YAAG,WAAW;aAazB,cAAc,YAAG,sBAAsB;CAC/B,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,aAAa,EAAqB,CAAC;AAElF,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D"}

package/dist/tokens/permissions.js

@@ -25,12 +25,27 @@ const PERMISSION_GROUPS = {
 	"vectorize:read": ["Vectorize Read"],
 	"vectorize:write": ["Vectorize Write"],
 	"ai:read": ["Workers AI Read"],
-	"zone:read": ["Zone Read"]
+	"zone:read": ["Zone Read"],
+	"routes:write": ["Workers Routes Write"]
 };
+/**
+* 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.
+*/
+const ZONE_SCOPED_PERMISSIONS = ["routes:write"];
 /** Narrow an arbitrary string to a {@link PermissionKey}. */
 function isPermissionKey(key) {
 	return key in PERMISSION_GROUPS;
 }
+/** Whether a key's permission group is zone-scoped — see {@link ZONE_SCOPED_PERMISSIONS}. */
+function isZoneScopedPermission(key) {
+	return ZONE_SCOPED_PERMISSIONS.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
@@ -49,4 +64,4 @@ function resolvePermissionKeys(keys) {
 	return names;
 }
 //#endregion
-export { PERMISSION_GROUPS, isPermissionKey, resolvePermissionKeys };
+export { PERMISSION_GROUPS, ZONE_SCOPED_PERMISSIONS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys };

package/dist/tokens/profiles.d.ts

@@ -95,6 +95,21 @@ export declare function resolveTokenProfiles(capabilities: readonly Capability[]
 export declare function resolveProfile(profiles: Record<string, TokenProfile>, name: string, override?: ProfileOverride): TokenProfile;
 /** Build the account-scoped {@link TokenPermission}s for a set of permission keys — the mint input. */
 export declare function permissionsForKeys(keys: PermissionKey[], accountId: string): TokenPermission[];
+/**
+ * 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 declare function routePermissions(zoneIds: readonly string[]): TokenPermission[];
 /**
  * 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

package/dist/tokens/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/tokens/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAmB,KAAK,aAAa,EAAyB,MAAM,eAAe,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA+C,CAAC;AAE9F,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAe7C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,2GAA2G;IAC3G,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,CAAC;AAKxD,iHAAiH;AACjH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAGtE;AAkCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CActG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,eAAe,GACzB,YAAY,CAgBd;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAI9F"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/tokens/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAmB,KAAK,eAAe,EAAiB,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA+C,CAAC;AAE9F,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAe7C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,2GAA2G;IAC3G,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,CAAC;AAKxD,iHAAiH;AACjH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAGtE;AAkCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CActG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,eAAe,GACzB,YAAY,CAgBd;AAsBD,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAG9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,EAAE,CAG9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAK9F"}

package/dist/tokens/profiles.js

@@ -1,8 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { CloudflareNotConfiguredError } from "../client/errors.js";
-import { accountResource } from "./accountTokensManager.js";
-import { isPermissionKey, resolvePermissionKeys } from "./permissions.js";
+import { accountResource, zoneResources } from "./accountTokensManager.js";
+import { PERMISSION_GROUPS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys } from "./permissions.js";
 //#region src/tokens/profiles.ts
 /** The valid stores, for validating a `--store` flag or a profile's `defaultStore`. */
 const TOKEN_STORES = [
@@ -116,19 +116,60 @@ function resolveProfile(profiles, name, override) {
 		defaultStore: override.store ?? base.defaultStore
 	};
 }
+/**
+* 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, where) {
+	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. */
 function permissionsForKeys(keys, accountId) {
+	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.
+*/
+function routePermissions(zoneIds) {
+	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.
 */
 function profilePermissions(profile, accountId) {
+	assertAccountScoped(profile.permissions, `Token profile "${profile.name}"`);
 	const resources = profile.resources && profile.resources !== "account" ? profile.resources : accountResource(accountId);
 	return [{
 		permissionGroupNames: resolvePermissionKeys(profile.permissions),
@@ -136,4 +177,4 @@ function profilePermissions(profile, accountId) {
 	}];
 }
 //#endregion
-export { CI_SYSTEM_PROFILE, TOKEN_STORES, defineTokenProfile, permissionsForKeys, profilePermissions, resolveProfile, resolveTokenProfiles, tokenSecretName };
+export { CI_SYSTEM_PROFILE, TOKEN_STORES, defineTokenProfile, permissionsForKeys, profilePermissions, resolveProfile, resolveTokenProfiles, routePermissions, tokenSecretName };

package/dist/workers/buildsManager.js

@@ -1,9 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { CloudflareInvalidResponseError, CloudflareRequestError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
+import { CloudflareInvalidResponseError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfRepoConnection } from "./buildsTypes.js";
 import { z } from "zod";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
 //#region src/workers/buildsManager.ts
 /** The Cloudflare REST API v4 base URL. The Builds endpoints live under `/accounts/{id}/builds`. */
 const CF_API_BASE = "https://api.cloudflare.com/client/v4";
@@ -228,12 +229,19 @@ var CloudflareBuildsManager = class 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, code) {
-	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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/cloudflare",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "js-base64": "^3.9.2"
   },
   "peerDependencies": {
-    "@pithy-sh/core": "^0.7.4",
+    "@pithy-sh/core": "^0.8.0",
     "zod": "^4.4.0"
   },
   "devDependencies": {

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;
 }
 
 /**