@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/dist/media/imageManager.js

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { cloudflareRequest } from "../client/errors.js";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
 //#region src/media/imageManager.ts
 /**
 * Per-request CF SDK options for every Images call: a 10s timeout and up to 3 retries. Uploads and
@@ -19,6 +20,30 @@ const requestOptions = {
 function encodeMetadata(metadata) {
 	return metadata === void 0 || metadata === null ? metadata : JSON.stringify(metadata);
 }
+/** One of the account's Images URL-signing keys. The value is the HMAC secret signed URLs are minted with. */
+const ImagesSigningKey = z.object({
+	name: z.string().min(1).describe("The key's name. Cloudflare provisions one named `default`."),
+	value: z.string().min(1).describe("The key itself — the HMAC-SHA256 secret a signed delivery URL is minted with.")
+}).describe("One Cloudflare Images URL-signing key.");
+const SigningKeysResponse = z.object({ keys: z.array(ImagesSigningKey).optional().describe("The account's signing keys.") }).describe("The Images signing-keys response.");
+/** One Images variant, and whether it serves an image without a signature whatever the image requires. */
+const ImagesVariant = z.object({
+	id: z.string().describe("The variant's name, as it appears in a delivery URL."),
+	neverRequireSignedURLs: z.boolean().describe("Whether this variant serves every image unsigned, even one uploaded with requireSignedURLs.")
+}).describe("One Cloudflare Images variant's signing posture.");
+const VariantsResponse = z.object({ variants: z.record(z.string(), z.object({
+	id: z.string().describe("The variant name."),
+	neverRequireSignedURLs: z.boolean().optional().describe("Whether it ignores signing.")
+}).describe("One variant as the API returns it.")).optional().describe("Every variant, keyed by name.") }).describe("The Images variants response.");
+/** Parse an Images response the SDK types loosely, refusing a shape we cannot read. */
+function parseResponse(schema, response, what) {
+	const result = schema.safeParse(response);
+	if (!result.success) throw new CloudflareInvalidResponseError({
+		message: `An Images ${what} response had an unexpected shape.`,
+		detail: result.error.message
+	});
+	return result.data;
+}
 /**
 * Out-of-Worker Cloudflare Images access over the REST API: upload, fetch, edit, delete, list, and
 * direct-upload URLs from a CLI/CI/provisioning context. Image metadata is an arbitrary
@@ -88,6 +113,37 @@ var CloudflareImageManager = class extends CloudflareManager {
 			return allImages;
 		});
 	}
+	/**
+	* The account's URL-signing keys — what a signed delivery URL for an image uploaded with
+	* `requireSignedURLs` is minted with. Cloudflare provisions a `default` key per account.
+	*/
+	async signingKeys() {
+		return cloudflareRequest("Images list signing keys", async () => {
+			const response = await this.getClient().images.v1.keys.list({ account_id: this.accountId }, requestOptions);
+			return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+		});
+	}
+	/** Create a named signing key, or roll it if it exists. Answers with every key the account then holds. */
+	async createSigningKey(name) {
+		return cloudflareRequest(`Images create signing key '${name}'`, async () => {
+			const response = await this.getClient().images.v1.keys.update(name, { account_id: this.accountId }, requestOptions);
+			return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+		});
+	}
+	/**
+	* Every variant, with whether it serves unsigned. A variant set to `neverRequireSignedURLs` delivers a
+	* private image to anyone holding its URL, which is why media's provisioning reads this.
+	*/
+	async listVariants() {
+		return cloudflareRequest("Images list variants", async () => {
+			const response = await this.getClient().images.v1.variants.list({ account_id: this.accountId }, requestOptions);
+			const variants = parseResponse(VariantsResponse, response, "variants").variants ?? {};
+			return Object.values(variants).map((variant) => ({
+				id: variant.id,
+				neverRequireSignedURLs: variant.neverRequireSignedURLs === true
+			}));
+		});
+	}
 	getServiceType() {
 		return "Cloudflare Images";
 	}
@@ -102,4 +158,4 @@ var CloudflareImageManager = class extends CloudflareManager {
 	}
 };
 //#endregion
