@pithy-sh/cloudflare 0.4.2 → 0.5.0

package/src/oauth/client.ts

@@ -0,0 +1,265 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createHash, randomBytes } from "node:crypto";
+import { commandName } from "@pithy-sh/core/src/cli/command";
+import { UpstreamError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+
+/**
+ * **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 const PITHY_OAUTH_CLIENT_ID = "5ae99cf157ae3e57d354e9c25ad3f7e2";
+
+/** The endpoints, from `https://dash.cloudflare.com/.well-known/openid-configuration`. */
+export const CLOUDFLARE_OAUTH = {
+  authorize: "https://dash.cloudflare.com/oauth2/auth",
+  token: "https://dash.cloudflare.com/oauth2/token",
+  revoke: "https://dash.cloudflare.com/oauth2/revoke",
+} as const;
+
+/** How long a token-endpoint call may take before it is a timeout rather than a wait. */
+const OAUTH_TIMEOUT_MS = 30_000;
+
+/** 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 function pkcePair(): 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. */
+export function oauthState(): string {
+  return randomBytes(16).toString("base64url");
+}
+
+/** 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 function authorizeUrl(request: AuthorizeRequest): string {
+  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. */
+export 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`.");
+export type OAuthTokenResponse = z.output<typeof OAuthTokenResponse>;
+
+/**
+ * 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(),
+});
+
+/** 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;
+}
+
+/** One form POST to an OAuth endpoint: the status, and the body parsed as JSON where it is JSON. */
+async function post(
+  operation: string,
+  url: string,
+  form: Record<string, string>,
+  options: EndpointOptions,
+): Promise<{ status: number; body: unknown }> {
+  const send = options.fetch ?? (globalThis.fetch as unknown as OAuthFetch);
+  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: unknown;
+    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: unknown): { error: string; description: string } | null {
+  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: unknown, context: string, now: Date, keepRefresh: string | null): OAuthGrant {
+  const token = decodeResponse(OAuthTokenResponse, body, context);
+  return {
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token ?? keepRefresh,
+    expiresAt: new Date(now.getTime() + token.expires_in * 1000),
+    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.
+ */
+export async function exchangeCode(
+  request: { code: string; verifier: string; redirectUri: string } & EndpointOptions,
+): Promise<OAuthGrant> {
+  const now = request.now ?? (() => 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);
+}
+
+/** 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 async function refreshGrant(request: { refreshToken: string } & EndpointOptions): Promise<RefreshResult> {
+  const now = request.now ?? (() => 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) {
+    const refusal = refusalOf(answer.body) ?? { error: `http_${answer.status}`, description: `HTTP ${answer.status}` };
+    return { kind: "refused", ...refusal };
+  }
+  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.
+ */
+export async function revokeToken(
+  request: { token: string; hint: "access_token" | "refresh_token" } & EndpointOptions,
+): Promise<void> {
+  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"}`,
+    });
+  }
+}

