@pithy-sh/cloudflare 0.1.1 → 0.1.3

package/dist/test-utils/inboundRecorder.js

@@ -0,0 +1,141 @@
+import { CloudflareInvalidResponseError, CloudflareRequestError } from "../client/errors.js";
+import { z } from "zod";
+//#region src/test-utils/inboundRecorder.ts
+/**
+* A throwaway Worker that records what its `email()` handler was handed, and the reader that fetches
+* the record back out.
+*
+* ## Why a Worker has to exist at all
+*
+* An Email Routing rule cannot point at a Worker that is not there. Cloudflare rejects the rule with
+* `2016 Workers Script Info not found` at creation time, so a live test of `ensureWorkerRoute` has to
+* deploy a real script before it can create a real rule. That fact alone forces this file; everything
+* else here is what the script may as well do once it is running.
+*
+* ## Why the record goes through KV
+*
+* There is no inbox. The fixture zone's catch-all drops and it has zero verified destination
+* addresses, so nothing this suite sends can be read from a mailbox — and a test that waits for one
+* waits forever. The Worker is the destination, so the Worker has to be the witness: it writes what it
+* received to a KV namespace the test created, and the test reads it back over the REST API.
+*
+* ## What it deliberately does not do
+*
+* It does not classify, suppress, or parse MIME. Everything `@pithy-sh/email` actually does with an
+* inbound message is unit-tested against real D1 in the Workers pool, where a hostile message can be
+* constructed exactly rather than mailed and hoped for. What only a live delivery can answer is what
+* Cloudflare *hands* the handler — which headers survive, which Cloudflare adds, and whether a
+* sender's own headers arrive intact. So the recorder records, and asserts nothing.
+*/
+/** The KV binding the recorder writes through. */
+const INBOUND_RECORDER_BINDING = "OBSERVED";
+/** The header a sender stamps to address its record. One send, one key, so parallel runs cannot collide. */
+const INBOUND_NONCE_HEADER = "X-Pithy-Probe";
+/**
+* The recorder's source, as a module string.
+*
+* Kept verbatim here rather than built from a template because it is uploaded as-is and read by whoever
+* is debugging a delivery that did not arrive. It writes **once**, under the nonce it finds in the raw
+* message, and it must never throw: a throw inside `email()` is a delivery failure Cloudflare retries,
+* which turns one test message into several.
+*/
+const INBOUND_RECORDER_MODULE = `
+const NONCE = /^${INBOUND_NONCE_HEADER}:[ \\t]*(\\S+)[ \\t]*$/im;
+const AUTH_RESULTS = /^Authentication-Results:[ \\t]*([\\s\\S]*?)(?=\\r?\\n[^ \\t])/gim;
+
+/** Header names in the raw block, in order, lowercased. Duplicates kept — two DKIM signatures are two facts. */
+function rawHeaderNames(raw) {
+  const block = raw.split(/\\r?\\n\\r?\\n/)[0] ?? "";
+  return block
+    .split(/\\r?\\n/)
+    .filter((line) => /^[A-Za-z0-9-]+:/.test(line))
+    .map((line) => line.slice(0, line.indexOf(":")).toLowerCase());
+}
+
+export default {
+  async email(message, env) {
+    let record;
+    let nonce = "unkeyed";
+    try {
+      const raw = await new Response(message.raw).text();
+      nonce = NONCE.exec(raw)?.[1] ?? "unkeyed";
+      record = {
+        envelopeFrom: message.from,
+        envelopeTo: message.to,
+        rawSize: message.rawSize,
+        seen: [...message.headers.keys()].map((name) => name.toLowerCase()).sort(),
+        rawHeaderNames: rawHeaderNames(raw),
+        authenticationResults: [...raw.matchAll(AUTH_RESULTS)].map((match) => match[1].trim()),
+        raw: raw.slice(0, 16384),
+      };
+    } catch (error) {
+      record = { failure: String(error) };
+    }
+    await env.${INBOUND_RECORDER_BINDING}.put(nonce, JSON.stringify(record), { expirationTtl: 3600 });
+  },
+};
+`;
+/**
+* What the recorder saw — validated on the way back in, because a KV read is a boundary like any other.
+*
+* The Worker that wrote it is ours, which is exactly the argument that has let every unvalidated
+* internal read through. A truncated write or a stale record from an older recorder deserves a Zod
+* failure naming the field, not a `TypeError` three assertions later.
+*/
+const ObservedInbound = z.object({
+	envelopeFrom: z.string().describe("The SMTP envelope sender, as `message.from` reported it."),
+	envelopeTo: z.string().describe("The SMTP envelope recipient, as `message.to` reported it."),
+	rawSize: z.number().describe("The message size in bytes, as `message.rawSize` reported it."),
+	seen: z.array(z.string()).describe("Header names on `message.headers`, lowercased and sorted — the surface workerd#6740 is about."),
+	rawHeaderNames: z.array(z.string()).describe("Header names in the raw MIME block, lowercased, in wire order, duplicates kept."),
+	authenticationResults: z.array(z.string()).describe("Every `Authentication-Results` value in the raw block, in wire order: the topmost is the receiver's."),
+	raw: z.string().describe("The delivered message, truncated to the first 16 KiB.")
+}).describe("One inbound message as the Worker's `email()` handler received it.");
+/** A trivial module Worker: enough for an Email Routing rule to be allowed to point at it. */
+const PLACEHOLDER_INBOUND_MODULE = "export default { async email() {} };\n";
+/** The module filename every throwaway Worker here is uploaded under. */
+const INBOUND_MODULE_NAME = "worker.mjs";
+/**
+* Deploy the recorder at `scriptName`, bound to the KV namespace records are written to.
+*
+* Uploaded through `CloudflareWorkersManager.createWorker` like anything else. It briefly was not:
+* #373 was a manager that could not upload a module to the live API at all, and this file carried a
+* hand-rolled `fetch` around it. The manager is the path again — a helper that exists because the
+* product is broken is the thing people copy.
+*/
+async function deployInboundRecorder(options) {
+	const { workers, scriptName, namespaceId, compatibilityDate } = options;
+	await workers.createWorker(scriptName, compatibilityDate, { bindings: [{
+		type: "kv_namespace",
+		name: INBOUND_RECORDER_BINDING,
+		namespace_id: namespaceId
+	}] }, {
+		name: INBOUND_MODULE_NAME,
+		body: INBOUND_RECORDER_MODULE
+	});
+}
+/**
+* The record for one nonce, or null while nothing has arrived.
+*
+* Null rather than a throw for the missing case, because "not yet" is the normal state of a mail
+* delivery: the caller polls. A 404 from KV is that state; anything else is a real failure and throws.
+*/
+async function readObservedInbound(options) {
+	const { creds, namespaceId, nonce } = options;
+	const url = `https://api.cloudflare.com/client/v4/accounts/${creds.accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(nonce)}`;
+	const response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
+	if (response.status === 404) return null;
+	if (!response.ok) throw new CloudflareRequestError({
+		message: "Could not read the recorded inbound message.",
+		action: "Check the token carries Workers KV Storage: Edit on this account.",
+		detail: `KV read for the inbound record returned ${response.status}.`
+	});
+	const body = JSON.parse(await response.text());
+	if (typeof body === "object" && body !== null && "failure" in body) throw new CloudflareInvalidResponseError({
+		message: "The inbound recorder could not read the message it was handed.",
+		detail: `The recorder Worker recorded a failure: ${String(body.failure)}`
+	});
+	return ObservedInbound.parse(body);
+}
+//#endregion
+export { INBOUND_MODULE_NAME, INBOUND_NONCE_HEADER, INBOUND_RECORDER_BINDING, INBOUND_RECORDER_MODULE, ObservedInbound, PLACEHOLDER_INBOUND_MODULE, deployInboundRecorder, readObservedInbound };

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

