@pithy-sh/cloudflare 0.3.0 → 0.4.0

package/dist/tokens/accountTokensManager.d.ts

@@ -23,6 +23,18 @@ export interface TokenPermission {
  * exact resource key format lives in a single place instead of being hand-spelled per use case.
  */
 export declare function accountResource(accountId: string): Record<string, string>;
+/**
+ * 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 declare function zoneResources(zoneIds: readonly string[]): Record<string, string>;
 /**
  * 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.
@@ -41,26 +53,60 @@ export declare const MintedAccountToken: z.ZodObject<{
     id: z.ZodString;
     value: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
-    status: z.ZodOptional<z.ZodEnum<{
+    status: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>;
+    }>>>;
 }, z.core.$strip>;
 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 declare const AccountTokenPolicy: z.ZodObject<{
+    effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>>;
+    permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>>>;
+    resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+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 declare const AccountTokenSummary: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    status: z.ZodOptional<z.ZodEnum<{
+    status: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>;
+    }>>>;
+    policies: z.ZodCatch<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>>;
+        permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>>>>;
+        resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>>>;
 }, z.core.$strip>;
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
 /**
@@ -153,6 +199,18 @@ export declare 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.
      */
     rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
 }

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":"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;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIhF;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;;;;;;;;;iBAY6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAwBkF,CAAC;AAClH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAuBuD,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;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}

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/dist/workflows/workflowsClient.d.ts

@@ -41,6 +41,12 @@ export declare const WorkflowInstance: z.ZodObject<{
     steps: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
 }, z.core.$strip>;
 export type WorkflowInstance = z.output<typeof WorkflowInstance>;
+/** One deployed Workflow definition — its name and the script that hosts it — from the account's list. */
+export declare const WorkflowDefinition: z.ZodObject<{
+    name: z.ZodString;
+    script_name: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowDefinition = z.output<typeof WorkflowDefinition>;
 /**
  * A client over the Cloudflare Workflows API — the only sanctioned way to reach CF Workflows from
  * outside a Worker (CLAUDE.md: no hand-rolled CF `fetch` outside `@pithy-sh/cloudflare`). The
@@ -58,6 +64,17 @@ export declare class CloudflareWorkflowsClient extends CloudflareManager {
     getServiceType(): string;
     /** Prove reach by listing the account's Workflows; never throws. */
     validateServiceAccess(): Promise<boolean>;
+    /**
+     * Every Workflow definition on the account, validated at the wire boundary. What `pithy feature destroy` reads
+     * to find the Workflows a feature's scripts host, by exact script name (#643).
+     */
+    listWorkflows(): Promise<WorkflowDefinition[]>;
+    /**
+     * Delete a Workflow definition by name, resolving `false` when there was none (#643). Cloudflare's own
+     * reference says this deletes the Workflow and leaves the Worker script alone; whether deleting the script
+     * deletes its Workflows it does not say, so teardown deletes them explicitly rather than rely on either.
+     */
+    deleteWorkflow(workflowName: string): Promise<boolean>;
     /** Create (trigger) a Workflow instance and return its id. */
     createInstance(workflowName: string, params: unknown, instanceId?: string): Promise<string>;
     /** Fetch an instance's status. Returns `null` on a 404 (a just-created instance can briefly lag). */

package/dist/workflows/workflowsClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflowsClient.d.ts","sourceRoot":"","sources":["../../src/workflows/workflowsClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,gGAAgG;AAChG,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD,MAAM,WAAW,+BAAgC,SAAQ,uBAAuB;IAC9E,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;EAawD,CAAC;AAC5F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;iBAqBuE,CAAC;AACrG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAOjE;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;;IAG9D,YAAY,MAAM,EAAE,+BAA+B,EAGlD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oEAAoE;IAC9D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,8DAA8D;IACxD,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhG;IAED,qGAAqG;IAC/F,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBlG;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAChF,OAAO,CAAC,OAAO,CAAC,CAmClB;CACF"}
+{"version":3,"file":"workflowsClient.d.ts","sourceRoot":"","sources":["../../src/workflows/workflowsClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,gGAAgG;AAChG,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD,MAAM,WAAW,+BAAgC,SAAQ,uBAAuB;IAC9E,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;EAawD,CAAC;AAC5F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;iBAqBuE,CAAC;AACrG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,0GAA0G;AAC1G,eAAO,MAAM,kBAAkB;;;iBAKuF,CAAC;AACvH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAOrE;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,SAAQ,iBAAiB;;IAG9D,YAAY,MAAM,EAAE,+BAA+B,EAGlD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oEAAoE;IAC9D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAUnD;IAED;;;;OAIG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU3D;IAED,8DAA8D;IACxD,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhG;IAED,qGAAqG;IAC/F,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBlG;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAChF,OAAO,CAAC,OAAO,CAAC,CAmClB;CACF"}

package/dist/workflows/workflowsClient.js

@@ -28,6 +28,11 @@ const WorkflowInstance = z.object({
 	]).optional().describe("The instance-level failure, present when `status` is `errored` or `terminated`."),
 	steps: z.array(z.unknown()).optional().describe("The instance's steps, each validated where it is read (`stepFailure`). Held as `unknown` here on purpose: the API has four step shapes, this client reads one field of one of them, and a shape nobody anticipated must not turn a failed Workflow into a parse error about the failure report.")
 }).describe("A Cloudflare Workflow instance's status, as returned by the instance-detail endpoint.");
