@pithy-sh/cloudflare 0.4.1 → 0.5.0

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

package/dist/oauth/scopes.d.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The scopes every session asks for, whatever the project composes (#759).
+ *
+ * - `user-details.read` — `GET /user`, which is what turns an audit row's actor from a token's name into
+ *   the person who signed in.
+ * - `offline_access` — the only way Cloudflare issues a refresh token. Without it a session dies at the
+ *   hour and every command after it opens a browser (measured 2026-10-15).
+ * - `account-api-tokens.write` — the mint. A session mints `ci-system` and every worker-consumer token
+ *   the project declares, so the hand-made bootstrap token stops being a setup step.
+ * - `account-settings.read` — `GET /accounts`, so the account is discovered rather than stored. On its own
+ *   it lists the account; `d1.write` alone listed nothing (both measured 2026-10-15), so discovery must not
+ *   lean on whichever other scope a project happens to request.
+ * - `zone.read` — `pithy init` and `pithy worker add` offer the account's real zones, and `init` asks
+ *   before there is a project whose capabilities could say so. Read-only, as {@link OAUTH_SCOPES} says of it.
+ *
+ * Everything else comes from the project's own token permissions, through {@link sessionScopes}.
+ */
+export declare const SESSION_BASE_SCOPES: readonly ["user-details.read", "offline_access", "account-api-tokens.write", "account-settings.read", "zone.read"];
+/**
+ * The scopes Cloudflare's consent screen lists under **"Sensitive scopes"**, switched off, by the name it
+ * shows them under.
+ *
+ * **Approving with one switched off does not grant the rest.** The dashboard answers *"We could not
+ * complete the authorization. Please check your network connection and try again."* and no callback
+ * ever arrives (measured 2026-10-15). So `connect` names these before it opens the browser, and its
+ * timeout names them as the likeliest cause.
+ *
+ * **The list is ours to keep, because Cloudflare's is not published.** `GET /oauth/scopes` carries an
+ * id, a name, a category and nothing that marks a scope sensitive; only the consent screen says. Add to
+ * it when a consent screen shows another.
+ */
+export declare const SENSITIVE_SCOPES: Readonly<Record<string, string>>;
+/**
+ * The scopes a session needs to act for a project, and to mint every token it declares: the base, then
+ * the scope of each permission key, de-duped in first-seen order.
+ *
+ * **Derived, never listed.** Cloudflare's delegation rule binds the session as it binds a token — a mint
+ * whose groups the session does not hold is refused — so the request is exactly the union of what the
+ * project's tokens carry. A capability the project does not compose contributes nothing to it, and so
+ * nothing to the consent screen the adopter reads.
+ */
+export declare function sessionScopes(permissionKeys: readonly string[]): string[];
+/**
+ * The requested scopes a grant does not carry, in request order.
+ *
+ * `granted` is the token endpoint's `scope`: one space-separated string. Today Cloudflare fails rather
+ * than grant a subset, so this should always be empty; it is checked because that is Cloudflare's
+ * behavior to change, and a session missing `account-api-tokens.write` would fail at the first mint.
+ */
+export declare function missingScopes(requested: readonly string[], granted: string): string[];
+/** One sensitive scope a request carries, by its id and the name the consent screen shows. */
+export interface SensitiveScope {
+    /** The catalog id: `account-api-tokens.write`. */
+    id: string;
+    /** What the consent screen calls it: "Account API Tokens Write". */
+    name: string;
+}
+/** The sensitive scopes in a request, in request order. See {@link SENSITIVE_SCOPES}. */
+export declare function sensitiveScopesIn(scopes: readonly string[]): SensitiveScope[];
+//# sourceMappingURL=scopes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/oauth/scopes.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,YAC9B,mBAAmB,EACnB,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,EACvB,WAAW,CACH,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAMzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGrF;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,EAAE,CAK7E"}

package/dist/oauth/scopes.js

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { oauthScopesFor } from "../tokens/permissions.js";
+//#region src/oauth/scopes.ts
+/**
+* The scopes every session asks for, whatever the project composes (#759).
+*
+* - `user-details.read` — `GET /user`, which is what turns an audit row's actor from a token's name into
+*   the person who signed in.
+* - `offline_access` — the only way Cloudflare issues a refresh token. Without it a session dies at the
+*   hour and every command after it opens a browser (measured 2026-10-15).
+* - `account-api-tokens.write` — the mint. A session mints `ci-system` and every worker-consumer token
+*   the project declares, so the hand-made bootstrap token stops being a setup step.
+* - `account-settings.read` — `GET /accounts`, so the account is discovered rather than stored. On its own
+*   it lists the account; `d1.write` alone listed nothing (both measured 2026-10-15), so discovery must not
+*   lean on whichever other scope a project happens to request.
+* - `zone.read` — `pithy init` and `pithy worker add` offer the account's real zones, and `init` asks
+*   before there is a project whose capabilities could say so. Read-only, as {@link OAUTH_SCOPES} says of it.
+*
+* Everything else comes from the project's own token permissions, through {@link sessionScopes}.
+*/
+const SESSION_BASE_SCOPES = [
+	"user-details.read",
+	"offline_access",
+	"account-api-tokens.write",
+	"account-settings.read",
+	"zone.read"
+];
+/**
+* The scopes Cloudflare's consent screen lists under **"Sensitive scopes"**, switched off, by the name it
+* shows them under.
+*
+* **Approving with one switched off does not grant the rest.** The dashboard answers *"We could not
+* complete the authorization. Please check your network connection and try again."* and no callback
+* ever arrives (measured 2026-10-15). So `connect` names these before it opens the browser, and its
+* timeout names them as the likeliest cause.
+*
+* **The list is ours to keep, because Cloudflare's is not published.** `GET /oauth/scopes` carries an
+* id, a name, a category and nothing that marks a scope sensitive; only the consent screen says. Add to
+* it when a consent screen shows another.
+*/
+const SENSITIVE_SCOPES = { "account-api-tokens.write": "Account API Tokens Write" };
+/**
+* The scopes a session needs to act for a project, and to mint every token it declares: the base, then
+* the scope of each permission key, de-duped in first-seen order.
+*
+* **Derived, never listed.** Cloudflare's delegation rule binds the session as it binds a token — a mint
+* whose groups the session does not hold is refused — so the request is exactly the union of what the
+* project's tokens carry. A capability the project does not compose contributes nothing to it, and so
+* nothing to the consent screen the adopter reads.
+*/
+function sessionScopes(permissionKeys) {
+	const scopes = [...SESSION_BASE_SCOPES];
+	for (const scope of oauthScopesFor(permissionKeys)) if (!scopes.includes(scope)) scopes.push(scope);
+	return scopes;
+}
+/**
+* The requested scopes a grant does not carry, in request order.
+*
+* `granted` is the token endpoint's `scope`: one space-separated string. Today Cloudflare fails rather
+* than grant a subset, so this should always be empty; it is checked because that is Cloudflare's
+* behavior to change, and a session missing `account-api-tokens.write` would fail at the first mint.
+*/
+function missingScopes(requested, granted) {
+	const held = new Set(granted.split(/\s+/).filter(Boolean));
+	return requested.filter((scope) => !held.has(scope));
+}
+/** The sensitive scopes in a request, in request order. See {@link SENSITIVE_SCOPES}. */
+function sensitiveScopesIn(scopes) {
+	return scopes.flatMap((id) => {
+		const name = SENSITIVE_SCOPES[id];
+		return name === void 0 ? [] : [{
+			id,
+			name
+		}];
+	});
+}
+//#endregion
+export { SENSITIVE_SCOPES, SESSION_BASE_SCOPES, missingScopes, sensitiveScopesIn, sessionScopes };

package/dist/secrets/secretsStoreManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAeqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AA4BxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBtG;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEzD;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;OAIG;YACW,UAAU;CAGzB"}
+{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAeqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AA4BxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBtG;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEzD;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;OAIG;YACW,UAAU;CAGzB"}

package/dist/secrets/secretsStoreManager.js

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
-import { z } from "zod";
 import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { remedy } from "@pithy-sh/core/src/cli/command";
 import { JsonDate } from "@pithy-sh/core/src/data/codecs";
 //#region src/secrets/secretsStoreManager.ts
 /** Scopes attached to every secret we create. CF requires at least one; "workers" is the bind target. */
@@ -172,7 +173,7 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 		const target = named[0];
 		if (!target) throw new NotFoundError({
 			message: `Secret '${name}' is not in the store, so there is nothing to update.`,
-			action: "Run `pithy secrets provision` to establish the entry, then run this again.",
+			action: `${remedy("secrets provision").say((command) => `Run \`${command}\`.`)} It establishes the entry; then run this again.`,
 			detail: `update secret ${name}: no live entry of that name, and this verb never creates one`
 		});
 		if (named.length > 1) throw new ConflictError({

package/dist/test-utils/settle.d.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **Waiting on an eventually consistent control plane, for the live suites.** One budget and one rule, shared
+ * by `@pithy-sh/cloudflare`'s Vectorize suite and `@pithy-sh/vector`'s, because the cloudflare suite kept a
+ * 60s budget and a single confirming read of its own and failed on exactly that (#709).
+ *
+ * **The budget is 120s, and 300s for a metadata index.** A Vectorize index became visible 25-50s after the
+ * call that made it, measured live, and an upsert became queryable in about 30s. A metadata index is slower:
+ * about 97s on one run of #709 and over 120s on the next, so its waits take {@link METADATA_INDEX_SETTLE_MS}.
+ *
+ * **A metadata-index wait compares names and types, never a count.** {@link metadataIndexesSettled} is the
+ * predicate; a list of the right length can still be the wrong list.
+ *
+ * **One confirming read proves nothing.** The metadata-index list is eventually consistent *and not
+ * monotonic*: a 3-minute probe watched it report `[]` for 26s, then both properties, then one of the two 18s
+ * later with nothing else running, then both again. So {@link waitForStable} waits for {@link STABLE_READS}
+ * agreeing reads in a row and hands back that snapshot, and a caller asserts against the snapshot rather
+ * than a fresh read, which can disagree with the one before it.
+ *
+ * **A test that waits several times shares one deadline across them.** Each wait's own budget bounds that
+ * wait and nothing else, so a test making eight of them in a row could outrun its vitest timeout with every
+ * step inside budget. Vitest then abandoned the body mid-poll: the failure said only "Test timed out", and the
+ * teardown that deletes the index never ran (#709). Pass the same {@link SettleOptions.deadline} to every
+ * wait and the step in progress when it passes fails by name, inside the body, where the teardown still runs.
+ */
+/** Ceiling for any one wait. Measured at 25-50s for a control-plane change, and about 30s for an upsert. */
+export declare const SETTLE_TIMEOUT_MS = 120000;
+/**
+ * Ceiling for a metadata-index wait, and only for that. A metadata index is the slowest change Vectorize
+ * applies: on #709 one settled in about 97s and the next was still unsettled at 120s, so the shared budget
+ * undercut exactly this wait. `pithy vector provision` waits on the same measurement.
+ */
+export declare const METADATA_INDEX_SETTLE_MS = 300000;
+/**
+ * Consecutive agreeing reads that count as settled. Three, because one confirming read can be a stale replica,
+ * and two in a row six seconds apart is a far weaker coincidence.
+ */
+export declare const STABLE_READS = 3;
+/** How often a poll re-checks. Vectorize applies changes in tens of seconds, so a tighter loop only burns quota. */
+export declare const POLL_INTERVAL_MS = 2000;
+/** How long to wait and how often to look. Every field defaults to the shared budget above. */
+export interface SettleOptions {
+    /** Give up after this long. Defaults to {@link SETTLE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Re-check this often. Defaults to {@link POLL_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Agreeing reads in a row that count as settled, for {@link waitForStable}. Defaults to {@link STABLE_READS}. */
+    stableReads?: number;
+    /**
+     * An absolute deadline (ms since the epoch) shared by every wait in a test. A wait gives up at whichever
+     * comes first, its own `timeoutMs` or this, and says which.
+     */
+    deadline?: number;
+}
+/**
+ * Poll until `ready`, or fail with a message naming what was being waited for. A bare timeout tells the next
+ * reader nothing; naming the step tells them whether Cloudflare was slow or something is actually broken.
+ */
+export declare function waitFor(what: string, ready: () => Promise<boolean>, options?: SettleOptions): Promise<void>;
+/**
+ * Poll until `settled` holds on {@link STABLE_READS} consecutive reads, and return the last value read. The
+ * caller asserts against the returned snapshot, never against a fresh read.
+ */
+export declare function waitForStable<T>(what: string, read: () => Promise<T>, settled: (value: T) => boolean, options?: SettleOptions): Promise<T>;
+/**
+ * The settle predicate for a metadata-index list: every declared index is live, under its own name and its own
+ * type. The rule `compareMetadataIndexes` applies with nothing missing and nothing mismatched, restated here
+ * because this package cannot import `@pithy-sh/vector`. A count is not enough: a list of the right length
+ * with the wrong names passed the predicate this replaced. An undeclared extra does not block it.
+ */
+export declare function metadataIndexesSettled(declared: readonly {
+    propertyName: string;
+    indexType: string;
+}[]): (live: readonly {
+    propertyName: string;
+    indexType: string;
+}[]) => boolean;
+//# sourceMappingURL=settle.d.ts.map

package/dist/test-utils/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../src/test-utils/settle.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,SAAU,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kHAAkH;IAClH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmBD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrH;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAC9B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,GAC/D,CAAC,IAAI,EAAE,SAAS;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,OAAO,CAK3E"}

package/dist/test-utils/settle.js

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/test-utils/settle.ts
+/**
+* **Waiting on an eventually consistent control plane, for the live suites.** One budget and one rule, shared
+* by `@pithy-sh/cloudflare`'s Vectorize suite and `@pithy-sh/vector`'s, because the cloudflare suite kept a
+* 60s budget and a single confirming read of its own and failed on exactly that (#709).
+*
+* **The budget is 120s, and 300s for a metadata index.** A Vectorize index became visible 25-50s after the
+* call that made it, measured live, and an upsert became queryable in about 30s. A metadata index is slower:
+* about 97s on one run of #709 and over 120s on the next, so its waits take {@link METADATA_INDEX_SETTLE_MS}.
+*
+* **A metadata-index wait compares names and types, never a count.** {@link metadataIndexesSettled} is the
+* predicate; a list of the right length can still be the wrong list.
+*
+* **One confirming read proves nothing.** The metadata-index list is eventually consistent *and not
+* monotonic*: a 3-minute probe watched it report `[]` for 26s, then both properties, then one of the two 18s
+* later with nothing else running, then both again. So {@link waitForStable} waits for {@link STABLE_READS}
+* agreeing reads in a row and hands back that snapshot, and a caller asserts against the snapshot rather
+* than a fresh read, which can disagree with the one before it.
+*
+* **A test that waits several times shares one deadline across them.** Each wait's own budget bounds that
+* wait and nothing else, so a test making eight of them in a row could outrun its vitest timeout with every
+* step inside budget. Vitest then abandoned the body mid-poll: the failure said only "Test timed out", and the
+* teardown that deletes the index never ran (#709). Pass the same {@link SettleOptions.deadline} to every
+* wait and the step in progress when it passes fails by name, inside the body, where the teardown still runs.
+*/
+/** Ceiling for any one wait. Measured at 25-50s for a control-plane change, and about 30s for an upsert. */
+const SETTLE_TIMEOUT_MS = 12e4;
+/**
+* Ceiling for a metadata-index wait, and only for that. A metadata index is the slowest change Vectorize
+* applies: on #709 one settled in about 97s and the next was still unsettled at 120s, so the shared budget
+* undercut exactly this wait. `pithy vector provision` waits on the same measurement.
+*/
+const METADATA_INDEX_SETTLE_MS = 3e5;
+/**
+* Consecutive agreeing reads that count as settled. Three, because one confirming read can be a stale replica,
+* and two in a row six seconds apart is a far weaker coincidence.
+*/
+const STABLE_READS = 3;
+/** How often a poll re-checks. Vectorize applies changes in tens of seconds, so a tighter loop only burns quota. */
+const POLL_INTERVAL_MS = 2e3;
+/** When a wait gives up, and the clause its timeout message ends the step name with. */
+function limitOf(options, started) {
+	const own = started + (options.timeoutMs ?? 12e4);
+	if (options.deadline !== void 0 && options.deadline < own) return {
+		deadline: options.deadline,
+		why: " (the shared deadline for this test ran out)"
+	};
+	return {
+		deadline: own,
+		why: ""
+	};
+}
+function seconds(ms) {
+	return Math.round(ms / 1e3);
+}
+function pause(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Poll until `ready`, or fail with a message naming what was being waited for. A bare timeout tells the next
+* reader nothing; naming the step tells them whether Cloudflare was slow or something is actually broken.
+*/
+async function waitFor(what, ready, options = {}) {
+	const started = Date.now();
+	const { deadline, why } = limitOf(options, started);
+	for (;;) {
+		if (await ready()) return;
+		if (Date.now() >= deadline) throw new Error(`Timed out after ${seconds(Date.now() - started)}s waiting for ${what}${why}. Cloudflare applies this change asynchronously — this is either a slower-than-usual apply or a real failure.`);
+		await pause(options.intervalMs ?? 2e3);
+	}
+}
+/**
+* Poll until `settled` holds on {@link STABLE_READS} consecutive reads, and return the last value read. The
+* caller asserts against the returned snapshot, never against a fresh read.
+*/
+async function waitForStable(what, read, settled, options = {}) {
+	const started = Date.now();
+	const needed = options.stableReads ?? 3;
+	const { deadline, why } = limitOf(options, started);
+	let agreed = 0;
+	let last = await read();
+	for (;;) {
+		agreed = settled(last) ? agreed + 1 : 0;
+		if (agreed >= needed) return last;
+		if (Date.now() >= deadline) throw new Error(`Timed out after ${seconds(Date.now() - started)}s waiting for ${what} to settle across ${needed} reads${why}. Last read: ${JSON.stringify(last)}.`);
+		await pause(options.intervalMs ?? 2e3);
+		last = await read();
+	}
+}
+/**
+* The settle predicate for a metadata-index list: every declared index is live, under its own name and its own
+* type. The rule `compareMetadataIndexes` applies with nothing missing and nothing mismatched, restated here
+* because this package cannot import `@pithy-sh/vector`. A count is not enough: a list of the right length
+* with the wrong names passed the predicate this replaced. An undeclared extra does not block it.
+*/
+function metadataIndexesSettled(declared) {
+	return (live) => {
+		const types = new Map(live.map((entry) => [entry.propertyName, entry.indexType]));
+		return declared.every((entry) => types.get(entry.propertyName) === entry.indexType);
+	};
+}
+//#endregion
+export { METADATA_INDEX_SETTLE_MS, POLL_INTERVAL_MS, SETTLE_TIMEOUT_MS, STABLE_READS, metadataIndexesSettled, waitFor, waitForStable };

package/dist/tokens/accountTokensManager.d.ts

@@ -57,7 +57,7 @@ export declare const MintedAccountToken: z.ZodObject<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>>;
+    }>>, unknown>;
 }, z.core.$strip>;
 export type MintedAccountToken = z.output<typeof MintedAccountToken>;
 /**
@@ -72,10 +72,10 @@ export declare const AccountTokenPolicy: z.ZodObject<{
     effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         allow: "allow";
         deny: "deny";
-    }>>>;
+    }>>, unknown>;
     permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-    }, z.core.$strip>>>>;
+    }, z.core.$strip>>>, unknown>;
     resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
 export type AccountTokenPolicy = z.output<typeof AccountTokenPolicy>;
@@ -96,17 +96,17 @@ export declare const AccountTokenSummary: z.ZodObject<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>>;
+    }>>, unknown>;
     policies: z.ZodCatch<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
         effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
             allow: "allow";
             deny: "deny";
-        }>>>;
+        }>>, unknown>;
         permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
-        }, z.core.$strip>>>>;
+        }, z.core.$strip>>>, unknown>;
         resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>>>>>;
+    }, z.core.$strip>>>, unknown>>;
 }, z.core.$strip>;
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
 /**

package/dist/tokens/permissions.d.ts

@@ -28,6 +28,45 @@ export declare const PERMISSION_GROUPS: {
 };
 /** A known permission key — one of {@link PERMISSION_GROUPS}'s keys. */
 export type PermissionKey = keyof typeof PERMISSION_GROUPS;
+/**
+ * **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.
+ */
+export declare const OAUTH_SCOPES: {
+    readonly "d1:read": readonly ["d1.read"];
+    readonly "d1:write": readonly ["d1.write"];
+    readonly "workers:write": readonly ["workers-scripts.write"];
+    readonly "secrets:read": readonly ["secrets-store.read"];
+    readonly "secrets:write": readonly ["secrets-store.write"];
+    readonly "email:routing": readonly ["email-routing-rule.write"];
+    readonly "kv:write": readonly ["workers-kv-storage.write"];
+    readonly "r2:read": readonly ["workers-r2.read"];
+    readonly "r2:write": readonly ["workers-r2.write"];
+    readonly "vectorize:read": readonly ["vectorize.read"];
+    readonly "vectorize:write": readonly ["vectorize.write"];
+    readonly "ai:read": readonly ["ai.read"];
+    readonly "zone:read": readonly ["zone.read"];
+    readonly "routes:write": readonly ["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.
+ */
+export declare function oauthScopesFor(keys: readonly string[]): string[];
 /**
  * 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.