@@ -0,0 +1,22 @@
+/**
+ * The Vitest `globalSetup` every `vitest.integration.config.ts` points at — one fixture report and one
+ * debris sweep per integration run, before a single suite is collected.
+ *
+ * **A `globalSetup` is the only place either can correctly live.** Reaping used to happen in a suite's
+ * `beforeAll`, and Vitest runs no hooks inside a `describe.skipIf(true)` — so each reaper was gated on
+ * exactly the credential whose absence lets debris pile up, and a package with no live suite of its own
+ * reaped nothing however much it created. `globalSetup` runs before collection, so no suite's gate can
+ * switch it off, and it runs once per project rather than once per file.
+ *
+ * The fixture report is the same argument about a different thing. A suite that skips for want of a
+ * Turnstile widget prints "skipped" and nothing else, and the one place that can say *which* fixture and
+ * *where to make it* is a place no suite's gate reaches. So it runs first, and it runs **before the
+ * credentials check** — a contributor with no account is exactly who needs to be told why the run went
+ * quiet, and gating the explanation on the thing being explained is how it goes silent for them.
+ *
+ * Never throws. Housekeeping that fails the run it was meant to help is worse than the debris: a missing
+ * or unprivileged token must skip the sweep and let the suites make their own skip decision, exactly as
+ * they did before.
+ */
+export default function setup(): Promise<void>;
+//# sourceMappingURL=integrationSetup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"integrationSetup.d.ts","sourceRoot":"","sources":["../../src/test-utils/integrationSetup.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAA8B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBnD"}