+/** One deployed Workflow definition — its name and the script that hosts it — from the account's list. */
+const WorkflowDefinition = z.object({
+	name: z.string().describe("The Workflow's account-wide name, e.g. `acme-prod-email-send`."),
+	script_name: z.string().describe("The Worker script whose exported class runs the Workflow.")
+}).describe("A Workflow definition on the account, as far as teardown needs one: what it is called and who hosts it.");
 /** Terminal states a poll stops on. */
 const TERMINAL = /* @__PURE__ */ new Set([
 	"complete",
@@ -64,6 +69,37 @@ var CloudflareWorkflowsClient = class extends CloudflareManager {
 			return false;
 		}
 	}
+	/**
+	* Every Workflow definition on the account, validated at the wire boundary. What `pithy feature destroy` reads
+	* to find the Workflows a feature's scripts host, by exact script name (#643).
+	*/
+	async listWorkflows() {
+		return cloudflareRequest("list Workflows", async () => {
+			const out = [];
+			for await (const workflow of this.getClient().workflows.list({ account_id: this.accountId })) {
+				const parsed = WorkflowDefinition.safeParse(workflow);
+				if (!parsed.success) throw new CloudflareInvalidResponseError({ detail: "list Workflows: unexpected shape" });
+				out.push(parsed.data);
+			}
+			return out;
+		});
+	}
+	/**
+	* Delete a Workflow definition by name, resolving `false` when there was none (#643). Cloudflare's own
+	* reference says this deletes the Workflow and leaves the Worker script alone; whether deleting the script
+	* deletes its Workflows it does not say, so teardown deletes them explicitly rather than rely on either.
+	*/
+	async deleteWorkflow(workflowName) {
+		return cloudflareRequest(`delete Workflow ${workflowName}`, async () => {
+			try {
+				await this.getClient().workflows.delete(workflowName, { account_id: this.accountId });
+				return true;
+			} catch (error) {
+				if (isNotFoundError(error)) return false;
+				throw error;
+			}
+		});
+	}
 	/** Create (trigger) a Workflow instance and return its id. */
 	async createInstance(workflowName, params, instanceId) {
 		return cloudflareRequest(`create instance of ${workflowName}`, async () => {
@@ -155,4 +191,4 @@ function describeFailure(failure, error) {
 	return `${failure.step === void 0 ? "step" : `step '${failure.step}'`} raised${failure.code === void 0 ? "" : ` [${failure.code}]`} ${failure.raw} — instance error: ${instance}`;
 }
 //#endregion
-export { CloudflareWorkflowsClient, WorkflowInstance, WorkflowInstanceStatus };
+export { CloudflareWorkflowsClient, WorkflowDefinition, WorkflowInstance, WorkflowInstanceStatus };

package/package.json

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