@pithy-sh/cloudflare 0.4.1 → 0.5.0

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;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"}
+{"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;aAiBzB,cAAc,YAAG,sBAAsB;CAC/B,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;CAeoC,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAShE;AAED;;;;;;;;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

@@ -29,6 +29,50 @@ const PERMISSION_GROUPS = {
 	"routes:write": ["Workers Routes Write"]
 };
 /**
+* **The third column: the OAuth scope each key needs a signed-in session to hold (#759).**
+*
+* A session mints only what it could do itself. Cloudflare refuses a mint whose permission groups the
+* session's scopes do not cover — *"The OAuth session does not include the scopes required for the
+* requested permission groups"*, measured 2026-10-15 — so the scopes `pithy cloudflare connect` asks for
+* are derived from the permissions the project's tokens carry, through this table, and never listed by
+* hand. `satisfies` over {@link PermissionKey} makes a key added above without a scope here a type error.
+*
+* **The ids pair with the group names one to one.** `GET /oauth/scopes` names each scope exactly as the
+* permission group it grants — `d1.write` is "D1 Write", `workers-routes.write` is "Workers Routes Write" —
+* which is what lets the integration test check this column against Cloudflare's own catalog the way
+* the group names are checked against the account. A write scope also covers its read: a session holding
+* `d1.write` minted a "D1 Read" token, so a key never needs both.
+*
+* Dot-delimited, always. The colon form (`account:read`) is what a first-party client like wrangler asks
+* for, and a third-party client can neither register one nor request it.
+*/
+const OAUTH_SCOPES = {
+	"d1:read": ["d1.read"],
+	"d1:write": ["d1.write"],
+	"workers:write": ["workers-scripts.write"],
+	"secrets:read": ["secrets-store.read"],
+	"secrets:write": ["secrets-store.write"],
+	"email:routing": ["email-routing-rule.write"],
+	"kv:write": ["workers-kv-storage.write"],
+	"r2:read": ["workers-r2.read"],
+	"r2:write": ["workers-r2.write"],
+	"vectorize:read": ["vectorize.read"],
+	"vectorize:write": ["vectorize.write"],
+	"ai:read": ["ai.read"],
+	"zone:read": ["zone.read"],
+	"routes:write": ["workers-routes.write"]
+};
+/**
+* Resolve permission keys to the OAuth scopes a session needs to act — or mint — with them, de-duped in
+* first-seen order. An unknown key is refused exactly as {@link resolvePermissionKeys} refuses it.
+*/
+function oauthScopesFor(keys) {
+	resolvePermissionKeys([...keys]);
+	const scopes = [];
+	for (const key of keys) for (const scope of OAUTH_SCOPES[key]) if (!scopes.includes(scope)) scopes.push(scope);
+	return scopes;
+}
+/**
 * 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.
 *
@@ -64,4 +108,4 @@ function resolvePermissionKeys(keys) {
 	return names;
 }
 //#endregion
-export { PERMISSION_GROUPS, ZONE_SCOPED_PERMISSIONS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys };
+export { OAUTH_SCOPES, PERMISSION_GROUPS, ZONE_SCOPED_PERMISSIONS, isPermissionKey, isZoneScopedPermission, oauthScopesFor, resolvePermissionKeys };

package/dist/tokens/profiles.d.ts

@@ -105,6 +105,10 @@ export declare function permissionsForKeys(keys: PermissionKey[], accountId: str
  * 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.
  *
+ * **This limits the route, not the token.** The account policy beside it carries Workers Scripts Write,
+ * which attaches a custom domain on any zone the account holds (measured, #709; `docs/TOKENS.md`). Only
+ * the route calls are held to the declared zones.
+ *
  * **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.

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,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"}
+{"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;;;;;;;;;;;;;;;;;GAiBG;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

@@ -152,6 +152,10 @@ function permissionsForKeys(keys, accountId) {
 * 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.
 *
+* **This limits the route, not the token.** The account policy beside it carries Workers Scripts Write,
+* which attaches a custom domain on any zone the account holds (measured, #709; `docs/TOKENS.md`). Only
+* the route calls are held to the declared zones.
+*
 * **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.

package/dist/workers/buildsManager.js

@@ -3,8 +3,8 @@
 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";
+import { z } from "zod";
 //#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";

package/dist/workflows/stepFailure.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { z } from "zod";
 import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
 import { MAX_WORKFLOW_STEP_TEXT, decodeWorkflowStepMessage, splitWorkflowStepCode } from "@pithy-sh/core/src/workflow/stepMessage";
 import { guaranteedErrorParams } from "@pithy-sh/core/src/error/messageParams";
 import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";

package/dist/workflows/workflowsClient.js

@@ -3,8 +3,8 @@
 import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { stepFailure, terminalWorkflowError } from "./stepFailure.js";
-import { z } from "zod";
 import { UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
 //#region src/workflows/workflowsClient.ts
 const WorkflowInstanceStatus = z.enum([
 	"queued",

package/package.json

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

package/src/ai/aiManager.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { AIRunParams, AIRunResponse } from "cloudflare/resources/ai/ai";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { AIRunResponse } from "cloudflare/resources/ai/ai";
 import type { ModelListResponse } from "cloudflare/resources/ai/models/models";
 import { fromUint8Array } from "js-base64";
 import { z } from "zod";
@@ -128,6 +129,39 @@ export interface AnalyzeImageOptions {
 
 const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable for alt text.";
 
+/**
+ * What a Workers AI model name may look like: `@<namespace>/` and then one to three segments, each made of
+ * letters, digits, `.`, `_` and `-` and starting with a letter or digit — `@cf/baai/bge-m3`,
+ * `@cf/llava-hf/llava-1.5-7b-hf`, `@hf/thebloke/deepseek-coder-6.7b-instruct-awq`.
+ *
+ * **The name goes into the request path unencoded, so this pattern is the whole of the defense.** A segment
+ * cannot be `.` or `..` (it must start with a letter or digit), and nothing that ends a path, opens a query
+ * or a fragment, or escapes a character (`?`, `#`, `%`, `\`, whitespace) is in the alphabet. A name outside
+ * it is refused before a request exists.
+ */
+const AI_MODEL_NAME = /^@[a-z0-9][a-z0-9-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*){1,3}$/;
+
+/**
+ * The REST path that runs `model`: `/accounts/<id>/ai/run/@cf/baai/bge-m3`, the model's slashes literal.
+ *
+ * **Not the SDK's `ai.run` (#709).** cloudflare 7.0.0 builds that path with its `path` tag, which
+ * percent-encodes every path parameter, the `/`s inside a model name included. Cloudflare routes on the
+ * literal slashes, so `/ai/run/@cf%2Fbaai%2Fbge-m3` answers 7000 "No route for that URI" for every model.
+ * The path is built here instead, and a name that could change its shape is refused by {@link AI_MODEL_NAME}.
+ *
+ * @throws ValidationError (`validation/invalid_input`) when `model` is not a Workers AI model name.
+ */
+export function aiRunPath(accountId: string, model: string): string {
+  if (!AI_MODEL_NAME.test(model)) {
+    throw new ValidationError({
+      message: `"${model.slice(0, 120)}" is not a Workers AI model name.`,
+      action: "Pass a model name such as @cf/baai/bge-m3. The Workers AI model catalog lists them.",
+      detail: `model name ${JSON.stringify(model)} does not match ${AI_MODEL_NAME}`,
+    });
+  }
+  return `/accounts/${encodeURIComponent(accountId)}/ai/run/${model}`;
+}
+
 /**
  * Out-of-Worker Workers AI access over the REST API: run any model, generate text, generate
  * embeddings, analyze an image, and list models from a CLI/CI/provisioning context. Inside a
@@ -138,12 +172,17 @@ const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable
 export class CloudflareAIManager extends CloudflareManager {
   /**
    * Run a Cloudflare AI model by name with an arbitrary JSON input. The single seam every typed
-   * helper builds on. The account id is injected for you; the rest of `input` is the model's body.
+   * helper builds on. The account is addressed for you; `input` is the model's body.
+   *
+   * Through the SDK's raw `post` to {@link aiRunPath}, not `ai.run`, whose path encoding Cloudflare cannot
+   * route. A malformed model name throws `validation/invalid_input` before any request is sent.
    */
   async runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse> {
-    return cloudflareRequest(`AI run model '${model}'`, () =>
-      this.getClient().ai.run(model, { account_id: this.accountId, ...input } as AIRunParams),
-    );
+    const path = aiRunPath(this.accountId, model);
+    return cloudflareRequest(`AI run model '${model}'`, async () => {
+      const envelope = await this.getClient().post<{ result: AIRunResponse }>(path, { body: input });
+      return envelope.result;
+    });
   }
 
   /**

package/src/client/manager.ts

@@ -17,6 +17,15 @@ export interface CloudflareManagerConfig {
   apiToken: string;
   /** The Cloudflare account id all operations target (`CLOUDFLARE_ACCOUNT_ID`). */
   accountId: string;
+  /**
+   * The token to call with *now*, read at every call, when it can change during the manager's life (#759).
+   *
+   * A signed-in session's access token lasts an hour and is renewed on disk ahead of that, so a manager
+   * built at the start of a long run would otherwise keep sending the token it was constructed with.
+   * Absent, {@link apiToken} is the token for good — which is every command that finishes inside the hour
+   * dispatch guarantees it.
+   */
+  tokenProvider?: () => string;
 }
 
 /**
@@ -26,9 +35,10 @@ export interface CloudflareManagerConfig {
  * (`validateServiceAccess`).
  */
 export abstract class CloudflareManager {
-  private readonly client: Cloudflare;
+  /** The SDK client, and the token it was built for — rebuilt when {@link getApiToken} answers another. */
+  private client: { token: string; sdk: Cloudflare };
 
-  private readonly apiToken: string;
+  private readonly token: () => string;
 
   protected readonly accountId: string;
 
@@ -39,22 +49,30 @@ export abstract class CloudflareManager {
     if (!config.accountId) {
       throw new CloudflareNotConfiguredError({ detail: "Missing accountId in CloudflareManagerConfig." });
     }
-    this.client = new Cloudflare({ apiToken: config.apiToken });
-    this.apiToken = config.apiToken;
+    const initial = config.apiToken;
+    this.token = config.tokenProvider ?? (() => initial);
+    this.client = { token: initial, sdk: new Cloudflare({ apiToken: initial }) };
     this.accountId = config.accountId;
   }
 
   /** The configured SDK client. Subclasses route typed calls through this. */
   protected getClient(): Cloudflare {
-    return this.client;
+    const token = this.getApiToken();
+    if (token !== this.client.token) this.client = { token, sdk: new Cloudflare({ apiToken: token }) };
+    return this.client.sdk;
   }
 
   /**
    * The raw API token, for subclasses that fall back to direct `fetch()` for endpoints the typed
    * SDK does not cover (e.g. Workers Builds, event subscriptions). The documented escape hatch.
+   * Read through the provider at every call, so it is the current token, never the constructed one.
    */
   protected getApiToken(): string {
-    return this.apiToken;
+    const token = this.token();
+    if (!token) {
+      throw new CloudflareNotConfiguredError({ detail: "The tokenProvider answered no apiToken." });
+    }
+    return token;
   }
 
   /** The account id all operations target. */

package/src/d1/d1Manager.ts

@@ -7,7 +7,7 @@ import type { D1 } from "cloudflare/resources/d1/d1";
 import type { QueryResult } from "cloudflare/resources/d1/database";
 import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors";
 import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
-import { D1PreparedStatementREST } from "./d1PreparedStatement";
+import { D1_QUERY_REQUEST, D1PreparedStatementREST } from "./d1PreparedStatement";
 
 /** Config for the D1 manager: the shared client config plus the database it targets. */
 export interface D1ManagerConfig extends CloudflareManagerConfig {
@@ -68,7 +68,7 @@ export class CloudflareD1Manager extends CloudflareManager implements D1Database
 
   async exec(query: string): Promise<D1ExecResult> {
     const response = await cloudflareRequest("D1 exec", () =>
-      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql: query }),
+      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql: query }, D1_QUERY_REQUEST),
     );
     const result = response.result[0];
     return { count: result?.results?.length ?? 0, duration: result?.meta?.duration ?? 0 };
