@pithy-sh/cloudflare 0.4.1 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ _Everything on the adopter side is on the site. `pithy.sh/docs` is canonical —
 
 ## Live integration tests
 
-Mocks prove our call *shapes*. They cannot prove the request, the response decoding, and the error handling are functionally correct against real Cloudflare — that only surfaces live. So every manager that makes real CF calls also has a `*.integration.test.ts` that creates a throwaway resource, exercises the manager against it, and tears it down. These are excluded from the default suite and run via `bun run test:integration` (the `vitest.integration.config.ts` project), gated on credentials so they skip cleanly without them.
+Mocks prove our call *shapes*. They cannot prove the request, the response decoding, and the error handling are functionally correct against real Cloudflare — that only surfaces live. So every manager that makes real CF calls also has a `*.integration.test.ts` that creates a throwaway resource, exercises the manager against it, and tears it down. These are excluded from the default suite and run via turbo's `test:integration` (the `vitest.integration.config.ts` project), gated on credentials so they skip cleanly without them. Turbo builds `@pithy-sh/core` first, because the suites import it through its `exports` map into `dist/`; the package's own `bun run test:integration` skips that build, so it fails on a fresh checkout until something has built core.
 
 Credentials come from `packages/cloudflare/.dev.vars`, with `process.env` overlaid per key for anything the file does not set (`loadCloudflareEnv`). **Nothing creates that file.** It used to be a symlink to the root's, wired by a `vars:local` task; #154 removed both, and `pithy dev` and `pithy seed` generate `apps/<worker>/.dev.vars` in an adopter's project — `apps/` is the registry, so nothing regenerates a file in a kit package. Write it, or export the variables:
 
@@ -25,10 +25,10 @@ cat > .dev.vars <<'EOF'          # a real file, in this package, git-ignored
 CLOUDFLARE_ACCOUNT_ID=…
 CLOUDFLARE_API_TOKEN=…
 EOF