-export { CloudflareImageManager };
+export { CloudflareImageManager, ImagesSigningKey, ImagesVariant };

package/dist/media/streamManager.d.ts

@@ -44,6 +44,16 @@ export declare const StreamDownloadStatus: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type StreamDownloadStatus = z.infer<typeof StreamDownloadStatus>;
+/**
+ * A Stream signing key: what a signed playback token for a video uploaded with `requireSignedURLs` is
+ * signed with. The JWK is base64 of the key's JSON, as Cloudflare returns it — a single line, so it is
+ * the form stored, where the PEM is not.
+ */
+export declare const StreamSigningKey: z.ZodObject<{
+    id: z.ZodString;
+    jwk: z.ZodString;
+}, z.core.$strip>;
+export type StreamSigningKey = z.infer<typeof StreamSigningKey>;
 /**
  * Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
  * and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
@@ -78,6 +88,11 @@ export declare class CloudflareStreamManager extends CloudflareManager {
     audioDownloadStatus(videoId: string): Promise<DownloadEntry>;
     /** Create a direct-upload URL for a client-side video upload. */
     createDirectUpload(params: Omit<DirectUploadCreateParams, "account_id">): Promise<DirectUploadCreateResponse>;
+    /**
+     * Create a signing key. Cloudflare returns the private half once, on creation, and never again — so the
+     * caller stores it, and a lost key is replaced by creating another.
+     */
+    createSigningKey(): Promise<StreamSigningKey>;
     getServiceType(): string;
     /** Prove access by listing videos. Never throws. */
     validateServiceAccess(): Promise<boolean>;