package/dist/test-utils/integrationSetup.js

@@ -0,0 +1,37 @@
+import { loadIntegrationCreds } from "./harness.js";
+import { fixtureValue, reportFixtureEstate, resolveFixture } from "./fixtures.js";
+import { reapAllStaleTestResources } from "./reap.js";
+//#region src/test-utils/integrationSetup.ts
+/**
+* The Vitest `globalSetup` every `vitest.integration.config.ts` points at — one fixture report and one
+* debris sweep per integration run, before a single suite is collected.
+*
+* **A `globalSetup` is the only place either can correctly live.** Reaping used to happen in a suite's
+* `beforeAll`, and Vitest runs no hooks inside a `describe.skipIf(true)` — so each reaper was gated on
+* exactly the credential whose absence lets debris pile up, and a package with no live suite of its own
+* reaped nothing however much it created. `globalSetup` runs before collection, so no suite's gate can
+* switch it off, and it runs once per project rather than once per file.
+*
+* The fixture report is the same argument about a different thing. A suite that skips for want of a
+* Turnstile widget prints "skipped" and nothing else, and the one place that can say *which* fixture and
+* *where to make it* is a place no suite's gate reaches. So it runs first, and it runs **before the
+* credentials check** — a contributor with no account is exactly who needs to be told why the run went
+* quiet, and gating the explanation on the thing being explained is how it goes silent for them.
+*
+* Never throws. Housekeeping that fails the run it was meant to help is worse than the debris: a missing
+* or unprivileged token must skip the sweep and let the suites make their own skip decision, exactly as
+* they did before.
+*/
+async function setup() {
+	reportFixtureEstate();
+	const creds = loadIntegrationCreds();
+	if (!creds.hasCreds) return;
+	const emailRoutingZoneId = resolveFixture("email-routing").ready ? fixtureValue("email-routing", "EMAIL_ROUTING_ZONE_ID") : void 0;
+	try {
+		await reapAllStaleTestResources(creds, { emailRoutingZoneId });
+	} catch (error) {
+		console.warn(`stale test resources could not be swept: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
+export { setup as default };

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

@@ -0,0 +1,112 @@
+import { type IntegrationCreds, type ReapableKind, 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;
+}
+/** Every label in a plan, in plan order — what a test asserts against so a dropped kind is visible. */
+export declare function reapPlanLabels(plan: readonly ReapPlanEntry[]): string[];
+/**
+ * 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 declare function reapKinds(plan: readonly ReapPlanEntry[], options?: {
+    now?: number;
+    staleAfterMs?: number;
+}): Promise<ReapKindResult[]>;
+/**
+ * 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 declare function testResourceReapPlan(creds: IntegrationCreds, options?: ReapScope): ReapPlanEntry[];
+/**
+ * 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 declare function reapAllStaleTestResources(creds: IntegrationCreds, options?: ReapScope & {
+    now?: number;
+    staleAfterMs?: number;
+}): Promise<ReapKindResult[]>;
+/** Re-exported so a caller reasoning about one name does not need two imports. */
+export { testResourceAge };
+//# sourceMappingURL=reap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reap.d.ts","sourceRoot":"","sources":["../../src/test-utils/reap.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAEjB,eAAe,EAChB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,gHAAgH;IAChH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG,CAAC,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,eAAe,CAAC;AAEjF,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAOD,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAEvE;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,OAAO,CAAC,cAAc,EAAE,CAAC,CA+B3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,SAAc,GAAG,aAAa,EAAE,CAkHtG;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,SAAS,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,OAAO,CAAC,cAAc,EAAE,CAAC,CAc3B;AAED,kFAAkF;AAClF,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/test-utils/reap.js

@@ -0,0 +1,185 @@
+import { CloudflareClients } from "../client/clients.js";
+import { listEmailRoutingRules, namedRules } from "./emailRoutingRules.js";
+import { emptyTestBucket, staleTestResourceNames, testResourceAge } from "./harness.js";
+import { Cloudflare } from "cloudflare";
+//#region src/test-utils/reap.ts
+/** Whether a plan entry is a stand-in for a kind that cannot run. */
+function isSkipped(entry) {
+	return "skipped" in entry;
+}
+/** Every label in a plan, in plan order — what a test asserts against so a dropped kind is visible. */
+function reapPlanLabels(plan) {
+	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.
+*/
+async function reapKinds(plan, options = {}) {
+	const results = [];
+	for (const entry of plan) {
+		if (isSkipped(entry)) {
+			results.push({
+				label: entry.label,
+				reaped: [],
+				failed: [],
+				skipped: entry.skipped
+			});
+			continue;
+		}
+		const reaped = [];
+		const failed = [];
+		let names;
+		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.
+*/
+function testResourceReapPlan(creds, options = {}) {
+	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 [
+		{
+			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 ? {
+			label: "Email Routing rule",
+			list: async () => namedRules(await listEmailRoutingRules(creds, options.emailRoutingZoneId ?? "")).map((rule) => rule.name),
+			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);
+			}
+		},
+		{
+			label: "Queue",
+			list: async () => {
+				const names = [];
+				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),
+			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.
+*/
+async function reapAllStaleTestResources(creds, options = {}) {
+	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;
+}
+//#endregion
+export { reapAllStaleTestResources, reapKinds, reapPlanLabels, testResourceAge, testResourceReapPlan };

package/dist/tokens/accountTokensManager.d.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+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 declare function accountResource(accountId: string): Record<string, string>;
+/**
+ * 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 declare const CfPermissionGroup: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+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 declare const MintedAccountToken: z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+        expired: "expired";
+    }>>;
+}, z.core.$strip>;
+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 declare const AccountTokenSummary: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+        expired: "expired";
+    }>>;
+}, z.core.$strip>;
+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 declare class CloudflareAccountTokensManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing permission groups — a read, never a token create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    verifyToken(): Promise<CfTokenVerification>;
+    /**
+     * 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.
+     */
+    getTokenName(tokenId: string): Promise<string | null>;
+    /** Every permission group available to account-owned tokens in this account (SDK auto-paginates). */
+    listPermissionGroups(): Promise<CfPermissionGroup[]>;
+    /**
+     * 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.
+     */
+    resolvePermissionGroups(names: string[]): Promise<Array<{
+        id: string;
+    }>>;
+    /**
+     * 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.
+     */
+    mintToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+    /**
+     * 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;
+    /** Every account-owned token's metadata (SDK auto-paginates). No secret values — list is metadata only. */
+    listTokens(): Promise<AccountTokenSummary[]>;
+    /** Find an account token by exact name, or `null` — for idempotent re-mint (SDK auto-paginates). */
+    findTokenByName(name: string): Promise<AccountTokenSummary | null>;
+    /** Delete an account token by id. */
+    deleteToken(tokenId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteTokensByName(name: string): Promise<number>;
+    /**
+     * 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.
+     */
+    rollTokenValue(tokenId: string): Promise<string>;
+    /**
+     * 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.
+     */
+    rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+}
+//# sourceMappingURL=accountTokensManager.d.ts.map