-bun run test:integration         # against the account in those creds
+bunx turbo run test:integration --filter=@pithy-sh/cloudflare   # builds core first, then runs against those creds
 ```
 
-Exporting them instead works identically and is how CI runs — the workflow sets `CLOUDFLARE_*` and `SECRETS_STORE_ID` from the `E2E Integration Testing` environment with no `.dev.vars` present. Set a key in both places and the file wins.
+Exporting them instead works identically and is how CI runs — the workflow sets `CLOUDFLARE_*` and `SECRETS_STORE_ID` from the `E2E Integration Testing` environment with no `.dev.vars` present, and runs the suites through turbo, which builds first and hands a task only the variables `test:integration` lists in `passThroughEnv` (`turbo.jsonc`). Set a key in both places and the file wins.
 
 Point them at a **dedicated test account** — they create and delete real resources.
 

package/dist/ai/aiManager.d.ts

@@ -64,6 +64,17 @@ export interface AnalyzeImageOptions {
     /** Upper bound on generated tokens. */
     maxTokens?: number;
 }
+/**
+ * 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 declare function aiRunPath(accountId: string, model: string): string;
 /**
  * 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
@@ -74,7 +85,10 @@ export interface AnalyzeImageOptions {
 export declare 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.
      */
     runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse>;
     /**

package/dist/ai/aiManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/ai/aiManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiBtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;iBAKgE,CAAC;AAC9F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAuChE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;GAckE,CAAC;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,WAAW;;iBAI8D,CAAC;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAIpF;IAED;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAU5F;IAED;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAezF;IAED,kGAAkG;IAC5F,UAAU,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAK/C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}
+{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/ai/aiManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE/E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAiBtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;iBAKgE,CAAC;AAC9F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAuChE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;GAckE,CAAC;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,WAAW;;iBAI8D,CAAC;AACvF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAMpF;IAED;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAclG;IAED;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAU5F;IAED;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAezF;IAED,kGAAkG;IAC5F,UAAU,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAK/C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/ai/aiManager.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
 import { fromUint8Array } from "js-base64";
 import { z } from "zod";
 //#region src/ai/aiManager.ts
@@ -62,6 +63,35 @@ const TextGeneration = z.union([FlatTextGeneration, ChatCompletionText]).describ
 const ImageToText = z.object({ description: z.string().describe("The model's textual description of the image.") }).describe("A Cloudflare image-to-text result: a description of the supplied image.");
 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.
+*/
+function aiRunPath(accountId, model) {
+	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
 * Worker you use the `Ai` binding directly — this manager is the REST counterpart, addressed by
@@ -71,13 +101,16 @@ const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable
 var CloudflareAIManager = class 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, input) {
-		return cloudflareRequest(`AI run model '${model}'`, () => this.getClient().ai.run(model, {
-			account_id: this.accountId,
-			...input
-		}));
+		const path = aiRunPath(this.accountId, model);
+		return cloudflareRequest(`AI run model '${model}'`, async () => {
+			return (await this.getClient().post(path, { body: input })).result;
+		});
 	}
 	/**
 	* Generate text from a chat prompt. Returns the validated `{ response }` payload. A response that
@@ -147,4 +180,4 @@ var CloudflareAIManager = class extends CloudflareManager {
 	}
 };
 //#endregion
-export { CloudflareAIManager, ImageToText, TextGeneration, VectorEmbeddings };
+export { CloudflareAIManager, ImageToText, TextGeneration, VectorEmbeddings, aiRunPath };

package/dist/client/manager.d.ts

@@ -14,6 +14,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;
 }
 /**
  * Base for every Cloudflare resource manager. Holds the configured SDK client and account id, and
@@ -22,8 +31,9 @@ export interface CloudflareManagerConfig {
  * (`validateServiceAccess`).
  */
 export declare abstract class CloudflareManager {
-    private readonly client;
-    private readonly apiToken;
+    /** The SDK client, and the token it was built for — rebuilt when {@link getApiToken} answers another. */
+    private client;
+    private readonly token;
     protected readonly accountId: string;
     constructor(config: CloudflareManagerConfig);
     /** The configured SDK client. Subclasses route typed calls through this. */
@@ -31,6 +41,7 @@ export declare abstract class CloudflareManager {
     /**
      * 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;
     /** The account id all operations target. */

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

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AAGtE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,8BAAsB,iBAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC,YAAY,MAAM,EAAE,uBAAuB,EAU1C;IAED,4EAA4E;IAC5E,SAAS,CAAC,SAAS,IAAI,UAAU,CAEhC;IAED;;;OAGG;IACH,SAAS,CAAC,WAAW,IAAI,MAAM,CAE9B;IAED,4CAA4C;IAC5C,SAAS,CAAC,YAAY,IAAI,MAAM,CAE/B;IAED,wFAAwF;IAClF,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAEvC;IAED,wFAAwF;IAClF,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO5C;IAED,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,IAAI,MAAM,CAAC;IAElC,kGAAkG;IAClG,QAAQ,CAAC,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AAGtE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,8BAAsB,iBAAiB;IACrC,yGAAyG;IACzG,OAAO,CAAC,MAAM,CAAqC;IAEnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC,YAAY,MAAM,EAAE,uBAAuB,EAW1C;IAED,4EAA4E;IAC5E,SAAS,CAAC,SAAS,IAAI,UAAU,CAIhC;IAED;;;;OAIG;IACH,SAAS,CAAC,WAAW,IAAI,MAAM,CAM9B;IAED,4CAA4C;IAC5C,SAAS,CAAC,YAAY,IAAI,MAAM,CAE/B;IAED,wFAAwF;IAClF,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAEvC;IAED,wFAAwF;IAClF,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO5C;IAED,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,IAAI,MAAM,CAAC;IAElC,kGAAkG;IAClG,QAAQ,CAAC,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD"}

package/dist/client/manager.js

@@ -10,26 +10,39 @@ import { Cloudflare } from "cloudflare";
 * (`validateServiceAccess`).
 */
 var CloudflareManager = class {
+	/** The SDK client, and the token it was built for — rebuilt when {@link getApiToken} answers another. */
 	client;
-	apiToken;
+	token;
 	accountId;
 	constructor(config) {
 		if (!config.apiToken) throw new CloudflareNotConfiguredError({ detail: "Missing apiToken in CloudflareManagerConfig." });
 		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. */
 	getClient() {
-		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.
 	*/
 	getApiToken() {
-		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. */
 	getAccountId() {

package/dist/d1/d1Manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"d1Manager.d.ts","sourceRoot":"","sources":["../../src/d1/d1Manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3F,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAkB,YAAW,UAAU;IAC9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,MAAM,EAAE,eAAe,EAMlC;IAID,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAE1C;IAED;;;;;;OAMG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAMlF;IAEK,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAM/C;IAED,6FAA6F;IACvF,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAEjC;IAED,8EAA8E;IAC9E,WAAW,IAAI,KAAK,CAEnB;IAID,iEAAiE;IAC3D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAKzE;IAED;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW/F;IAED,oCAAoC;IAC9B,eAAe,IAAI,OAAO,CAAC,EAAE,CAAC,CAInC;IAED,4CAA4C;IACtC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAMpC;IAED;;;;OAIG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAS1D;IAED,qEAAqE;IACrE,SAAS,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAErD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}
+{"version":3,"file":"d1Manager.d.ts","sourceRoot":"","sources":["../../src/d1/d1Manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE3F,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGpF,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,iBAAkB,YAAW,UAAU;IAC9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,MAAM,EAAE,eAAe,EAMlC;IAID,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAE1C;IAED;;;;;;OAMG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAMlF;IAEK,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAM/C;IAED,6FAA6F;IACvF,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAEjC;IAED,8EAA8E;IAC9E,WAAW,IAAI,KAAK,CAEnB;IAID,iEAAiE;IAC3D,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CASzE;IAED;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW/F;IAED,oCAAoC;IAC9B,eAAe,IAAI,OAAO,CAAC,EAAE,CAAC,CAInC;IAED,4CAA4C;IACtC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAMpC;IAED;;;;OAIG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAS1D;IAED,qEAAqE;IACrE,SAAS,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAErD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/d1/d1Manager.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 import { CloudflareNotConfiguredError, cloudflareRequest, reasonOf } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
-import { D1PreparedStatementREST } from "./d1PreparedStatement.js";
+import { D1PreparedStatementREST, D1_QUERY_REQUEST } from "./d1PreparedStatement.js";
 import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
 //#region src/d1/d1Manager.ts
 /**
@@ -38,7 +38,7 @@ var CloudflareD1Manager = class extends CloudflareManager {
 		const result = (await cloudflareRequest("D1 exec", () => this.getClient().d1.database.query(this.databaseId, {
 			account_id: this.accountId,
 			sql: query
-		}))).result[0];
+		}, D1_QUERY_REQUEST))).result[0];
 		return {
 			count: result?.results?.length ?? 0,
 			duration: result?.meta?.duration ?? 0
@@ -58,7 +58,7 @@ var CloudflareD1Manager = class extends CloudflareManager {
 			account_id: this.accountId,
 			sql,
 			params
-		}))).result;
+		}, D1_QUERY_REQUEST))).result;
 	}
 	/**
 	* Run many independent queries, collecting a per-query result instead of failing the whole batch

package/dist/d1/d1PreparedStatement.d.ts

@@ -2,6 +2,18 @@
 // SPDX-License-Identifier: MIT
 import type { D1PreparedStatement, D1Result } from "@cloudflare/workers-types";
 import type { Cloudflare } from "cloudflare";
+/**
+ * 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 declare const D1_QUERY_REQUEST: {
+    readonly maxRetries: 0;
+};
 export declare class D1PreparedStatementREST<T = Record<string, unknown>> implements D1PreparedStatement {
     private readonly sql;
     private readonly boundParams;

package/dist/d1/d1PreparedStatement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"d1PreparedStatement.d.ts","sourceRoot":"","sources":["../../src/d1/d1PreparedStatement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAuC7C,qBAAa,uBAAuB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,mBAAmB;IAC9F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAE,OAAO,EAAO,EAM9G;IAED,gGAAgG;IAChG,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAErD;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAEK,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IASlC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;YAe5D,YAAY;CAY3B"}
+{"version":3,"file":"d1PreparedStatement.d.ts","sourceRoot":"","sources":["../../src/d1/d1PreparedStatement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA6B7C;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;aAAK,UAAU,EAAE,CAAC;CAAW,CAAC;AAY3D,qBAAa,uBAAuB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,mBAAmB;IAC9F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,GAAE,OAAO,EAAO,EAM9G;IAED,gGAAgG;IAChG,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAErD;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAED,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAEjC;IAEK,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IASlC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;YAmB5D,YAAY;CAgB3B"}

package/dist/d1/d1PreparedStatement.js

@@ -26,6 +26,16 @@ function mapMeta(restMeta) {
 		changes: restMeta?.changes ?? 0
 	};
 }
+/**
+* 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.
+*/
+const D1_QUERY_REQUEST = { maxRetries: 0 };
 /** The REST `params` array is strings; coerce each bound value the way the D1 REST API expects. */
 function toStringParams(params) {
 	return params.map((value) => {
@@ -70,7 +80,7 @@ var D1PreparedStatementREST = class D1PreparedStatementREST {
 			account_id: this.accountId,
 			sql: this.sql,
 			params
-		}))).result[0];
+		}, D1_QUERY_REQUEST))).result[0];
 		const rows = rawResult?.results?.rows ?? [];
 		if (options?.columnNames) return [rawResult?.results?.columns ?? [], ...rows];
 		return rows;
@@ -81,7 +91,7 @@ var D1PreparedStatementREST = class D1PreparedStatementREST {
 			account_id: this.accountId,
 			sql: this.sql,
 			params
-		}))).result[0];
+		}, D1_QUERY_REQUEST))).result[0];
 		return {
 			success: true,
 			meta: mapMeta(queryResult?.meta),
@@ -90,4 +100,4 @@ var D1PreparedStatementREST = class D1PreparedStatementREST {
 	}
 };
 //#endregion
-export { D1PreparedStatementREST };
+export { D1PreparedStatementREST, D1_QUERY_REQUEST };

package/dist/oauth/callback.d.ts

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/** 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 declare function readCallback(address: string, expect: CallbackExpectation): CallbackAnswer;
+//# sourceMappingURL=callback.d.ts.map

package/dist/oauth/callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["../../src/oauth/callback.ts"],"names":[],"mappings":"AAMA,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpH,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,cAAc,CAgCzF"}

package/dist/oauth/callback.js

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { commandName } from "@pithy-sh/core/src/cli/command";
+//#region src/oauth/callback.ts
+/**
+* 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.
+*/
+function readCallback(address, expect) {
+	const text = address.trim().replace(/^["']|["']$/g, "");
+	let 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, why) {
+	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}`
+	});
+}
+//#endregion
+export { readCallback };

