@pithy-sh/cloudflare 0.4.2 → 0.6.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 `runtime` as the project
+ *   composes them, 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/queue/queueProvisioner.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** A queue's identity, decoded from the Queues API's `queue_id` and `queue_name`. */
+export const QueueInfo = z
+  .object({
+    id: z.string().describe("The CF-assigned queue id, which the REST API addresses a queue by."),
+    name: z.string().describe("The queue name a producer binding names it by."),
+  })
+  .describe("A Cloudflare Queue's identity, as the Queues API returns it.");
+export type QueueInfo = z.output<typeof QueueInfo>;
+
+/** The Queues API's own spelling of a queue's identity, mapped onto {@link QueueInfo}. */
+const QueueRecord = z
+  .object({
+    queue_id: z.string().describe("The CF-assigned queue id."),
+    queue_name: z.string().describe("The queue name."),
+  })
+  .transform(({ queue_id, queue_name }) => ({ id: queue_id, name: queue_name }))
+  .describe("A queue as the Queues API returns it.");
+
+/**
+ * Account-level Queues control plane: **find, create and delete queues** (#662).
+ *
+ * `pithy provision` creates the queue behind every `queue` binding a composition declares, and `pithy feature
+ * destroy` deletes a feature's. A `queues.producers` entry names a queue, and `wrangler deploy` refuses one that
+ * does not exist, so the entry is only honest because this stands the queue up. Addressed by account — unlike
+ * {@link CloudflareQueueManager}, which targets one queue to send into.
+ */
+export class CloudflareQueueProvisioner extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Queues (control plane)";
+  }
+
+  /** Prove access by listing queues — a read, never a create or a delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().queues.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Find a queue by exact name in the account, or `null` — for idempotent provisioning. */
+  async findQueueByName(name: string): Promise<QueueInfo | null> {
+    return cloudflareRequest(`find queue ${name}`, async () => {
+      for await (const queue of this.getClient().queues.list({ account_id: this.accountId })) {
+        const parsed = QueueRecord.safeParse(queue);
+        if (parsed.success && parsed.data.name === name) return parsed.data;
+      }
+      return null;
+    });
+  }
+
+  /** Create a queue by name; returns its id and name. */
+  async createQueue(name: string): Promise<QueueInfo> {
+    const response = await cloudflareRequest(`create queue ${name}`, () =>
+      this.getClient().queues.create({ account_id: this.accountId, queue_name: name }),
+    );
+    return decodeResponse(QueueRecord, response, "queue create");
+  }
+
+  /** Delete a queue by id. Idempotent — a missing queue is not an error, so teardown can re-run safely. */
+  async deleteQueue(queueId: string): Promise<void> {
+    await cloudflareRequest(`delete queue ${queueId}`, async () => {
+      try {
+        await this.getClient().queues.delete(queueId, { account_id: this.accountId });
+      } catch (error) {
+        if (isNotFoundError(error)) return;
+        throw error;
+      }
+    });
+  }
+}

package/src/r2/r2Manager.ts

@@ -33,11 +33,29 @@ const LIST_PARTS_PAGE_SIZE = 1000;
  * the bucket it targets. R2 signs presigned URLs with the S3 keys, not the CF API token — both
  * come from config (no environment coupling).
  */
-export interface R2ManagerConfig extends CloudflareManagerConfig, R2Credentials {
+export interface R2ManagerConfig extends Omit<CloudflareManagerConfig, "apiToken">, R2Credentials {
   /** The R2 bucket all object operations target. */
   bucketName: string;
+  /**
+   * A Cloudflare API token, for the one call here that is not S3: {@link CloudflareR2Manager.validateServiceAccess}.
+   *
+   * **Absent in a Worker (#728).** Every object operation is S3, signed with the key pair, so a Worker's
+   * object store holds no API token: the application's one is `runtime`, and R2 needs none of it. Without
+   * one, `validateServiceAccess` answers `false` and nothing calls the Cloudflare API. An empty string is
+   * still refused, because that is an unresolved value rather than a decision.
+   */
+  apiToken?: string;
 }
 
+/**
+ * What the base client is built with when the config carries no API token. Never sent: {@link noApiToken}
+ * is the provider, and the base reads the token through it at every call and refuses an empty one.
+ */
+const S3_ONLY = "r2-s3-only";
+
+/** The token provider of an S3-only manager: no token, so any Cloudflare API call is refused before it is sent. */
+const noApiToken = (): string => "";
+
 /** How long a presigned URL stays valid. Shared by every presign method so the option reads the same. */
 export interface PresignOptions {
   /** Lifetime in seconds. Defaults to one hour — long enough for a large upload, short enough to leak little. */
@@ -168,8 +186,15 @@ export class CloudflareR2Manager extends CloudflareManager {
 
   private s3Client: S3Client | null = null;
 
+  private readonly s3Only: boolean;
+
   constructor(config: R2ManagerConfig) {
-    super(config);
+    super(
+      config.apiToken === undefined
+        ? { ...config, apiToken: S3_ONLY, tokenProvider: noApiToken }
+        : { ...config, apiToken: config.apiToken },
+    );
+    this.s3Only = config.apiToken === undefined;
     if (!config.bucketName) {
       throw new CloudflareNotConfiguredError({ detail: "Missing bucketName for R2 access." });
     }
@@ -538,6 +563,8 @@ export class CloudflareR2Manager extends CloudflareManager {
    * not merely that an S3 client could be built. Never throws.
    */
   async validateServiceAccess(): Promise<boolean> {
+    // An S3-only manager holds no API token to read the bucket record with.
+    if (this.s3Only) return false;
     try {
       await this.getClient().r2.buckets.get(this.bucketName, { account_id: this.accountId });
       return true;

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/accountTokensManager.ts

@@ -185,6 +185,18 @@ export const AccountTokenSummary = z
       .describe(
         "The token's access policies, when the list response carries them. **A live token's own scope is the record of how it was minted** — it is how a `ci-system` token minted before zone-scoped routes (#651) can be told from one minted after, without reading the token record (which needs a grant these least-privilege tokens deliberately lack). Absent and empty are different facts: a response that says nothing means the scope could not be read, never that the token has none.",
       ),
+    // **Not `nullAsAbsent`, and that is the field.** Everywhere else a `null` means the response did not say;
+    // here it is Cloudflare's answer — nothing has ever authenticated with this token. Absent stays "did
+    // not say", and a shape this does not model degrades to absent rather than dropping the token, for the
+    // reason `policies` gives.
+    last_used_on: z
+      .string()
+      .nullable()
+      .optional()
+      .catch(undefined)
+      .describe(
+        "When something last authenticated with the token, as Cloudflare measures it against the live account. Read because `pithy token forget` acts on it (#762): `null` means never, so a local copy may be its only one. Absent means the response did not say, which is not a claim either way.",
+      ),
   })
   .describe("An existing account-owned API token's metadata (never its secret value).");
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;