@pithy-sh/cloudflare 0.8.0 → 0.9.0

package/dist/analytics/analyticsManager.d.ts

@@ -4,14 +4,14 @@ import { z } from "zod";
 import { CloudflareManager } from "../client/manager";
 import { type AnalyticsDataset } from "./datasets";
 /**
- * **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads (#728).**
+ * **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads.**
  *
  * One endpoint, `POST /graphql`, reached through the SDK's raw `post` like every other call the typed SDK
  * does not cover — never a hand-rolled `fetch` (CLAUDE.md §Cloudflare access). It answers HTTP 200 with
  * `{ data, errors }` even when it refuses, so `errors` is read on every answer and a non-empty one is a
  * refusal in Cloudflare's own words.
  *
- * The token it runs on is the application's one `runtime` token, carrying "Account Analytics Read", whose grain is
+ * The token it runs on is the application's one `runtime` token, carrying {@link ANALYTICS_PERMISSION}, whose grain is
  * the whole account. This manager narrows nothing on its own: every query takes the keys it is about, and
  * the caller decides which keys those are.
  */
@@ -68,7 +68,7 @@ export declare class CloudflareAnalyticsManager extends CloudflareManager {
         imageIds: readonly string[];
     }): Promise<Map<string, number>>;
     /**
-     * Turnstile events per sitekey and event type inside the window, for the sitekeys given (#731). The sitekey
+     * Turnstile events per sitekey and event type inside the window, for the sitekeys given. The sitekey
      * filter is what scopes the account-wide dataset to the widgets the caller is about. Absent means none.
      */
     turnstileEvents(window: WindowQuery & {

package/dist/analytics/analyticsManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyticsManager.d.ts","sourceRoot":"","sources":["../../src/analytics/analyticsManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,gBAAgB,EAAoD,MAAM,YAAY,CAAC;AAErG;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,sGAAsG;AACtG,eAAO,MAAM,aAAa;;;;;iBAOiF,CAAC;AAC5G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAgE1D,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,KAAK,EAAE,IAAI,CAAC;IACZ,mCAAmC;IACnC,KAAK,EAAE,IAAI,CAAC;CACb;AASD,6DAA6D;AAC7D,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED,iFAAiF;IAC3E,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;OAGG;YACW,KAAK;IAsBnB,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAWnB;;;OAGG;IACG,aAAa,CACjB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC,CAAC,CA2B3D;IAED,0GAA0G;IACpG,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBzG;IAED,qGAAqG;IAC/F,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA2BvG;IAED;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GACpD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAmC3C;CACF"}
+{"version":3,"file":"analyticsManager.d.ts","sourceRoot":"","sources":["../../src/analytics/analyticsManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,gBAAgB,EAAoD,MAAM,YAAY,CAAC;AAGrG;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,sGAAsG;AACtG,eAAO,MAAM,aAAa;;;;;iBAOiF,CAAC;AAC5G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAgE1D,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,KAAK,EAAE,IAAI,CAAC;IACZ,mCAAmC;IACnC,KAAK,EAAE,IAAI,CAAC;CACb;AASD,6DAA6D;AAC7D,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED,iFAAiF;IAC3E,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;OAGG;YACW,KAAK;IA6BnB,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAWnB;;;OAGG;IACG,aAAa,CACjB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC,CAAC,CA2B3D;IAED,0GAA0G;IACpG,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBzG;IAED,qGAAqG;IAC/F,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA2BvG;IAED;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,WAAW,GAAG;QAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GACpD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAmC3C;CACF"}

package/dist/analytics/analyticsManager.js

@@ -3,17 +3,18 @@
 import { CloudflareInvalidResponseError, cloudflareRefusal, cloudflareRequest, decodeResponse } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { IMAGE_REQUESTS, STREAM_MINUTES, TURNSTILE_EVENTS } from "./datasets.js";
+import { ANALYTICS_PERMISSION, GRAPHQL_AUTH_CODES } from "./forbidden.js";
 import { z } from "zod";
 //#region src/analytics/analyticsManager.ts
 /**
-* **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads (#728).**
+* **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads.**
 *
 * One endpoint, `POST /graphql`, reached through the SDK's raw `post` like every other call the typed SDK
 * does not cover — never a hand-rolled `fetch` (CLAUDE.md §Cloudflare access). It answers HTTP 200 with
 * `{ data, errors }` even when it refuses, so `errors` is read on every answer and a non-empty one is a
 * refusal in Cloudflare's own words.
 *
-* The token it runs on is the application's one `runtime` token, carrying "Account Analytics Read", whose grain is
+* The token it runs on is the application's one `runtime` token, carrying {@link ANALYTICS_PERMISSION}, whose grain is
 * the whole account. This manager narrows nothing on its own: every query takes the keys it is about, and
 * the caller decides which keys those are.
 */
@@ -95,16 +96,21 @@ var CloudflareAnalyticsManager = class extends CloudflareManager {
 		const raw = await cloudflareRequest(operation, () => this.getClient().post("/graphql", { body: {
 			query,
 			variables
-		} }), { permission: "Account Analytics Read" });
+		} }), { permission: ANALYTICS_PERMISSION });
 		const answer = decodeResponse(GraphQLAnswer, raw, operation);
 		const errors = answer.errors ?? [];