package/dist/oauth/catalog.d.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/** One OAuth scope, as Cloudflare's catalog lists it. */
+export declare const OAuthScope: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OAuthScope = z.output<typeof OAuthScope>;
+/** The catalog's endpoint. Global: it needs authentication and no account. */
+export declare 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 declare function listOAuthScopes(options: {
+    apiToken: string;
+    fetch?: (url: string, init: {
+        headers: Record<string, string>;
+    }) => Promise<Response>;
+}): Promise<OAuthScope[]>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/oauth/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/oauth/catalog.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,yDAAyD;AACzD,eAAO,MAAM,UAAU;;;;iBAMyB,CAAC;AACjD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAIrD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,sDAAsD,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvF,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAOxB"}

package/dist/oauth/catalog.js

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { z } from "zod";
+//#region src/oauth/catalog.ts
+/** One OAuth scope, as Cloudflare's catalog lists it. */
+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`.");
+const ScopeList = z.object({ result: z.array(OAuthScope) });
+/** The catalog's endpoint. Global: it needs authentication and no account. */
+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.
+*/
+async function listOAuthScopes(options) {
+	const send = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+	const raw = await cloudflareRequest("list OAuth scopes", async () => {
+		return await (await send(OAUTH_SCOPES_URL, { headers: { authorization: `Bearer ${options.apiToken}` } })).json();
+	});
+	return decodeResponse(ScopeList, raw, "oauth scopes list").result;
+}
+//#endregion
+export { OAUTH_SCOPES_URL, OAuthScope, listOAuthScopes };

package/dist/oauth/client.d.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **The Pithy OAuth client: one, owned by us, authorized by each adopter against their own account (#759).**
+ *
+ * Registered 2026-10-15 on the `pithy.` account as `Pithy CLI` — a public client, so no secret ships in
+ * this package: `token_endpoint_auth_method: none`, `authorization_code` with PKCE `S256`, and
+ * `refresh_token`. Verified by a DNS TXT record on `pithy.sh`, its `client_uri`, and public, which is
+ * what lets a user on any account sign in to it. An identifier, not a credential.
+ */
+export declare const PITHY_OAUTH_CLIENT_ID = "5ae99cf157ae3e57d354e9c25ad3f7e2";
+/** The endpoints, from `https://dash.cloudflare.com/.well-known/openid-configuration`. */
+export declare const CLOUDFLARE_OAUTH: {
+    readonly authorize: "https://dash.cloudflare.com/oauth2/auth";
+    readonly token: "https://dash.cloudflare.com/oauth2/token";
+    readonly revoke: "https://dash.cloudflare.com/oauth2/revoke";
+};
+/** The slice of `fetch` this module calls: a form POST. Injected, so no test reaches Cloudflare. */
+export type OAuthFetch = (url: string, init: {
+    method: "POST";
+    headers: Record<string, string>;
+    body: URLSearchParams;
+    signal: AbortSignal;
+}) => Promise<Response>;
+/** A PKCE verifier and the challenge derived from it. The verifier never leaves the process that made it. */
+export interface PkcePair {
+    /** 43 base64url characters of randomness — sent only to the token endpoint, with the code. */
+    verifier: string;
+    /** `BASE64URL(SHA256(verifier))` — sent in the authorize URL. */
+    challenge: string;
+}
+/**
+ * A fresh PKCE pair.
+ *
+ * **This is what makes a pasted address safe to accept.** The code in the address a browser lands on is
+ * redeemable only with the verifier, and the verifier exists only in the CLI that opened the flow — so a
+ * code read off a screen, typed across an SSH session, or seen by anyone else is worth nothing elsewhere.
+ */
+export declare function pkcePair(): PkcePair;
+/** A fresh `state`. Cloudflare refuses one under eight characters; this is twenty-two. */
+export declare function oauthState(): string;
+/** What an authorize URL is built from. */
+export interface AuthorizeRequest {
+    /** The scopes to request — `sessionScopes`, never a hand-written list. */
+    scopes: readonly string[];
+    /** The loopback redirect: `http://127.0.0.1:<port>/callback`. */
+    redirectUri: string;
+    /** The `state` the callback must echo. */
+    state: string;
+    /** The PKCE challenge. */
+    challenge: string;
+}
+/** The URL a browser opens to sign in and consent. */
+export declare function authorizeUrl(request: AuthorizeRequest): string;
+/** The token endpoint's answer to a code exchange or a refresh. */
+export declare const OAuthTokenResponse: z.ZodObject<{
+    access_token: z.ZodString;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    token_type: z.ZodString;
+    expires_in: z.ZodNumber;
+    scope: z.ZodString;
+}, z.core.$strip>;
+export type OAuthTokenResponse = z.output<typeof OAuthTokenResponse>;
+/** A session's tokens, as this kit holds them. */
+export interface OAuthGrant {
+    /** The bearer token. */
+    accessToken: string;
+    /** The refresh token, or `null` when `offline_access` was not granted. */
+    refreshToken: string | null;
+    /** When {@link accessToken} stops working, from `expires_in` and the clock at the answer. */
+    expiresAt: Date;
+    /** The granted scopes, space-separated, verbatim. */
+    scope: string;
+}
+/** What every token-endpoint call takes beyond its own fields. */
+interface EndpointOptions {
+    /** Defaults to the global `fetch`. */
+    fetch?: OAuthFetch;
+    /** Defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/**
+ * Redeem an authorization code for a session.
+ *
+ * A refusal is a `core/upstream_failed` carrying Cloudflare's own description — an expired code, a
+ * `redirect_uri` that does not match, a verifier that does not fit the challenge. Each is a sign-in that
+ * has to start over, and the description is what says which.
+ */
+export declare function exchangeCode(request: {
+    code: string;
+    verifier: string;
+    redirectUri: string;
+} & EndpointOptions): Promise<OAuthGrant>;
+/** What a refresh comes back as: a new grant, or the server's refusal in its own words. */
+export type RefreshResult = {
+    kind: "refreshed";
+    grant: OAuthGrant;
+} | {
+    kind: "refused";
+    error: string;
+    description: string;
+};
+/**
+ * Renew a session without a browser.
+ *
+ * **A refusal is an answer, not a throw.** A spent, revoked or expired refresh token means *sign in
+ * again*, and the caller decides how to say so — at dispatch it is deferred to the first command that
+ * actually needs Cloudflare. Only a transport failure throws, because that one is worth retrying.
+ *
+ * The refresh token **rotates** on every use (measured). The one handed back must replace the one sent,
+ * on disk, before anything else reads it; the caller holds the profile's lock across that write.
+ */
+export declare function refreshGrant(request: {
+    refreshToken: string;
+} & EndpointOptions): Promise<RefreshResult>;
+/**
+ * Revoke one token at Cloudflare. Throws on a refusal, so `disconnect` never reports a revocation that did
+ * not happen — the local file is deleted either way, and the operator is told which half held.
+ */
+export declare function revokeToken(request: {
+    token: string;
+    hint: "access_token" | "refresh_token";
+} & EndpointOptions): Promise<void>;
+export {};
+//# sourceMappingURL=client.d.ts.map

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

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