package/src/oauth/scopes.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { oauthScopesFor } from "../tokens/permissions";
+
+/**
+ * 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 const SESSION_BASE_SCOPES = [
+  "user-details.read",
+  "offline_access",
+  "account-api-tokens.write",
+  "account-settings.read",
+  "zone.read",
+] as const;
+
+/**
+ * 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 const SENSITIVE_SCOPES: Readonly<Record<string, string>> = {
+  "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.
+ */
+export function sessionScopes(permissionKeys: readonly string[]): string[] {
+  const scopes: string[] = [...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.
+ */
+export function missingScopes(requested: readonly string[], granted: string): string[] {
+  const held = new Set(granted.split(/\s+/).filter(Boolean));
+  return requested.filter((scope) => !held.has(scope));
+}
+
+/** 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 function sensitiveScopesIn(scopes: readonly string[]): SensitiveScope[] {
+  return scopes.flatMap((id) => {
+    const name = SENSITIVE_SCOPES[id];
+    return name === undefined ? [] : [{ id, name }];
+  });
+}

package/src/secrets/secretsStoreManager.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { remedy } from "@pithy-sh/core/src/cli/command";
 import { JsonDate } from "@pithy-sh/core/src/data/codecs";
 import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
 import { z } from "zod";
@@ -207,7 +208,7 @@ export class CloudflareSecretsStoreManager extends CloudflareManager {
     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`,
       });
     }

package/src/test-utils/settle.ts

@@ -0,0 +1,139 @@
+// 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 const SETTLE_TIMEOUT_MS = 120_000;
+
+/**
+ * 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 const METADATA_INDEX_SETTLE_MS = 300_000;
+
+/**
+ * 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 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 const POLL_INTERVAL_MS = 2_000;
+
+/** 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;
+}
+
+/** When a wait gives up, and the clause its timeout message ends the step name with. */
+function limitOf(options: SettleOptions, started: number): { deadline: number; why: string } {
+  const own = started + (options.timeoutMs ?? SETTLE_TIMEOUT_MS);
+  if (options.deadline !== undefined && options.deadline < own) {
+    return { deadline: options.deadline, why: " (the shared deadline for this test ran out)" };
+  }
+  return { deadline: own, why: "" };
+}
+
+function seconds(ms: number): number {
+  return Math.round(ms / 1000);
+}
+
+function pause(ms: number): Promise<void> {
+  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.
+ */
+export async function waitFor(what: string, ready: () => Promise<boolean>, options: SettleOptions = {}): Promise<void> {
+  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 ?? POLL_INTERVAL_MS);
+  }
+}
+
+/**
+ * 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 async function waitForStable<T>(
+  what: string,
+  read: () => Promise<T>,
+  settled: (value: T) => boolean,
+  options: SettleOptions = {},
+): Promise<T> {
+  const started = Date.now();
+  const needed = options.stableReads ?? STABLE_READS;
+  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 ?? POLL_INTERVAL_MS);
+    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.
+ */
+export function metadataIndexesSettled(
+  declared: readonly { propertyName: string; indexType: string }[],
+): (live: readonly { propertyName: string; indexType: string }[]) => boolean {
+  return (live) => {
+    const types = new Map(live.map((entry) => [entry.propertyName, entry.indexType]));
+    return declared.every((entry) => types.get(entry.propertyName) === entry.indexType);
+  };
+}

package/src/tokens/permissions.ts

@@ -46,12 +46,66 @@ export const PERMISSION_GROUPS = {
   //
   // Still not a group that can alter a zone. "Workers Routes Write" writes routes on a zone; changing
   // the zone itself would be "Zone Write", which this catalog does not have and will not get.
+  //
+  // Only this group is zone-limited. "Workers Scripts Write" is account-scoped and attaches a custom
+  // domain — a proxied DNS record and a certificate — on any zone the account holds (measured, #709;
+  // docs/TOKENS.md). So a token carrying the base can reach every zone's hostnames whatever this scopes.
   "routes:write": ["Workers Routes Write"],
 } as const;
 
 /** 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 const OAUTH_SCOPES = {
+  "d1:read": ["d1.read"],
+  "d1:write": ["d1.write"],
+  "workers:write": ["workers-scripts.write"],
+  "secrets:read": ["secrets-store.read"],
+  "secrets:write": ["secrets-store.write"],
+  "email:routing": ["email-routing-rule.write"],
+  "kv:write": ["workers-kv-storage.write"],
+  "r2:read": ["workers-r2.read"],
+  "r2:write": ["workers-r2.write"],
+  "vectorize:read": ["vectorize.read"],
+  "vectorize:write": ["vectorize.write"],
+  "ai:read": ["ai.read"],
+  "zone:read": ["zone.read"],
+  "routes:write": ["workers-routes.write"],
+} as const satisfies Record<PermissionKey, readonly string[]>;
+
+/**
+ * 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 function oauthScopesFor(keys: readonly string[]): string[] {
+  resolvePermissionKeys([...keys]);
+  const scopes: string[] = [];
+  for (const key of keys) {
+    for (const scope of OAUTH_SCOPES[key as PermissionKey]) {
+      if (!scopes.includes(scope)) scopes.push(scope);
+    }
+  }
+  return scopes;
+}
+
 /**
  * The keys whose Cloudflare permission group is **zone-scoped**: a policy carrying one must name zone
  * resources (`com.cloudflare.api.account.zone.<id>`), never the account resource.

package/src/tokens/profiles.ts

@@ -263,6 +263,10 @@ export function permissionsForKeys(keys: PermissionKey[], accountId: string): To
  * it is a policy of its own rather than a permission on the profile because its resources are zones,
  * which a profile cannot name: they are resolved from the domains at mint time.
  *
+ * **This limits the route, not the token.** The account policy beside it carries Workers Scripts Write,
+ * which attaches a custom domain on any zone the account holds (measured, #709; `docs/TOKENS.md`). Only
+ * the route calls are held to the declared zones.
+ *
  * **Empty for an empty zone list, deliberately.** A project that declares no domain attaches no route,
  * so it mints exactly the token it minted before this existed. No new permission for a project that
  * needs none.