@pithy-sh/cloudflare 0.1.0

package/src/test-utils/reap.ts

@@ -0,0 +1,297 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Cloudflare } from "cloudflare";
+import { CloudflareClients } from "../client/clients";
+import { listEmailRoutingRules, namedRules } from "./emailRoutingRules";
+import {
+  emptyTestBucket,
+  type IntegrationCreds,
+  type ReapableKind,
+  staleTestResourceNames,
+  testResourceAge,
+} from "./harness";
+
+/**
+ * The reap registry: every throwaway resource kind a live suite can mint, in one place, swept once per
+ * integration run.
+ *
+ * ## Why this exists, and why per-suite reaping was never enough
+ *
+ * {@link ReapableKind} and `reapStaleTestResources` are generic — they know how to reap *a* kind, and
+ * nothing about which kinds exist. So a kind was reaped only where some suite happened to hand the
+ * reaper a `list`/`remove` pair, and five such call sites covered the whole repo. Secrets Store
+ * entries, Queues, and API tokens had none at all, which is why eight `pithy-int-secret-…` entries sat
+ * on a real account with nothing in the repo able to reclaim them, ever.
+ *
+ * Two failures compound, and the second is the one that makes per-suite reaping structurally wrong.
+ *
+ * **A reaper registered in a suite's `beforeAll` does not run when that suite skips.** Every live suite
+ * is a `describe.skipIf(...)`, and Vitest runs no hooks inside a skipped suite. So the reaper is gated
+ * on exactly the credential whose absence lets debris accumulate: without `R2_CREDENTIALS` the R2
+ * suite skips, and because D1 reaping lived inside `@pithy-sh/storage`'s bundle, the **D1** reaper went
+ * offline with it. A reaper must never be gated on the same condition as the suite that dirties the
+ * account.
+ *
+ * **And reaping was per-suite, not per-run.** `test:integration --filter @pithy-sh/vector` mints
+ * Vectorize indexes and reaps nothing, because the only index reaper lived in `@pithy-sh/cloudflare`.
+ * Cross-package coverage was accidental.
+ *
+ * So the sweep moved to a Vitest `globalSetup` (see `integrationSetup.ts`), which runs once per project
+ * before any suite is collected and cannot be skipped by a suite's gate. A new live suite inherits
+ * cleanup instead of remembering to arrange it.
+ *
+ * ## What is deliberately still not reaped
+ *
+ * Resources composed under {@link RESERVED_TEST_PROJECT} — `pithy provision --feature`'s ephemeral D1 and
+ * KV, which a live test provisions through the *product's* namer because the names are the thing under
+ * test. `testResourceAge` cannot read an age out of `pithy-int-test-dev-73-slug-db`, and returns null
+ * rather than guessing. That conservatism is correct and stays: failing to clean up costs pennies, and
+ * deleting a resource a running suite still owns turns a green run red for reasons nobody can see. Those
+ * suites tear down in an unconditional `afterAll`; an interrupted run leaves debris that must be removed
+ * by hand. `CONTRIBUTING.md` says so out loud rather than implying the sweep covers everything.
+ */
+
+/**
+ * What this run is allowed to sweep beyond the account itself.
+ *
+ * Every other kind is account-scoped: the credentials name the account, and the account holds the
+ * debris. An Email Routing rule is not — it lives on a **zone**, and a sweep that guessed which zone
+ * would be editing mail delivery on a domain nobody pointed it at. So the zone is passed in, from the
+ * fixture that declared it, and a run that was told nothing sweeps nothing.
+ */
+export interface ReapScope {
+  /** The zone whose `pithy-int-` routing rules may be reclaimed. Absent means the kind reports itself skipped. */
+  emailRoutingZoneId?: string;
+}
+
+/** A kind that cannot be reaped this run, and the credential it is waiting on. */
+export interface SkippedReapKind {
+  /** The human label, matching the kind it stands in for. */
+  label: string;
+  /** Why it was skipped — names the missing variable, so the report is actionable. */
+  skipped: string;
+}
+
+/** One entry in a reap plan: a kind that can be swept, or a named reason it cannot. */
+export type ReapPlanEntry = (ReapableKind & { label: string }) | SkippedReapKind;
+
+/** What one kind's sweep did. `skipped` is non-null only when the kind never ran. */
+export interface ReapKindResult {
+  /** The kind's label, as it appears in the plan. */
+  label: string;
+  /** Names successfully removed. */
+  reaped: string[];
+  /** Names that matched but could not be removed — reported, never swallowed. */
+  failed: string[];
+  /** The reason this kind did not run, or null when it did. */
+  skipped: string | null;
+}
+
+/** Whether a plan entry is a stand-in for a kind that cannot run. */
+function isSkipped(entry: ReapPlanEntry): entry is SkippedReapKind {
+  return "skipped" in entry;
+}
+
+/** Every label in a plan, in plan order — what a test asserts against so a dropped kind is visible. */
+export function reapPlanLabels(plan: readonly ReapPlanEntry[]): string[] {
+  return plan.map((entry) => entry.label);
+}
+
+/**
+ * Sweep every kind in a plan and report what went.
+ *
+ * Never throws, and never lets one kind's failure end the sweep: a reaper exists to help a suite, and a
+ * housekeeping error that fails the run is worse than the debris it was cleaning. A listing that throws
+ * yields an empty result for that kind; a removal that throws lands in `failed`, where it is visible.
+ */
+export async function reapKinds(
+  plan: readonly ReapPlanEntry[],
+  options: { now?: number; staleAfterMs?: number } = {},
+): Promise<ReapKindResult[]> {
+  const results: ReapKindResult[] = [];
+
+  for (const entry of plan) {
+    if (isSkipped(entry)) {
+      results.push({ label: entry.label, reaped: [], failed: [], skipped: entry.skipped });
+      continue;
+    }
+
+    const reaped: string[] = [];
+    const failed: string[] = [];
+    let names: string[];
+    try {
+      names = await entry.list();
+    } catch {
+      results.push({ label: entry.label, reaped, failed, skipped: null });
+      continue;
+    }
+
+    for (const name of staleTestResourceNames(names, options)) {
+      try {
+        await entry.remove(name);
+        reaped.push(name);
+      } catch {
+        failed.push(name);
+      }
+    }
+    results.push({ label: entry.label, reaped, failed, skipped: null });
+  }
+
+  return results;
+}
+
+/**
+ * Build the sweep plan for an account.
+ *
+ * Alphabetical by label, so the set is readable as a list rather than as an accident of construction
+ * order, and so a test can pin it. Every kind appears whether or not it can run — a kind that is missing
+ * a credential reports *why*, because "nothing to reap" and "unable to reap" look identical in a log and
+ * only one of them is fine.
+ *
+ * R2 is the one kind an API token cannot reclaim: Cloudflare refuses to delete a non-empty bucket, and
+ * emptying one is an S3-protocol operation. So it needs the key pair, and says so when it lacks it.
+ */
+export function testResourceReapPlan(creds: IntegrationCreds, options: ReapScope = {}): ReapPlanEntry[] {
+  const clients = new CloudflareClients({ accountId: creds.accountId, apiToken: creds.apiToken });
+  const sdk = new Cloudflare({ apiToken: creds.apiToken });
+  const workers = clients.workers();
+  const tokens = clients.accountTokens();
+  const d1 = clients.d1Provisioner();
+  const kv = clients.kvProvisioner();
+  const vectorize = clients.vectorizeProvisioner();
+  const r2 = clients.r2Provisioner();
+
+  return [
+    {
+      // Minted by `accountTokensManager.integration.test.ts`. Delete addresses a token by id, so the
+      // listing is what turns a stale name back into one.
+      label: "API token",
+      list: async () => (await tokens.listTokens()).map((token) => token.name),
+      remove: async (name) => {
+        await tokens.deleteTokensByName(name);
+      },
+    },
+    {
+      label: "D1 database",
+      list: async () => (await d1.listDatabases()).map((database) => database.name),
+      remove: async (name) => {
+        const found = (await d1.listDatabases()).find((database) => database.name === name);
+        if (found) await d1.deleteDatabase(found.uuid);
+      },
+    },
+    options.emailRoutingZoneId
+      ? {
+          // The one kind whose debris changes what happens to somebody's mail rather than costing a few
+          // cents: a rule left behind keeps delivering to a Worker script the same run already deleted.
+          // Zone-scoped, so it reaps only where a run was told which zone it was allowed to touch.
+          label: "Email Routing rule",
+          list: async () =>
+            namedRules(await listEmailRoutingRules(creds, options.emailRoutingZoneId ?? "")).map((rule) => rule.name),
+          // `removeWorkerRoute` is already name-keyed and idempotent, which is `remove`'s contract —
+          // another runner's sweep reaching the rule first must not read as a failure.
+          remove: async (name) => {
+            await clients
+              .emailRouting()
+              .removeWorkerRoute({ zoneId: options.emailRoutingZoneId ?? "", ruleName: name });
+          },
+        }
+      : {
+          label: "Email Routing rule",
+          skipped: "no EMAIL_ROUTING_ZONE_ID: the zone to sweep is unknown.",
+        },
+    {
+      label: "KV namespace",
+      list: async () => (await kv.listNamespaces()).map((namespace) => namespace.title),
+      remove: async (title) => {
+        const found = (await kv.listNamespaces()).find((namespace) => namespace.title === title);
+        if (found) await kv.deleteNamespace(found.id);
+      },
+    },
+    {
+      // Queues are created with the raw SDK in the live suite (the manager addresses an existing queue
+      // by name), so the reaper reaches for the same surface rather than inventing a provisioner.
+      label: "Queue",
+      list: async () => {
+        const names: string[] = [];
+        for await (const queue of sdk.queues.list({ account_id: creds.accountId })) {
+          if (queue.queue_name) names.push(queue.queue_name);
+        }
+        return names;
+      },
+      remove: async (name) => {
+        for await (const queue of sdk.queues.list({ account_id: creds.accountId })) {
+          if (queue.queue_name === name && queue.queue_id) {
+            await sdk.queues.delete(queue.queue_id, { account_id: creds.accountId });
+            return;
+          }
+        }
+      },
+    },
+    creds.r2
+      ? {
+          label: "R2 bucket",
+          list: async () => (await r2.listBuckets()).map((bucket) => bucket.name),
+          remove: async (name) => {
+            await emptyTestBucket(creds, name);
+            await r2.deleteBucket(name);
+          },
+        }
+      : {
+          label: "R2 bucket",
+          skipped: "no R2_CREDENTIALS: a bucket cannot be emptied, and R2 refuses to delete a non-empty one.",
+        },
+    creds.secretsStoreId
+      ? {
+          label: "Secrets Store entry",
+          list: async () => (await clients.secrets(creds.secretsStoreId).listSecrets()).map((entry) => entry.name),
+          // `deleteSecretIfPresent`, not `deleteSecret`: `ReapableKind.remove` is contractually
+          // idempotent, and another runner's sweep reaching the entry first must not read as a failure.
+          remove: async (name) => {
+            await clients.secrets(creds.secretsStoreId).deleteSecretIfPresent(name);
+          },
+        }
+      : {
+          label: "Secrets Store entry",
+          skipped: "no SECRETS_STORE_ID: the store to sweep is unknown.",
+        },
+    {
+      label: "Vectorize index",
+      list: async () => (await vectorize.listIndexes()).map((index) => index.name),
+      remove: (name) => vectorize.deleteIndex(name),
+    },
+    {
+      label: "Worker script",
+      list: async () => (await workers.listWorkers()).map((script) => script.id ?? "").filter(Boolean),
+      remove: (name) => workers.deleteWorker(name),
+    },
+  ];
+}
+
+/**
+ * Reclaim every stale throwaway resource on the account, across every kind.
+ *
+ * The entry point a `globalSetup` calls. Reports one line per kind that did something or could not run;
+ * a kind with nothing to do stays quiet, because a clean account should produce a clean log.
+ */
+export async function reapAllStaleTestResources(
+  creds: IntegrationCreds,
+  options: ReapScope & { now?: number; staleAfterMs?: number } = {},
+): Promise<ReapKindResult[]> {
+  const results = await reapKinds(testResourceReapPlan(creds, options), options);
+
+  for (const result of results) {
+    if (result.skipped) console.warn(`stale ${result.label}(s) were not swept: ${result.skipped}`);
+    if (result.reaped.length > 0) {
+      console.warn(`reaped ${result.reaped.length} stale ${result.label}(s): ${result.reaped.join(", ")}`);
+    }
+    if (result.failed.length > 0) {
+      console.warn(`could not reap ${result.failed.length} stale ${result.label}(s): ${result.failed.join(", ")}`);
+    }
+  }
+
+  return results;
+}
+
+/** Re-exported so a caller reasoning about one name does not need two imports. */
+export { testResourceAge };