package/dist/media/streamManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamManager.d.ts","sourceRoot":"","sources":["../../src/media/streamManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACtH,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWtD;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;iBAM8C,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;iBAKwD,CAAC;AAC1F,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA2BxE;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,wCAAwC;IAClC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED,sCAAsC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIrD;IAED,8CAA8C;IACxC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAI/F;IAED,iEAAiE;IAC3D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED,qEAAqE;IAC/D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BjE;IAED;;;OAGG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAUjE;IAED,iEAAiE;IAC3D,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAIlH;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}
+{"version":3,"file":"streamManager.d.ts","sourceRoot":"","sources":["../../src/media/streamManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,2CAA2C,CAAC;AACtH,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWtD;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;iBAM8C,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;iBAKwD,CAAC;AAC1F,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA2BxE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;iBAKoB,CAAC;AAClD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,wCAAwC;IAClC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED,sCAAsC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIrD;IAED,8CAA8C;IACxC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAI/F;IAED,iEAAiE;IAC3D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED,qEAAqE;IAC/D,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CASxE;IAED;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BjE;IAED;;;OAGG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAUjE;IAED,iEAAiE;IAC3D,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAIlH;IAED;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAelD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,oDAAoD;IAC9C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/media/streamManager.js

@@ -50,6 +50,15 @@ function parseDownloadStatus(response) {
 	return result.data;
 }
 /**
+* A Stream signing key: what a signed playback token for a video uploaded with `requireSignedURLs` is
+* signed with. The JWK is base64 of the key's JSON, as Cloudflare returns it — a single line, so it is
+* the form stored, where the PEM is not.
+*/
+const StreamSigningKey = z.object({
+	id: z.string().min(1).describe("The key id — the `kid` a signed token names."),
+	jwk: z.string().min(1).describe("The RSA private key as base64-encoded JWK, as Cloudflare returns it.")
+}).describe("One Cloudflare Stream signing key.");
+/**
 * Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
 * and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
 * the SDK's own `Video` shape — this class imposes none of its own.
@@ -130,6 +139,24 @@ var CloudflareStreamManager = class extends CloudflareManager {
 			...params
 		}, requestOptions));
 	}
+	/**
+	* Create a signing key. Cloudflare returns the private half once, on creation, and never again — so the
+	* caller stores it, and a lost key is replaced by creating another.
+	*/
+	async createSigningKey() {
+		return cloudflareRequest("Stream create signing key", async () => {
+			const response = await this.getClient().stream.keys.create({
+				account_id: this.accountId,
+				body: {}
+			}, requestOptions);
+			const parsed = StreamSigningKey.safeParse(response);
+			if (!parsed.success) throw new CloudflareInvalidResponseError({
+				message: "A Stream signing-key response had an unexpected shape.",
+				detail: parsed.error.message
+			});
+			return parsed.data;
+		});
+	}
 	getServiceType() {
 		return "Cloudflare Stream";
 	}
@@ -144,4 +171,4 @@ var CloudflareStreamManager = class extends CloudflareManager {
 	}
 };
 //#endregion
-export { CloudflareStreamManager, DownloadEntry, StreamDownloadStatus };
+export { CloudflareStreamManager, DownloadEntry, StreamDownloadStatus, StreamSigningKey };

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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"}

package/dist/oauth/client.js

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { UpstreamError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { commandName } from "@pithy-sh/core/src/cli/command";
+import { createHash, randomBytes } from "node:crypto";
+//#region src/oauth/client.ts
+/**
+* **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.
+*/
+const PITHY_OAUTH_CLIENT_ID = "5ae99cf157ae3e57d354e9c25ad3f7e2";
+/** The endpoints, from `https://dash.cloudflare.com/.well-known/openid-configuration`. */
+const CLOUDFLARE_OAUTH = {
+	authorize: "https://dash.cloudflare.com/oauth2/auth",
+	token: "https://dash.cloudflare.com/oauth2/token",
+	revoke: "https://dash.cloudflare.com/oauth2/revoke"
+};
+/** How long a token-endpoint call may take before it is a timeout rather than a wait. */
+const OAUTH_TIMEOUT_MS = 3e4;
+/**
+* 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.
+*/
+function pkcePair() {
+	const verifier = randomBytes(32).toString("base64url");
+	return {
+		verifier,
+		challenge: createHash("sha256").update(verifier).digest("base64url")
+	};
+}
+/** A fresh `state`. Cloudflare refuses one under eight characters; this is twenty-two. */
+function oauthState() {
+	return randomBytes(16).toString("base64url");
+}
+/** The URL a browser opens to sign in and consent. */
+function authorizeUrl(request) {
+	const url = new URL(CLOUDFLARE_OAUTH.authorize);
+	url.search = new URLSearchParams({
+		response_type: "code",
+		client_id: PITHY_OAUTH_CLIENT_ID,
+		redirect_uri: request.redirectUri,
+		scope: request.scopes.join(" "),
+		state: request.state,
+		code_challenge: request.challenge,
+		code_challenge_method: "S256"
+	}).toString();
+	return url.toString();
+}
+/** The token endpoint's answer to a code exchange or a refresh. */
+const OAuthTokenResponse = z.object({
+	access_token: z.string().min(1).describe("The bearer token API calls carry. One hour, measured."),
+	refresh_token: z.string().min(1).optional().describe("Present only when `offline_access` was granted. Rotates on every use."),
+	token_type: z.string().describe("Always `bearer`."),
+	expires_in: z.number().int().positive().describe("Seconds until the access token expires."),
+	scope: z.string().describe("The scopes granted, space-separated. Compare it with what was requested.")
+}).describe("Cloudflare's token endpoint response, `POST /oauth2/token`.");
+/**
+* The token endpoint's refusal body, per RFC 6749 §5.2.
+*
+* **Not the REST API's `errors[]`, so not `cloudflareRefusal`'s to word.** That composer reads the
+* envelope `api.cloudflare.com` answers with and writes a permission-grant action for it; the OAuth
+* endpoints on `dash.cloudflare.com` answer `{ error, error_description }`, and the remedy is a sign-in,
+* not a grant. They are a service we do not control, so a refusal is `core/upstream_failed`.
+*/
+const OAuthErrorResponse = z.object({
+	error: z.string(),
+	error_description: z.string().optional()
+});
+/** One form POST to an OAuth endpoint: the status, and the body parsed as JSON where it is JSON. */
+async function post(operation, url, form, options) {
+	const send = options.fetch ?? globalThis.fetch;
+	return cloudflareRequest(operation, async () => {
+		const response = await send(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body: new URLSearchParams(form),
+			signal: AbortSignal.timeout(OAUTH_TIMEOUT_MS)
+		});
+		const text = await response.text();
+		let body;
+		try {
+			body = text === "" ? {} : JSON.parse(text);
+		} catch {
+			body = {
+				error: "invalid_response",
+				error_description: text.slice(0, 200)
+			};
+		}
+		return {
+			status: response.status,
+			body
+		};
+	});
+}
+/** The refusal's own words, or `null` when the body is not an RFC 6749 error. */
+function refusalOf(body) {
+	const parsed = OAuthErrorResponse.safeParse(body);
+	if (!parsed.success) return null;
+	return {
+		error: parsed.data.error,
+		description: parsed.data.error_description ?? parsed.data.error
+	};
+}
+function grantOf(body, context, now, keepRefresh) {
+	const token = decodeResponse(OAuthTokenResponse, body, context);
+	return {
+		accessToken: token.access_token,
+		refreshToken: token.refresh_token ?? keepRefresh,
+		expiresAt: new Date(now.getTime() + token.expires_in * 1e3),
+		scope: token.scope
+	};
+}
+/**
+* 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.
+*/
+async function exchangeCode(request) {
+	const now = request.now ?? (() => /* @__PURE__ */ new Date());
+	const answer = await post("exchange the sign-in code", CLOUDFLARE_OAUTH.token, {
+		grant_type: "authorization_code",
+		code: request.code,
+		redirect_uri: request.redirectUri,
+		client_id: PITHY_OAUTH_CLIENT_ID,
+		code_verifier: request.verifier
+	}, request);
+	if (answer.status !== 200) {
+		const refusal = refusalOf(answer.body);
+		throw new UpstreamError({
+			message: `Cloudflare refused the sign-in: ${refusal?.description ?? `HTTP ${answer.status}`}`,
+			action: `Run ${commandName("cloudflare connect")} again. A sign-in code works once, and only for a few minutes.`,
+			detail: `token endpoint ${answer.status}: ${refusal?.error ?? "no error body"}`
+		});
+	}
+	return grantOf(answer.body, "token exchange", now(), null);
+}
+/**
+* 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.
+*/
+async function refreshGrant(request) {
+	const now = request.now ?? (() => /* @__PURE__ */ new Date());
+	const answer = await post("renew the Cloudflare session", CLOUDFLARE_OAUTH.token, {
+		grant_type: "refresh_token",
+		refresh_token: request.refreshToken,
+		client_id: PITHY_OAUTH_CLIENT_ID
+	}, request);
+	if (answer.status !== 200) return {
+		kind: "refused",
+		...refusalOf(answer.body) ?? {
+			error: `http_${answer.status}`,
+			description: `HTTP ${answer.status}`
+		}
+	};
+	return {
+		kind: "refreshed",
+		grant: grantOf(answer.body, "token refresh", now(), request.refreshToken)
+	};
+}
+/**
+* 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.
+*/
+async function revokeToken(request) {
+	const answer = await post("revoke the Cloudflare session", CLOUDFLARE_OAUTH.revoke, {
+		token: request.token,
+		token_type_hint: request.hint,
+		client_id: PITHY_OAUTH_CLIENT_ID
+	}, request);
+	if (answer.status !== 200) {
+		const refusal = refusalOf(answer.body);
+		throw new UpstreamError({
+			message: `Cloudflare did not revoke the session: ${refusal?.description ?? `HTTP ${answer.status}`}`,
+			action: "Sign in to the Cloudflare dashboard and revoke the Pithy CLI's access to your account there.",
+			detail: `revoke endpoint ${answer.status}: ${refusal?.error ?? "no error body"}`
+		});
+	}
+}
+//#endregion
+export { CLOUDFLARE_OAUTH, OAuthTokenResponse, PITHY_OAUTH_CLIENT_ID, authorizeUrl, exchangeCode, oauthState, pkcePair, refreshGrant, revokeToken };