-		if (errors.length > 0) throw cloudflareRefusal({
-			problem: `Cloudflare request failed: ${operation}.`,
-			apiErrors: errors.map((error) => ({ ...error.message === void 0 ? {} : { message: error.message } })),
-			permission: "Account Analytics Read",
-			...errors.some((error) => error.extensions?.code === RATE_BUDGET_CODE) ? { status: 429 } : {},
-			detail: JSON.stringify(errors)
-		});
+		if (errors.length > 0) {
+			const codes = errors.map((error) => error.extensions?.code);
+			const status = codes.some((code) => code === RATE_BUDGET_CODE) ? 429 : codes.some((code) => code !== void 0 && GRAPHQL_AUTH_CODES.has(code)) ? 403 : void 0;
+			throw cloudflareRefusal({
+				problem: `Cloudflare request failed: ${operation}.`,
+				apiErrors: errors.map((error) => ({ ...error.message === void 0 ? {} : { message: error.message } })),
+				permission: ANALYTICS_PERMISSION,
+				...status === void 0 ? {} : { status },
+				detail: JSON.stringify(errors),
+				cause: errors
+			});
+		}
 		return answer.data;
 	}
 	/** The one account in an answer, refused when the token's viewer cannot see it. */
@@ -172,7 +178,7 @@ var CloudflareAnalyticsManager = class extends CloudflareManager {
 		return totals;
 	}
 	/**
-	* Turnstile events per sitekey and event type inside the window, for the sitekeys given (#731). The sitekey
+	* Turnstile events per sitekey and event type inside the window, for the sitekeys given. The sitekey
 	* filter is what scopes the account-wide dataset to the widgets the caller is about. Absent means none.
 	*/
 	async turnstileEvents(window) {

package/dist/analytics/forbidden.d.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+/**
+ * **An analytics read the Worker's own token may not make, as each caller's own code.**
+ *
+ * Every capability that reads Cloudflare's GraphQL Analytics does it on the one `runtime` token, which needs
+ * {@link ANALYTICS_PERMISSION}. A refusal for want of it is `cloudflare/request_failed` like any other, and
+ * that code names no permission a client can read. So a caller wraps its read in {@link guardForbidden},
+ * which hands a missing grant to the caller's own error class with the permission in `params` and the
+ * remedy in `message`, and lets every other failure through unchanged. No SDK is imported here, so a
+ * caller that loads the manager lazily keeps doing so.
+ */
+/** The account permission group every analytics read needs, as Cloudflare's token editor names it. */
+export declare const ANALYTICS_PERMISSION = "Account Analytics Read";
+/** The GraphQL `extensions.code` that means the token may not read the account it asked about. */
+export declare const GRAPHQL_AUTH_CODES: ReadonlySet<string>;
+/** A missing grant, in the fields a caller's error class takes. */
+export interface ForbiddenRefusal {
+    /** The sentence the caller reads: the permission, and the rotate that adds it. */
+    message: string;
+    /** `permission`, for a client that translates. */
+    params: MessageParams;
+    /** The operator's line from the Cloudflare refusal, kept for the terminal and the log. */
+    action?: string;
+    /** The Cloudflare refusal's detail, kept for the log. */
+    detail?: string;
+}
+/** Builds the caller's own error for a missing grant. */
+export type RefuseForbidden = (refusal: ForbiddenRefusal, options: {
+    cause: unknown;
+}) => Error;
+/** Where the read ran and what to call it, for the sentence. */
+export interface ForbiddenContext {
+    /** The environment this Worker serves, or null when it names none. */
+    environment: string | null;
+    /** The read as the sentence names it: "the delivery analytics read". */
+    read: string;
+}
+/**
+ * Whether a failure is an analytics query refused because the credentials did not get in: a 401 or 403, or
+ * Cloudflare's auth-class code, or GraphQL's `authz`. A spent rate budget, a 5xx and a rejected query are not.
+ */
+export declare function isAnalyticsForbidden(error: unknown): boolean;
+/** A missing grant on `error`, as the fields of the caller's own error. */
+export declare function forbiddenRefusal(error: PithyError, context: ForbiddenContext): ForbiddenRefusal;
+/** Run an analytics read, refusing a missing grant with the caller's own error and passing every other failure on. */
+export declare function guardForbidden<T>(read: () => Promise<T>, context: ForbiddenContext, refuse: RefuseForbidden): Promise<T>;
+//# sourceMappingURL=forbidden.d.ts.map

package/dist/analytics/forbidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden.d.ts","sourceRoot":"","sources":["../../src/analytics/forbidden.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAIrE;;;;;;;;;GASG;AAEH,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAsB,CAAC;AAE1E,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,aAAa,CAAC;IACtB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,KAAK,KAAK,CAAC;AAEhG,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd;AAWD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG5D;AAWD,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAO/F;AAED,sHAAsH;AACtH,wBAAsB,cAAc,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/analytics/forbidden.js

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { isAuthClassFailure } from "../client/errors.js";
+import { RUNTIME_PROFILE } from "../tokens/runtime.js";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { commandName, remedy } from "@pithy-sh/core/src/cli/command";
+//#region src/analytics/forbidden.ts
+/**
+* **An analytics read the Worker's own token may not make, as each caller's own code.**
+*
+* Every capability that reads Cloudflare's GraphQL Analytics does it on the one `runtime` token, which needs
+* {@link ANALYTICS_PERMISSION}. A refusal for want of it is `cloudflare/request_failed` like any other, and
+* that code names no permission a client can read. So a caller wraps its read in {@link guardForbidden},
+* which hands a missing grant to the caller's own error class with the permission in `params` and the
+* remedy in `message`, and lets every other failure through unchanged. No SDK is imported here, so a
+* caller that loads the manager lazily keeps doing so.
+*/
+/** The account permission group every analytics read needs, as Cloudflare's token editor names it. */
+const ANALYTICS_PERMISSION = "Account Analytics Read";
+/** The GraphQL `extensions.code` that means the token may not read the account it asked about. */
+const GRAPHQL_AUTH_CODES = /* @__PURE__ */ new Set(["authz"]);
+/** Whether a GraphQL `errors` array, kept as a refusal's cause, says the token may not read the account. */
+function isGraphQLAuthRefusal(cause) {
+	if (!Array.isArray(cause)) return false;
+	return cause.some((entry) => {
+		const code = entry?.extensions?.code;
+		return typeof code === "string" && GRAPHQL_AUTH_CODES.has(code);
+	});
+}
+/**
+* Whether a failure is an analytics query refused because the credentials did not get in: a 401 or 403, or
+* Cloudflare's auth-class code, or GraphQL's `authz`. A spent rate budget, a 5xx and a rejected query are not.
+*/
+function isAnalyticsForbidden(error) {
+	if (!(error instanceof PithyError) || error.payload.code !== "cloudflare/request_failed") return false;
+	return isAuthClassFailure(error.cause) || isGraphQLAuthRefusal(error.cause);
+}
+/** The remedy a caller reads: rotate re-scopes the runtime token, where a mint only rolls its value. */
+function rotateSentence(environment) {
+	const tail = "to re-scope it; a mint only rolls the value.";
+	if (environment === null) return `Rotate it with \`${commandName("token rotate")}\` ${tail}`;
+	return remedy("token rotate", {
+		args: [RUNTIME_PROFILE],
+		flags: { "--env": environment }
+	}, { runtime: true }).say((command) => `Run \`${command}\` ${tail}`);
+}
+/** A missing grant on `error`, as the fields of the caller's own error. */
+function forbiddenRefusal(error, context) {
+	return {
+		message: `Cloudflare refused ${context.read}: this Worker's ${RUNTIME_PROFILE} token lacks ${ANALYTICS_PERMISSION}. ${rotateSentence(context.environment)}`,
+		params: { permission: ANALYTICS_PERMISSION },
+		...error.payload.action === void 0 ? {} : { action: error.payload.action },
+		...error.payload.detail === void 0 ? {} : { detail: error.payload.detail }
+	};
+}
+/** Run an analytics read, refusing a missing grant with the caller's own error and passing every other failure on. */
+async function guardForbidden(read, context, refuse) {
+	try {
+		return await read();
+	} catch (error) {
+		if (!(error instanceof PithyError) || !isAnalyticsForbidden(error)) throw error;
+		throw refuse(forbiddenRefusal(error, context), { cause: error });
+	}
+}
+//#endregion
+export { ANALYTICS_PERMISSION, GRAPHQL_AUTH_CODES, forbiddenRefusal, guardForbidden, isAnalyticsForbidden };

package/dist/client/errors.d.ts

@@ -56,9 +56,8 @@ export declare class CloudflareInvalidResponseError extends PithyError {
  * One entry of Cloudflare's `errors[]` array — the API's own answer to a failed call.
  *
  * Every v4 endpoint answers a failure with `{ success: false, errors: [{ code, message,
- * documentation_url }] }`, and the SDK already parses it onto the thrown `APIError`. Until #534 we
- * projected none of it: a refusal named the operation and stopped, so a token missing one product's
- * grant, a revoked token, a wrong account and an outage all rendered as the same sentence.
+ * documentation_url }] }`, and the SDK parses it onto the thrown `APIError`. It is what tells a token
+ * missing one product's grant, a revoked token, a wrong account and an outage apart.
  */
 export interface CloudflareApiError {
     /** Cloudflare's numeric error code — the stable discriminator (`10000` is its auth-class code). */
@@ -96,13 +95,9 @@ export declare function cloudflareRequest<T>(operation: string, fn: () => Promis
  * Compose the refusal every failed Cloudflare call renders: the problem line, then the API's own
  * answer, then — only for an auth-class code — what to do about it.
  *
- * One place, so a fix reaches every provisioner at once — and **one place is a claim a test has to
- * hold, because it was false the first time it was written.** Round one of #534 said
- * `CloudflareBuildsManager` was the only path composing a refusal by hand; `mintToken`, the Stream
- * direct upload and two integration helpers were composing their own, so `pithy token mint` — the
- * bootstrap command an under-scoped token meets first — still printed the operation and nothing else
- * on the identical 401 body. `refusalSites.test.ts` now fails any `new CloudflareRequestError(`
- * outside this file, so "the only place" is enforced rather than remembered.
+ * One place, so a fix reaches every provisioner at once. `refusalSites.test.ts` fails any
+ * `new CloudflareRequestError(` outside this file, so "the only place" is enforced rather than
+ * remembered.
  *
  * CLAUDE.md §Errors decides where each string lands. Cloudflare's sentence and its docs link are the
  * **caller's** information — what happened, in the words of whoever it happened to — so they go in
@@ -118,14 +113,10 @@ export declare function cloudflareRequest<T>(operation: string, fn: () => Promis
  * 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
- * reads beautifully in a terminal and is unencodable everywhere else. A `PithyError` raised inside a
- * `classifiedSteps` step crosses a durable boundary as one string whose newline separates the sentence
- * from the remedy, so a multi-line `message` was declined whole at the reader and the operator got
- * `core/workflow_failed` 500 about durable execution instead of the API answer this issue exists to
- * show them. The same newline is what the CLI's action line is, so an upstream sentence containing one
- * forges a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
+ * **The message is one line, a kit-wide rule.** A `PithyError` raised inside a `classifiedSteps` step
+ * crosses a durable boundary as one string whose newline separates the sentence from the remedy, so a
+ * multi-line `message` is declined whole at the reader. The same newline is what the CLI's action line
+ * is, so an upstream sentence containing one would forge a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
  * theirs with a word instead of an indent, and a word survives a step record, a `--json` line and a
  * browser.
  */
@@ -183,6 +174,11 @@ export declare function cloudflareSaid(problem: string, apiErrors: CloudflareApi
  * one somebody clicks.
  */
 export declare function cloudflareApiErrors(source: unknown): CloudflareApiError[];
+/**
+ * Whether a thrown SDK error is the credentials failing rather than the request — the same judgment the
+ * refusal's action line makes, read off the throw a {@link cloudflareRefusal} keeps as its `cause`.
+ */
+export declare function isAuthClassFailure(error: unknown): boolean;
 /**
  * The HTTP status of a thrown SDK error, when it carries one. Exported because a call site that
  * composes its own refusal through {@link cloudflareRefusal} has to hand it the same status this

package/dist/client/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}

package/dist/client/errors.js

@@ -104,10 +104,9 @@ function oneLine(text) {
 * Cloudflare's auth-class codes — the ones that mean "your credentials did not get you in", as
 * opposed to a missing resource (`12000`), a conflict (`12042`) or a rejected argument (`10202`).
 *
-* Status alone is not the discriminator, which is the trap #534 walked into: the reported Turnstile
-* refusal was `10000` under a **401**, while `isAuthorizationError` below keys on 403 and would not
-* have fired. Cloudflare returns `10000` under 400, 401 and 403 depending on the endpoint, so the
-* code is what identifies the class and the status is only a fallback for a body-less throw.
+* Status alone is not the discriminator: Cloudflare returns `10000` under 400, 401 and 403 depending
+* on the endpoint, so the code is what identifies the class and the status is only a fallback for a
+* body-less throw.
 */
 const AUTH_CLASS_CODES = /* @__PURE__ */ new Set([
 	9103,
@@ -188,13 +187,9 @@ async function cloudflareRequest(operation, fn, options) {
 * Compose the refusal every failed Cloudflare call renders: the problem line, then the API's own
 * answer, then — only for an auth-class code — what to do about it.
 *
-* One place, so a fix reaches every provisioner at once — and **one place is a claim a test has to
-* hold, because it was false the first time it was written.** Round one of #534 said
-* `CloudflareBuildsManager` was the only path composing a refusal by hand; `mintToken`, the Stream
-* direct upload and two integration helpers were composing their own, so `pithy token mint` — the
-* bootstrap command an under-scoped token meets first — still printed the operation and nothing else
-* on the identical 401 body. `refusalSites.test.ts` now fails any `new CloudflareRequestError(`
-* outside this file, so "the only place" is enforced rather than remembered.
+* One place, so a fix reaches every provisioner at once. `refusalSites.test.ts` fails any
+* `new CloudflareRequestError(` outside this file, so "the only place" is enforced rather than
+* remembered.
 *
 * CLAUDE.md §Errors decides where each string lands. Cloudflare's sentence and its docs link are the
 * **caller's** information — what happened, in the words of whoever it happened to — so they go in
@@ -210,14 +205,10 @@ async function cloudflareRequest(operation, fn, options) {
 * 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
-* reads beautifully in a terminal and is unencodable everywhere else. A `PithyError` raised inside a
-* `classifiedSteps` step crosses a durable boundary as one string whose newline separates the sentence
-* from the remedy, so a multi-line `message` was declined whole at the reader and the operator got
-* `core/workflow_failed` 500 about durable execution instead of the API answer this issue exists to
-* show them. The same newline is what the CLI's action line is, so an upstream sentence containing one
-* forges a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
+* **The message is one line, a kit-wide rule.** A `PithyError` raised inside a `classifiedSteps` step
+* crosses a durable boundary as one string whose newline separates the sentence from the remedy, so a
+* multi-line `message` is declined whole at the reader. The same newline is what the CLI's action line
+* is, so an upstream sentence containing one would forge a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
 * theirs with a word instead of an indent, and a word survives a step record, a `--json` line and a
 * browser.
 */
@@ -254,7 +245,7 @@ function cloudflareRefusal(args) {
 * 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
+* **A statusless failure is not covered here, and deliberately so.** 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,
@@ -404,7 +395,7 @@ function apiErrorParams(entry) {
 *
 * **The API's code decides; the status is only consulted when there is no code.** Cloudflare returns
 * `10000` under 400, 401 and 403 depending on the endpoint, which is why the status cannot be the
-* discriminator — and the converse is the half that shipped wrong: a 403 is *also* how Cloudflare
+* discriminator — and the converse holds too: a 403 is *also* how Cloudflare
 * answers `10021 Script startup exceeded CPU limit`, and "add Account → Workers Scripts to it" changes
 * nothing about a CPU limit. So when Cloudflare named any code at all, the codes are the whole of the
 * evidence and the status is not consulted; only a body-less throw (`401 status code (no body)`) falls
@@ -414,13 +405,11 @@ function apiErrorParams(entry) {
 * Cloudflare answered `10000` for this one call; that is all it said. A token missing this product's
 * grant, a revoked token and a token pointed at the wrong account all produce it, and this process can
 * separate none of the three. So the line names all three, in the order an operator can check them,
-* and asserts none. It named two for one round — "reaches other products" or "reaches none" — which
-* excluded the third by construction: a token in the *wrong* account reaches other products in that
-* account, so the operator was told to add a grant they already held.
+* and asserts none.
 *
-* The **level** is deliberately absent too. The call that raised #534 was a *list* — Read would have
-* satisfied it — so "Turnstile → Edit" would have been a guess dressed as an instruction. Name the
-* group; the operator picks the level their calls need.
+* The **level** is deliberately absent too. A list call is satisfied by Read, so "Turnstile → Edit"
+* would be a guess dressed as an instruction. Name the group; the operator picks the level their calls
+* need.
 */
 function permissionAction(apiErrors, status, hint) {
 	if (!isAuthClassRefusal(apiErrors, status)) return void 0;
@@ -436,6 +425,13 @@ function isAuthClassRefusal(apiErrors, status) {
 	if (coded.length > 0) return coded.some((entry) => AUTH_CLASS_CODES.has(entry.code));
 	return status === 401 || status === 403;
 }
+/**
+* Whether a thrown SDK error is the credentials failing rather than the request — the same judgment the
+* refusal's action line makes, read off the throw a {@link cloudflareRefusal} keeps as its `cause`.
+*/
+function isAuthClassFailure(error) {
+	return isAuthClassRefusal(cloudflareApiErrors(error), statusOf(error));
+}
 /** The account permission group behind the refused endpoint, per Cloudflare's own docs link. */
 function accountPermissionOf(apiErrors) {
 	for (const entry of apiErrors) {
@@ -575,4 +571,4 @@ function decodeResponse(schema, raw, context) {
 	return parsed.data;
 }
 //#endregion
-export { CloudflareInvalidResponseError, CloudflareNotConfiguredError, CloudflareRequestError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, cloudflareSaid, decodeResponse, isAuthorizationError, isNotFoundError, messageOf, reasonOf, statusOf };
+export { CloudflareInvalidResponseError, CloudflareNotConfiguredError, CloudflareRequestError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, cloudflareSaid, decodeResponse, isAuthClassFailure, isAuthorizationError, isNotFoundError, messageOf, reasonOf, statusOf };

package/dist/tokens/profiles.js

@@ -1,9 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { CloudflareNotConfiguredError } from "../client/errors.js";
+import { RUNTIME_PROFILE, RUNTIME_TOKEN_SECRET } from "./runtime.js";
 import { accountResource, zoneResources } from "./accountTokensManager.js";
 import { PERMISSION_GROUPS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys } from "./permissions.js";
-import { RUNTIME_PROFILE, RUNTIME_TOKEN_SECRET } from "./runtime.js";
 //#region src/tokens/profiles.ts
 /** The valid stores, for validating a `--store` flag or a profile's `defaultStore`. */
 const TOKEN_STORES = [

package/package.json

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

package/src/analytics/analyticsManager.ts

@@ -5,16 +5,17 @@ import { z } from "zod";
 import { CloudflareInvalidResponseError, cloudflareRefusal, cloudflareRequest, decodeResponse } from "../client/errors";
 import { CloudflareManager } from "../client/manager";
 import { type AnalyticsDataset, IMAGE_REQUESTS, STREAM_MINUTES, TURNSTILE_EVENTS } from "./datasets";
+import { ANALYTICS_PERMISSION, GRAPHQL_AUTH_CODES } from "./forbidden";
 
 /**
- * **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads (#728).**
+ * **Cloudflare's GraphQL Analytics API, for the account-level datasets the kit reads.**
  *
  * One endpoint, `POST /graphql`, reached through the SDK's raw `post` like every other call the typed SDK
  * does not cover — never a hand-rolled `fetch` (CLAUDE.md §Cloudflare access). It answers HTTP 200 with
  * `{ data, errors }` even when it refuses, so `errors` is read on every answer and a non-empty one is a
  * refusal in Cloudflare's own words.
  *
- * The token it runs on is the application's one `runtime` token, carrying "Account Analytics Read", whose grain is
+ * The token it runs on is the application's one `runtime` token, carrying {@link ANALYTICS_PERMISSION}, whose grain is
  * the whole account. This manager narrows nothing on its own: every query takes the keys it is about, and
  * the caller decides which keys those are.
  */
@@ -145,19 +146,26 @@ export class CloudflareAnalyticsManager extends CloudflareManager {
     const raw = await cloudflareRequest(
       operation,
       () => this.getClient().post<unknown>("/graphql", { body: { query, variables } }),
-      { permission: "Account Analytics Read" },
+      { permission: ANALYTICS_PERMISSION },
     );
     const answer = decodeResponse(GraphQLAnswer, raw, operation);
     const errors = answer.errors ?? [];
     if (errors.length > 0) {
+      const codes = errors.map((error) => error.extensions?.code);
+      // Every refusal answers 200, so the status handed on is the one the GraphQL code means: a spent rate
+      // budget is the 429 worth asking again, and `authz` is the 403 whose action line names the grant.
+      const status = codes.some((code) => code === RATE_BUDGET_CODE)
+        ? 429
+        : codes.some((code) => code !== undefined && GRAPHQL_AUTH_CODES.has(code))
+          ? 403
+          : undefined;
       throw cloudflareRefusal({
         problem: `Cloudflare request failed: ${operation}.`,
         apiErrors: errors.map((error) => ({ ...(error.message === undefined ? {} : { message: error.message }) })),
-        permission: "Account Analytics Read",
-        // A spent rate budget answers 200 too, with `extensions.code: "budget"` (measured 2026-10-17). It
-        // is the one GraphQL refusal that is worth asking again, so it is handed on as the 429 it means.
-        ...(errors.some((error) => error.extensions?.code === RATE_BUDGET_CODE) ? { status: 429 } : {}),
+        permission: ANALYTICS_PERMISSION,
+        ...(status === undefined ? {} : { status }),
         detail: JSON.stringify(errors),
+        cause: errors,
       });
     }
     return answer.data;
@@ -267,7 +275,7 @@ export class CloudflareAnalyticsManager extends CloudflareManager {
   }
 
   /**
-   * Turnstile events per sitekey and event type inside the window, for the sitekeys given (#731). The sitekey
+   * Turnstile events per sitekey and event type inside the window, for the sitekeys given. The sitekey
    * filter is what scopes the account-wide dataset to the widgets the caller is about. Absent means none.
    */
   async turnstileEvents(

package/src/analytics/forbidden.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { commandName, remedy } from "@pithy-sh/core/src/cli/command";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import { isAuthClassFailure } from "../client/errors";
+import { RUNTIME_PROFILE } from "../tokens/runtime";
+
+/**
+ * **An analytics read the Worker's own token may not make, as each caller's own code.**
+ *
+ * Every capability that reads Cloudflare's GraphQL Analytics does it on the one `runtime` token, which needs
+ * {@link ANALYTICS_PERMISSION}. A refusal for want of it is `cloudflare/request_failed` like any other, and
+ * that code names no permission a client can read. So a caller wraps its read in {@link guardForbidden},
+ * which hands a missing grant to the caller's own error class with the permission in `params` and the
+ * remedy in `message`, and lets every other failure through unchanged. No SDK is imported here, so a
+ * caller that loads the manager lazily keeps doing so.
+ */
+
+/** The account permission group every analytics read needs, as Cloudflare's token editor names it. */
+export const ANALYTICS_PERMISSION = "Account Analytics Read";
+
+/** The GraphQL `extensions.code` that means the token may not read the account it asked about. */
+export const GRAPHQL_AUTH_CODES: ReadonlySet<string> = new Set(["authz"]);
+
+/** A missing grant, in the fields a caller's error class takes. */
+export interface ForbiddenRefusal {
+  /** The sentence the caller reads: the permission, and the rotate that adds it. */
+  message: string;
+  /** `permission`, for a client that translates. */
+  params: MessageParams;
+  /** The operator's line from the Cloudflare refusal, kept for the terminal and the log. */
+  action?: string;
+  /** The Cloudflare refusal's detail, kept for the log. */
+  detail?: string;
+}
+
+/** Builds the caller's own error for a missing grant. */
+export type RefuseForbidden = (refusal: ForbiddenRefusal, options: { cause: unknown }) => Error;
+
+/** Where the read ran and what to call it, for the sentence. */
+export interface ForbiddenContext {
+  /** The environment this Worker serves, or null when it names none. */
+  environment: string | null;
+  /** The read as the sentence names it: "the delivery analytics read". */
+  read: string;
+}
+
+/** Whether a GraphQL `errors` array, kept as a refusal's cause, says the token may not read the account. */
+function isGraphQLAuthRefusal(cause: unknown): boolean {
+  if (!Array.isArray(cause)) return false;
+  return cause.some((entry: unknown) => {
+    const code = (entry as { extensions?: { code?: unknown } } | null)?.extensions?.code;
+    return typeof code === "string" && GRAPHQL_AUTH_CODES.has(code);
+  });
+}
+
+/**
+ * Whether a failure is an analytics query refused because the credentials did not get in: a 401 or 403, or
+ * Cloudflare's auth-class code, or GraphQL's `authz`. A spent rate budget, a 5xx and a rejected query are not.
+ */
+export function isAnalyticsForbidden(error: unknown): boolean {
+  if (!(error instanceof PithyError) || error.payload.code !== "cloudflare/request_failed") return false;
+  return isAuthClassFailure(error.cause) || isGraphQLAuthRefusal(error.cause);
+}
+
+/** The remedy a caller reads: rotate re-scopes the runtime token, where a mint only rolls its value. */
+function rotateSentence(environment: string | null): string {
+  const tail = "to re-scope it; a mint only rolls the value.";
+  if (environment === null) return `Rotate it with \`${commandName("token rotate")}\` ${tail}`;
+  return remedy("token rotate", { args: [RUNTIME_PROFILE], flags: { "--env": environment } }, { runtime: true }).say(
+    (command) => `Run \`${command}\` ${tail}`,
+  );
+}
+
+/** A missing grant on `error`, as the fields of the caller's own error. */
+export function forbiddenRefusal(error: PithyError, context: ForbiddenContext): ForbiddenRefusal {
+  return {
+    message: `Cloudflare refused ${context.read}: this Worker's ${RUNTIME_PROFILE} token lacks ${ANALYTICS_PERMISSION}. ${rotateSentence(context.environment)}`,
+    params: { permission: ANALYTICS_PERMISSION },
+    ...(error.payload.action === undefined ? {} : { action: error.payload.action }),
+    ...(error.payload.detail === undefined ? {} : { detail: error.payload.detail }),
+  };
+}
+
+/** Run an analytics read, refusing a missing grant with the caller's own error and passing every other failure on. */
+export async function guardForbidden<T>(
+  read: () => Promise<T>,
+  context: ForbiddenContext,
+  refuse: RefuseForbidden,
+): Promise<T> {
+  try {
+    return await read();
+  } catch (error) {
+    if (!(error instanceof PithyError) || !isAnalyticsForbidden(error)) throw error;
+    throw refuse(forbiddenRefusal(error, context), { cause: error });
+  }
+}

package/src/client/errors.ts

@@ -94,9 +94,8 @@ export class CloudflareInvalidResponseError extends PithyError {
  * One entry of Cloudflare's `errors[]` array — the API's own answer to a failed call.
  *
  * Every v4 endpoint answers a failure with `{ success: false, errors: [{ code, message,
- * documentation_url }] }`, and the SDK already parses it onto the thrown `APIError`. Until #534 we
- * projected none of it: a refusal named the operation and stopped, so a token missing one product's
- * grant, a revoked token, a wrong account and an outage all rendered as the same sentence.
+ * documentation_url }] }`, and the SDK parses it onto the thrown `APIError`. It is what tells a token
+ * missing one product's grant, a revoked token, a wrong account and an outage apart.
  */
 export interface CloudflareApiError {
   /** Cloudflare's numeric error code — the stable discriminator (`10000` is its auth-class code). */
@@ -162,10 +161,9 @@ function oneLine(text: string): string {
  * Cloudflare's auth-class codes — the ones that mean "your credentials did not get you in", as
  * opposed to a missing resource (`12000`), a conflict (`12042`) or a rejected argument (`10202`).
  *
- * Status alone is not the discriminator, which is the trap #534 walked into: the reported Turnstile
- * refusal was `10000` under a **401**, while `isAuthorizationError` below keys on 403 and would not
- * have fired. Cloudflare returns `10000` under 400, 401 and 403 depending on the endpoint, so the
- * code is what identifies the class and the status is only a fallback for a body-less throw.
+ * Status alone is not the discriminator: Cloudflare returns `10000` under 400, 401 and 403 depending
+ * on the endpoint, so the code is what identifies the class and the status is only a fallback for a
+ * body-less throw.
  */
 const AUTH_CLASS_CODES = new Set([9103, 9106, 9107, 9109, 10000, 10001]);
 
@@ -252,13 +250,9 @@ export async function cloudflareRequest<T>(
  * Compose the refusal every failed Cloudflare call renders: the problem line, then the API's own
  * answer, then — only for an auth-class code — what to do about it.
  *
- * One place, so a fix reaches every provisioner at once — and **one place is a claim a test has to
- * hold, because it was false the first time it was written.** Round one of #534 said
- * `CloudflareBuildsManager` was the only path composing a refusal by hand; `mintToken`, the Stream
- * direct upload and two integration helpers were composing their own, so `pithy token mint` — the
- * bootstrap command an under-scoped token meets first — still printed the operation and nothing else
- * on the identical 401 body. `refusalSites.test.ts` now fails any `new CloudflareRequestError(`
- * outside this file, so "the only place" is enforced rather than remembered.
+ * One place, so a fix reaches every provisioner at once. `refusalSites.test.ts` fails any
+ * `new CloudflareRequestError(` outside this file, so "the only place" is enforced rather than
+ * remembered.
  *
  * CLAUDE.md §Errors decides where each string lands. Cloudflare's sentence and its docs link are the
  * **caller's** information — what happened, in the words of whoever it happened to — so they go in
@@ -274,14 +268,10 @@ export async function cloudflareRequest<T>(
  * 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
- * reads beautifully in a terminal and is unencodable everywhere else. A `PithyError` raised inside a
- * `classifiedSteps` step crosses a durable boundary as one string whose newline separates the sentence
- * from the remedy, so a multi-line `message` was declined whole at the reader and the operator got
- * `core/workflow_failed` 500 about durable execution instead of the API answer this issue exists to
- * show them. The same newline is what the CLI's action line is, so an upstream sentence containing one
- * forges a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
+ * **The message is one line, a kit-wide rule.** A `PithyError` raised inside a `classifiedSteps` step
+ * crosses a durable boundary as one string whose newline separates the sentence from the remedy, so a
+ * multi-line `message` is declined whole at the reader. The same newline is what the CLI's action line
+ * is, so an upstream sentence containing one would forge a remedy Pithy never wrote. `Cloudflare said:` marks the boundary between our words and
  * theirs with a word instead of an indent, and a word survives a step record, a `--json` line and a
  * browser.
  */
@@ -341,7 +331,7 @@ export function cloudflareRefusal(args: {
  * 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
+ * **A statusless failure is not covered here, and deliberately so.** 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,
@@ -504,7 +494,7 @@ function apiErrorParams(entry: CloudflareApiError | undefined): MessageParams {
  *
  * **The API's code decides; the status is only consulted when there is no code.** Cloudflare returns
  * `10000` under 400, 401 and 403 depending on the endpoint, which is why the status cannot be the
- * discriminator — and the converse is the half that shipped wrong: a 403 is *also* how Cloudflare
+ * discriminator — and the converse holds too: a 403 is *also* how Cloudflare
  * answers `10021 Script startup exceeded CPU limit`, and "add Account → Workers Scripts to it" changes
  * nothing about a CPU limit. So when Cloudflare named any code at all, the codes are the whole of the
  * evidence and the status is not consulted; only a body-less throw (`401 status code (no body)`) falls
@@ -514,13 +504,11 @@ function apiErrorParams(entry: CloudflareApiError | undefined): MessageParams {
  * Cloudflare answered `10000` for this one call; that is all it said. A token missing this product's
  * grant, a revoked token and a token pointed at the wrong account all produce it, and this process can
  * separate none of the three. So the line names all three, in the order an operator can check them,
- * and asserts none. It named two for one round — "reaches other products" or "reaches none" — which
- * excluded the third by construction: a token in the *wrong* account reaches other products in that
- * account, so the operator was told to add a grant they already held.
+ * and asserts none.
  *
- * The **level** is deliberately absent too. The call that raised #534 was a *list* — Read would have
- * satisfied it — so "Turnstile → Edit" would have been a guess dressed as an instruction. Name the
- * group; the operator picks the level their calls need.
+ * The **level** is deliberately absent too. A list call is satisfied by Read, so "Turnstile → Edit"
+ * would be a guess dressed as an instruction. Name the group; the operator picks the level their calls
+ * need.
  */
 function permissionAction(apiErrors: CloudflareApiError[], status?: number, hint?: string): string | undefined {
   if (!isAuthClassRefusal(apiErrors, status)) return undefined;
@@ -540,6 +528,14 @@ function isAuthClassRefusal(apiErrors: CloudflareApiError[], status?: number): b
   return status === 401 || status === 403;
 }
 
+/**
+ * Whether a thrown SDK error is the credentials failing rather than the request — the same judgment the
+ * refusal's action line makes, read off the throw a {@link cloudflareRefusal} keeps as its `cause`.
+ */
+export function isAuthClassFailure(error: unknown): boolean {
+  return isAuthClassRefusal(cloudflareApiErrors(error), statusOf(error));
+}
+
 /** The account permission group behind the refused endpoint, per Cloudflare's own docs link. */
 function accountPermissionOf(apiErrors: CloudflareApiError[]): string | undefined {
   for (const entry of apiErrors) {