package/src/tokens/accountTokensManager.ts

@@ -0,0 +1,334 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import {
+  CloudflareNotConfiguredError,
+  CloudflareRequestError,
+  cloudflareRequest,
+  decodeResponse,
+  isAuthorizationError,
+  messageOf,
+} from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+import { CfTokenVerification } from "../user/userManager";
+
+/**
+ * One access policy to attach to a minted token: a set of permission groups (named, resolved to ids
+ * at mint time) and the resources they apply to. This is the reusable unit — every use case that
+ * needs a scoped CF token (the secrets manager is the first) describes itself as a list of these,
+ * and the manager turns names into the CF policy shape. `effect` defaults to `allow`.
+ */
+export interface TokenPermission {
+  /** Permission-group names to grant, resolved to ids against the live account list (e.g. "Secrets Store Read"). */
+  permissionGroupNames: string[];
+  /** The resource scope the groups apply to (e.g. `{ "com.cloudflare.api.account.<id>": "*" }`). */
+  resources: Record<string, string>;
+  /** Allow or deny the groups against the resources. Defaults to `allow`. */
+  effect?: "allow" | "deny";
+}
+
+/**
+ * The whole-account resource scope for a token policy: `{ "com.cloudflare.api.account.<id>": "*" }`.
+ * Account-level permission groups (Secrets Store, D1, Workers, …) scope to this. One helper so the
+ * exact resource key format lives in a single place instead of being hand-spelled per use case.
+ */
+export function accountResource(accountId: string): Record<string, string> {
+  return { [`com.cloudflare.api.account.${accountId}`]: "*" };
+}
+
+/**
+ * A permission group available to account-owned tokens, as returned by the permission-groups list.
+ * Only the id and name matter for resolution — the manager maps a requested name to its id.
+ */
+export const CfPermissionGroup = z
+  .object({
+    id: z.string().describe("The CF-assigned permission-group id, referenced in a token policy."),
+    name: z.string().describe("The human-readable permission-group name (e.g. 'Secrets Store Read')."),
+  })
+  .describe("A Cloudflare account-token permission group: the id a policy references and its display name.");
+export type CfPermissionGroup = z.output<typeof CfPermissionGroup>;
+
+/**
+ * A freshly minted account-owned token. The `value` is the secret bearer credential — present **only**
+ * in the create response, never re-readable — so it is captured here and must be stored at once
+ * (e.g. into the Secrets Store). Never log it.
+ */
+export const MintedAccountToken = z
+  .object({
+    id: z.string().describe("The CF-assigned token id, used to address the token for get/delete."),
+    value: z.string().describe("The secret token value — returned once on create, never again. Store immediately."),
+    name: z.string().optional().describe("The token name as registered with Cloudflare."),
+    status: z.enum(["active", "disabled", "expired"]).optional().describe("The token's lifecycle status."),
+  })
+  .describe("A newly created account-owned API token, including its one-time secret value.");
+export type MintedAccountToken = z.output<typeof MintedAccountToken>;
+
+/**
+ * An existing account-owned token's metadata, as returned by list/get. No `value` — Cloudflare never
+ * returns a token's secret after creation — so this is only enough to find a token by name and
+ * address it for deletion.
+ */
+export const AccountTokenSummary = z
+  .object({
+    id: z.string().describe("The CF-assigned token id, used to address the token for deletion."),
+    name: z.string().describe("The token name, the key callers match on for idempotent re-mint."),
+    status: z.enum(["active", "disabled", "expired"]).optional().describe("The token's lifecycle status."),
+  })
+  .describe("An existing account-owned API token's metadata (never its secret value).");
+export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
+
+/**
+ * Out-of-Worker control plane for **account-owned** Cloudflare API tokens: mint scoped, least-privilege
+ * tokens, find them by name, and delete them. Account-owned (not user-bound) by design — CLAUDE.md
+ * prefers org-level tokens that outlive any one person.
+ *
+ * This is the reusable seam behind every "pithy mints its own scoped token" case. A caller hands it a
+ * token name and a set of {@link TokenPermission}s (permission-group names + resource scope); the
+ * manager resolves the names to ids against the live account list and creates the token. The secrets
+ * manager's runtime credential is the first concrete use; more follow without touching this class.
+ */
+export class CloudflareAccountTokensManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Account API Tokens";
+  }
+
+  /** Prove access by listing permission groups — a read, never a token create/delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.listPermissionGroups();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Verify the **calling** token against this account — `GET /accounts/{id}/tokens/verify`.
+   *
+   * Distinct from {@link CloudflareUserManager.verifyToken}, which hits the *user*-scoped
+   * `/user/tokens/verify` and returns `Invalid API Token` for an account-owned (`cfat_*`) credential.
+   * Since `CLAUDE.md` prefers account-owned tokens over user-bound ones, the user endpoint is the wrong
+   * one for the common case, and using it reports a working token as invalid.
+   */
+  async verifyToken(): Promise<CfTokenVerification> {
+    const raw = await cloudflareRequest("verify account token", () =>
+      this.getClient().accounts.tokens.verify({ account_id: this.accountId }),
+    );
+    return decodeResponse(CfTokenVerification, raw, "account token verify");
+  }
+
+  /**
+   * The name of an account-owned token by id, or `null` — `GET /accounts/{id}/tokens/{token_id}`.
+   *
+   * Distinct from {@link CloudflareUserManager.getTokenName}, which hits `GET /user/tokens/:id` and
+   * answers `9109 — Valid user-level authentication not found` for a `cfat_*` caller. Both halves of
+   * the account-token identity read — verify and name — are account-scoped, or neither is.
+   *
+   * **Best effort, by contract.** Reading a token record needs `API Tokens Read`, which the
+   * least-privilege tokens {@link mintToken} produces deliberately do not carry: a 403 is the normal
+   * answer for a CI credential asking its own name, not a fault. So a denied read returns `null` and
+   * the caller falls back to the token id from {@link verifyToken} — which any account token can call
+   * with no permission at all. Every other failure still throws.
+   */
+  async getTokenName(tokenId: string): Promise<string | null> {
+    const raw = await cloudflareRequest(`get account token ${tokenId}`, async () => {
+      try {
+        return await this.getClient().accounts.tokens.get(tokenId, { account_id: this.accountId });
+      } catch (error) {
+        if (isAuthorizationError(error)) return null;
+        throw error;
+      }
+    });
+    const parsed = TokenName.safeParse(raw);
+    return parsed.success ? parsed.data.name : null;
+  }
+
+  /** Every permission group available to account-owned tokens in this account (SDK auto-paginates). */
+  async listPermissionGroups(): Promise<CfPermissionGroup[]> {
+    return cloudflareRequest("list account token permission groups", async () => {
+      const out: CfPermissionGroup[] = [];
+      for await (const group of this.getClient().accounts.tokens.permissionGroups.list({
+        account_id: this.accountId,
+      })) {
+        const parsed = CfPermissionGroup.safeParse(group);
+        if (parsed.success) out.push(parsed.data);
+      }
+      return out;
+    });
+  }
+
+  /**
+   * Resolve permission-group names to their `{ id }` references against the account's live group list.
+   * Throws a clear, actionable error naming any name that does not exist, or any name that is
+   * **ambiguous** — Cloudflare reuses display names across resource scopes (e.g. account vs zone), so a
+   * name that maps to more than one id can't be resolved without picking the wrong scope. Either way a
+   * typo'd or ambiguous group fails loudly at mint time, never silently widening or narrowing scope.
+   */
+  async resolvePermissionGroups(names: string[]): Promise<Array<{ id: string }>> {
+    return this.resolveAgainstIndex(indexByName(await this.listPermissionGroups()), names);
+  }
+
+  /**
+   * Mint a new account-owned token named `name` carrying `permissions`. Resolves every permission
+   * group name to its id (one group-list fetch for all policies), builds the CF policy set, and
+   * creates the token. Returns the token's one-time secret `value` — store it immediately. A 403 (the
+   * calling token cannot create tokens) is reraised as an actionable "grant 'Account API Tokens
+   * Write'" error so the cause is obvious; this doubles as the fail-fast preflight when provisioning
+   * runs the mint first.
+   */
+  async mintToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken> {
+    const index = indexByName(await this.listPermissionGroups());
+    const policies = permissions.map((permission) => ({
+      effect: permission.effect ?? ("allow" as const),
+      permission_groups: this.resolveAgainstIndex(index, permission.permissionGroupNames),
+      resources: permission.resources,
+    }));
+    let raw: unknown;
+    try {
+      raw = await this.getClient().accounts.tokens.create({ account_id: this.accountId, name, policies });
+    } catch (error) {
+      if (isAuthorizationError(error)) {
+        throw new CloudflareNotConfiguredError(
+          {
+            message: "The Cloudflare API token is not allowed to create account tokens.",
+            action: "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.",
+            detail: `mint account token '${name}': ${messageOf(error)}`,
+          },
+          { cause: error },
+        );
+      }
+      throw new CloudflareRequestError(
+        { message: `Failed to mint account token '${name}'.`, detail: messageOf(error) },
+        { cause: error },
+      );
+    }
+    return decodeResponse(MintedAccountToken, raw, "account token create");
+  }
+
+  /**
+   * Resolve names against a prefetched name→ids index, throwing on any unknown or ambiguous name.
+   * The shared core of {@link resolvePermissionGroups} and {@link mintToken}: take the group list once,
+   * resolve every name against it. Ambiguity (a name with more than one id) is a hard error, not a
+   * silent pick — see {@link resolvePermissionGroups}.
+   */
+  private resolveAgainstIndex(index: Map<string, string[]>, names: string[]): Array<{ id: string }> {
+    const unknown = names.filter((name) => !index.has(name));
+    if (unknown.length > 0) {
+      throw new CloudflareNotConfiguredError({
+        message: `Unknown Cloudflare permission group(s): ${unknown.join(", ")}.`,
+        action: "Check the exact permission-group names against the account's available groups.",
+        detail: `resolve permission groups: not found in account ${this.accountId} — ${unknown.join(", ")}`,
+      });
+    }
+    const ambiguous = names.filter((name) => (index.get(name)?.length ?? 0) > 1);
+    if (ambiguous.length > 0) {
+      throw new CloudflareNotConfiguredError({
+        message: `Ambiguous Cloudflare permission group(s): ${ambiguous.join(", ")}.`,
+        action: "These names map to more than one permission group; scope the token by a unique group name.",
+        detail: `resolve permission groups: name maps to multiple ids in account ${this.accountId} — ${ambiguous.join(", ")}`,
+      });
+    }
+    // biome-ignore lint/style/noNonNullAssertion: each name is present and unambiguous — the guards above proved it.
+    return names.map((name) => ({ id: index.get(name)![0]! }));
+  }
+
+  /** Every account-owned token's metadata (SDK auto-paginates). No secret values — list is metadata only. */
+  async listTokens(): Promise<AccountTokenSummary[]> {
+    return cloudflareRequest("list account tokens", async () => {
+      const out: AccountTokenSummary[] = [];
+      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+        const parsed = AccountTokenSummary.safeParse(token);
+        if (parsed.success) out.push(parsed.data);
+      }
+      return out;
+    });
+  }
+
+  /** Find an account token by exact name, or `null` — for idempotent re-mint (SDK auto-paginates). */
+  async findTokenByName(name: string): Promise<AccountTokenSummary | null> {
+    return cloudflareRequest(`find account token ${name}`, async () => {
+      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+        const parsed = AccountTokenSummary.safeParse(token);
+        if (parsed.success && parsed.data.name === name) return parsed.data;
+      }
+      return null;
+    });
+  }
+
+  /** Delete an account token by id. */
+  async deleteToken(tokenId: string): Promise<void> {
+    await cloudflareRequest(`delete account token ${tokenId}`, () =>
+      this.getClient().accounts.tokens.delete(tokenId, { account_id: this.accountId }),
+    );
+  }
+
+  /**
+   * Delete every account token with the given name; returns how many were removed. Names are not
+   * unique in Cloudflare, so any duplicates (e.g. a prior interrupted run) are swept here. A no-op
+   * when none match. Used by teardown.
+   */
+  async deleteTokensByName(name: string): Promise<number> {
+    return cloudflareRequest(`delete account tokens named ${name}`, async () => {
+      const ids: string[] = [];
+      for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+        const parsed = AccountTokenSummary.safeParse(token);
+        if (parsed.success && parsed.data.name === name) ids.push(parsed.data.id);
+      }
+      for (const id of ids) {
+        await this.getClient().accounts.tokens.delete(id, { account_id: this.accountId });
+      }
+      return ids.length;
+    });
+  }
+
+  /**
+   * Roll an existing token's secret: regenerate its value **in place**, keeping the same token id,
+   * name, and policies (the dashboard's "Roll" action). Returns the new secret value — the only time
+   * Cloudflare hands it back — so it must be stored at once. The seam the deferred value-rotation
+   * builds on: a credential self-rolls without ever changing identity.
+   */
+  async rollTokenValue(tokenId: string): Promise<string> {
+    const raw = await cloudflareRequest(`roll account token value ${tokenId}`, () =>
+      this.getClient().accounts.tokens.value.update(tokenId, { account_id: this.accountId, body: {} }),
+    );
+    return decodeResponse(RolledTokenValue, raw, "account token value roll");
+  }
+
+  /**
+   * Ensure a named token exists and return a **fresh** secret for it. If a token of this name already
+   * exists, roll its value in place (same id and policies, new secret); otherwise mint a new one.
+   * Either way the caller gets a usable secret to store — the idempotent path for a credential that
+   * lives in the Secrets Store, since Cloudflare never returns a token's existing secret. Mirrors the
+   * dashboard's roll-or-create.
+   */
+  async rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken> {
+    const existing = await this.findTokenByName(name);
+    if (!existing) return this.mintToken(name, permissions);
+    const value = await this.rollTokenValue(existing.id);
+    return { id: existing.id, value, name: existing.name, status: existing.status };
+  }
+}
+
+/** The rolled secret value Cloudflare returns from a value-roll — a non-empty bearer string. */
+const RolledTokenValue = z.string().min(1);
+
+/** Just the token's name, the piece the account-token actor path needs. */
+const TokenName = z
+  .object({ name: z.string().describe("The token's registered name — the audit actor id for an account token.") })
+  .describe("The one field a token-record read is narrowed to: its name.");
+
+/**
+ * Index permission groups by display name, collecting **every** id that bears a name. A list rather
+ * than one id per name on purpose: Cloudflare reuses display names across scopes, and a name with
+ * more than one id is ambiguous — the resolver rejects it rather than silently pick one.
+ */
+function indexByName(groups: CfPermissionGroup[]): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const group of groups) {
+    const ids = index.get(group.name) ?? [];
+    ids.push(group.id);
+    index.set(group.name, ids);
+  }
+  return index;
+}