@@ -89,7 +89,11 @@ export class CloudflareD1Manager extends CloudflareManager implements D1Database
   /** Run one SQL statement and return its raw REST result sets. */
   async executeQuery(sql: string, params?: string[]): Promise<QueryResult[]> {
     const response = await cloudflareRequest("D1 query", () =>
-      this.getClient().d1.database.query(this.databaseId, { account_id: this.accountId, sql, params }),
+      this.getClient().d1.database.query(
+        this.databaseId,
+        { account_id: this.accountId, sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     return response.result;
   }

package/src/d1/d1PreparedStatement.ts

@@ -31,6 +31,17 @@ function mapMeta(restMeta?: QueryResult.Meta): D1Meta & Record<string, unknown>
   };
 }
 
+/**
+ * The request options every D1 query is sent with: **no retries** (#709).
+ *
+ * The SDK retries a request twice by default, on a connection timeout, a 408, a 409, a 429 or a 5xx. That is
+ * safe for a read of a resource and wrong for a query, which is not idempotent: D1 can apply a statement and
+ * answer slowly, and the resent copy then runs against the changed database. A migration's `CREATE TABLE` did
+ * exactly that and failed `table already exists`, on a step that had succeeded. Sent once, a slow answer
+ * surfaces as the timeout it was, and `cloudflareRequest` already tells the operator to check before retrying.
+ */
+export const D1_QUERY_REQUEST = { maxRetries: 0 } as const;
+
 /** The REST `params` array is strings; coerce each bound value the way the D1 REST API expects. */
 function toStringParams(params: unknown[]): string[] {
   return params.map((value) => {
@@ -88,7 +99,11 @@ export class D1PreparedStatementREST<T = Record<string, unknown>> implements D1P
   async raw<U = unknown[]>(options?: { columnNames?: boolean }): Promise<U[] | [string[], ...U[]]> {
     const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
     const response = await cloudflareRequest("D1 raw query", () =>
-      this.client.d1.database.raw(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+      this.client.d1.database.raw(
+        this.databaseId,
+        { account_id: this.accountId, sql: this.sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     const rawResult = response.result[0];
     const rows = (rawResult?.results?.rows ?? []) as U[];
@@ -102,7 +117,11 @@ export class D1PreparedStatementREST<T = Record<string, unknown>> implements D1P
   private async executeQuery<U>(): Promise<D1Result<U>> {
     const params = this.boundParams.length > 0 ? toStringParams(this.boundParams) : undefined;
     const response = await cloudflareRequest("D1 query", () =>
-      this.client.d1.database.query(this.databaseId, { account_id: this.accountId, sql: this.sql, params }),
+      this.client.d1.database.query(
+        this.databaseId,
+        { account_id: this.accountId, sql: this.sql, params },
+        D1_QUERY_REQUEST,
+      ),
     );
     const queryResult = response.result[0];
     return {

package/src/oauth/callback.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { commandName } from "@pithy-sh/core/src/cli/command";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+
+/** What a callback said: a code to redeem, or Cloudflare's refusal. */
+export type CallbackAnswer = { kind: "code"; code: string } | { kind: "error"; error: string; description: string };
+
+/** What the address must match: the `state` and `redirect_uri` this sign-in sent. */
+export interface CallbackExpectation {
+  /** The `state` in the authorize URL. */
+  state: string;
+  /** The `redirect_uri` in the authorize URL, verbatim. */
+  redirectUri: string;
+}
+
+/**
+ * Read the address a browser landed on — from the loopback listener or pasted by hand — into an answer.
+ *
+ * **One reader for both paths, so they cannot check different things.** A remote session pastes what its
+ * browser shows, because the redirect lands on the browser's own loopback interface, where nothing is
+ * listening (measured over SSH, 2026-10-15). The pasted address is held to exactly what a delivered
+ * callback is: the same origin and path this sign-in sent, the same `state`, and a `code` or an `error`.
+ *
+ * Accepting a paste is safe because of PKCE, not because of this check — a code is worthless without the
+ * verifier, and the verifier never left this process. The `state` check is what stops a code from a
+ * *different* sign-in being redeemed into this one.
+ */
+export function readCallback(address: string, expect: CallbackExpectation): CallbackAnswer {
+  const text = address.trim().replace(/^["']|["']$/g, "");
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw notTheAddress(expect, "it is not an address");
+  }
+  const sent = new URL(expect.redirectUri);
+  if (url.origin !== sent.origin || url.pathname !== sent.pathname) {
+    throw notTheAddress(expect, `it is ${url.origin}${url.pathname}`);
+  }
+  if (url.searchParams.get("state") !== expect.state) {
+    throw new ValidationError({
+      message: "That address belongs to a different sign-in: its state does not match.",
+      action: `Paste the address from the browser tab this sign-in opened, or run ${commandName("cloudflare connect")} again.`,
+      detail: "callback state did not match the state this sign-in sent",
+    });
+  }
+  const error = url.searchParams.get("error");
+  if (error !== null) {
+    return { kind: "error", error, description: url.searchParams.get("error_description") ?? error };
+  }
+  const code = url.searchParams.get("code");
+  if (code === null || code === "") {
+    throw new ValidationError({
+      message: "That address carries no code and no error.",
+      action: "Paste the whole address from the browser's address bar, after you approve.",
+      detail: "callback had neither `code` nor `error`",
+    });
+  }
+  return { kind: "code", code };
+}
+
+function notTheAddress(expect: CallbackExpectation, why: string): ValidationError {
+  return new ValidationError({
+    message: `That is not the address this sign-in sent the browser to: ${why}.`,
+    action: `Paste the whole address your browser landed on. It starts with ${expect.redirectUri}.`,
+    detail: `expected ${expect.redirectUri}`,
+  });
+}

package/src/oauth/catalog.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+
+/** One OAuth scope, as Cloudflare's catalog lists it. */
+export const OAuthScope = z
+  .object({
+    id: z.string().describe("The scope a client requests: `d1.write`."),
+    name: z.string().describe("Its display name, which is the permission group's own: `D1 Write`."),
+    category: z.string().optional().describe("Cloudflare's grouping, e.g. `developer_platform`."),
+  })
+  .describe("One scope in `GET /oauth/scopes`.");
+export type OAuthScope = z.output<typeof OAuthScope>;
+
+const ScopeList = z.object({ result: z.array(OAuthScope) });
+
+/** The catalog's endpoint. Global: it needs authentication and no account. */
+export const OAUTH_SCOPES_URL = "https://api.cloudflare.com/client/v4/oauth/scopes";
+
+/**
+ * **Cloudflare's OAuth scope catalog: every scope a third-party client may register (#759).**
+ *
+ * The third column of the permission table is checked against this the way the group names are checked
+ * against the account, because a scope id that drifts from it is a sign-in Cloudflare refuses with
+ * `invalid_scope` — at the consent screen of an adopter, rather than in this repository's CI.
+ */
+export async function listOAuthScopes(options: {
+  apiToken: string;
+  fetch?: (url: string, init: { headers: Record<string, string> }) => Promise<Response>;
+}): Promise<OAuthScope[]> {
+  const send = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+  const raw = await cloudflareRequest("list OAuth scopes", async () => {
+    const response = await send(OAUTH_SCOPES_URL, { headers: { authorization: `Bearer ${options.apiToken}` } });
+    return (await response.json()) as unknown;
+  });
+  return decodeResponse(ScopeList, raw, "oauth scopes list").result;
+}