@pithy-sh/cloudflare 0.1.1 → 0.1.3

package/dist/d1/d1Provisioner.js

@@ -0,0 +1,67 @@
+import { cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/d1/d1Provisioner.ts
+/** A D1 database's identity, decoded from the create response. */
+const D1DatabaseInfo = z.object({
+	uuid: z.string().describe("The CF-assigned database id (a uuid) used to address the database."),
+	name: z.string().describe("The database name.")
+}).describe("A Cloudflare D1 database's identity, as returned by the create endpoint.");
+/**
+* Account-level D1 control plane: **create and delete databases**. Customers use this to stand up
+* and tear down per-environment databases (e.g. ephemeral staging), and `pithy add secrets` uses it
+* to provision each environment's secrets D1. Addressed by account — unlike {@link CloudflareD1Manager},
+* which targets one database id for queries.
+*/
+var CloudflareD1Provisioner = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare D1 (control plane)";
+	}
+	/** Prove access by listing databases — a read, never a destructive create/delete. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().d1.database.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** Every D1 database in the account — for prefix-scan reconcile teardown (`pithy feature destroy`). */
+	async listDatabases() {
+		return cloudflareRequest("list D1 databases", async () => {
+			const databases = [];
+			for await (const db of this.getClient().d1.database.list({ account_id: this.accountId })) {
+				const parsed = D1DatabaseInfo.safeParse(db);
+				if (parsed.success) databases.push(parsed.data);
+			}
+			return databases;
+		});
+	}
+	/** Find a database by exact name in the account, or `null` — for idempotent provisioning. */
+	async findDatabaseByName(name) {
+		return cloudflareRequest(`find D1 database ${name}`, async () => {
+			for await (const db of this.getClient().d1.database.list({
+				account_id: this.accountId,
+				name
+			})) {
+				const parsed = D1DatabaseInfo.safeParse(db);
+				if (parsed.success && parsed.data.name === name) return parsed.data;
+			}
+			return null;
+		});
+	}
+	/** Create a D1 database by name; returns its id and name. */
+	async createDatabase(name) {
+		const response = await cloudflareRequest(`create D1 database ${name}`, () => this.getClient().d1.database.create({
+			account_id: this.accountId,
+			name
+		}));
+		return decodeResponse(D1DatabaseInfo, response, "D1 database create");
+	}
+	/** Delete a D1 database by id. */
+	async deleteDatabase(databaseId) {
+		await cloudflareRequest(`delete D1 database ${databaseId}`, () => this.getClient().d1.database.delete(databaseId, { account_id: this.accountId }));
+	}
+};
+//#endregion
+export { CloudflareD1Provisioner, D1DatabaseInfo };

package/dist/email/emailRoutingManager.d.ts

@@ -0,0 +1,36 @@
+import { CloudflareManager } from "../client/manager";
+export declare class CloudflareEmailRoutingManager extends CloudflareManager {
+    #private;
+    getServiceType(): string;
+    /** Prove reach by listing a zone's routing rules; never throws. (Account-level reach is a weak proxy here.) */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Ensure a routing rule named `ruleName` exists on `zoneId`, delivering mail addressed to `address`
+     * to the Worker `workerName`. Idempotent: if a rule with that name already exists it is left as-is.
+     * Assumes Email Routing is already enabled on the zone.
+     */
+    ensureWorkerRoute(options: {
+        zoneId: string;
+        address: string;
+        workerName: string;
+        ruleName: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Remove the rule named `ruleName` from `zoneId`, so mail stops being delivered to the Worker behind it.
+     * Idempotent: a zone carrying no such rule is a no-op, which is what lets a teardown be re-run.
+     *
+     * **Matched on the rule name, never on the address.** The name is the key `ensureWorkerRoute` created
+     * under, so the two agree on which rule belongs to which capability even after somebody edited the
+     * address in the dashboard — and a teardown that matched on the address would happily delete a rule an
+     * operator wrote by hand for the same mailbox.
+     */
+    removeWorkerRoute(options: {
+        zoneId: string;
+        ruleName: string;
+    }): Promise<{
+        removed: boolean;
+    }>;
+}
+//# sourceMappingURL=emailRoutingManager.d.ts.map

package/dist/email/emailRoutingManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailRoutingManager.d.ts","sourceRoot":"","sources":["../../src/email/emailRoutingManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA2CtD,qBAAa,6BAA8B,SAAQ,iBAAiB;;IAClE,cAAc,IAAI,MAAM,CAEvB;IAED,+GAA+G;IACzG,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAE9C;IAED;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE;QAC/B,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAehC;IAED;;;;;;;;OAQG;IACG,iBAAiB,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAQpG;CAwCF"}

package/dist/email/emailRoutingManager.js

@@ -0,0 +1,124 @@
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/email/emailRoutingManager.ts
+/**
+* Cloudflare Email Routing rules — the inbound side. Used by email provisioning to point a domain's
+* bounce/complaint mail at the app worker that hosts the `email()` handler. Email Routing is
+* **zone-scoped** (a rule lives on a zone, and routing must already be enabled on that zone — enabling
+* it sets the zone's MX, an operator action we never take automatically, so the apex MX stays put).
+*
+* Rule *creation and deletion* go through the typed SDK. The lookup both of them turn on cannot:
+* `emailRouting.rules` exposes only create/update/delete/get, and `get` addresses a rule by CF id — we
+* match by name, which needs a listing the SDK has no method for. That one read stays on the documented
+* raw-`fetch` escape hatch; drop it the moment a `rules.list` lands.
+*/
+/** A routing rule's stored shape — only the fields we match on for idempotency. */
+const RuleEnvelope = z.object({
+	success: z.boolean(),
+	result: z.array(z.object({
+		id: z.string().optional(),
+		name: z.string().optional()
+	})).nullable().default([]),
+	/**
+	* The paging block. Present on every list response, and read rather than ignored because both
+	* callers ask a question a truncated answer gets **wrong in the dangerous direction**: an unseen
+	* rule reads as "no such rule", which makes `ensureWorkerRoute` create a duplicate on every run and
+	* `removeWorkerRoute` report a removal while mail is still being delivered.
+	*/
+	result_info: z.object({
+		page: z.number().optional(),
+		per_page: z.number().optional(),
+		total_count: z.number().optional(),
+		total_pages: z.number().optional()
+	}).nullish()
+});
+/** Rules per page. Cloudflare's maximum, so the common zone is answered in one request. */
+const RULES_PER_PAGE = 50;
+/** A hard stop on the page loop, so a malformed `result_info` cannot spin forever. */
+const MAX_RULE_PAGES = 100;
+var CloudflareEmailRoutingManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Email Routing";
+	}
+	/** Prove reach by listing a zone's routing rules; never throws. (Account-level reach is a weak proxy here.) */
+	async validateServiceAccess() {
+		return true;
+	}
+	/**
+	* Ensure a routing rule named `ruleName` exists on `zoneId`, delivering mail addressed to `address`
+	* to the Worker `workerName`. Idempotent: if a rule with that name already exists it is left as-is.
+	* Assumes Email Routing is already enabled on the zone.
+	*/
+	async ensureWorkerRoute(options) {
+		const { zoneId, address, workerName, ruleName } = options;
+		return cloudflareRequest("Email Routing ensure worker rule", async () => {
+			if ((await this.#listRules(zoneId)).some((rule) => rule.name === ruleName)) return { created: false };
+			await this.getClient().emailRouting.rules.create({
+				zone_id: zoneId,
+				name: ruleName,
+				enabled: true,
+				matchers: [{
+					type: "literal",
+					field: "to",
+					value: address
+				}],
+				actions: [{
+					type: "worker",
+					value: [workerName]
+				}]
+			});
+			return { created: true };
+		});
+	}
+	/**
+	* Remove the rule named `ruleName` from `zoneId`, so mail stops being delivered to the Worker behind it.
+	* Idempotent: a zone carrying no such rule is a no-op, which is what lets a teardown be re-run.
+	*
+	* **Matched on the rule name, never on the address.** The name is the key `ensureWorkerRoute` created
+	* under, so the two agree on which rule belongs to which capability even after somebody edited the
+	* address in the dashboard — and a teardown that matched on the address would happily delete a rule an
+	* operator wrote by hand for the same mailbox.
+	*/
+	async removeWorkerRoute(options) {
+		const { zoneId, ruleName } = options;
+		return cloudflareRequest("Email Routing remove worker rule", async () => {
+			const rule = (await this.#listRules(zoneId)).find((candidate) => candidate.name === ruleName);
+			if (!rule?.id) return { removed: false };
+			await this.getClient().emailRouting.rules.delete(rule.id, { zone_id: zoneId });
+			return { removed: true };
+		});
+	}
+	/**
+	* **Every** routing rule on a zone, by the raw-`fetch` escape hatch this file's header documents —
+	* the SDK has no listing, and both matching by name and deleting by id need one.
+	*
+	* Paged to exhaustion rather than reading the first page. A zone with more rules than fit one page
+	* is unusual but entirely legal, and a partial read is not a smaller answer here — it is a *wrong*
+	* one, because both callers treat "not in the list" as "does not exist". Provisioning would then
+	* create a second rule for the same address on every run, and a teardown would report mail stopped
+	* while it kept arriving.
+	*
+	* A failed read **throws**, for the same reason: silently degrading to an empty list would produce
+	* exactly the two failures above.
+	*/
+	async #listRules(zoneId) {
+		const rules = [];
+		for (let page = 1; page <= MAX_RULE_PAGES; page += 1) {
+			const url = `https://api.cloudflare.com/client/v4/zones/${zoneId}/email/routing/rules?page=${page}&per_page=${RULES_PER_PAGE}`;
+			const listed = await fetch(url, { headers: { Authorization: `Bearer ${this.getApiToken()}` } });
+			if (!listed.ok) throw new CloudflareInvalidResponseError({
+				message: "Could not read the zone's Email Routing rules.",
+				detail: `Email Routing rule list returned ${listed.status}: ${await listed.text()}`
+			});
+			const envelope = RuleEnvelope.parse(await listed.json());
+			const batch = envelope.result ?? [];
+			rules.push(...batch);
+			const totalPages = envelope.result_info?.total_pages;
+			if (totalPages !== void 0 ? page >= totalPages : batch.length < RULES_PER_PAGE) break;
+		}
+		return rules;
+	}
+};
+//#endregion
+export { CloudflareEmailRoutingManager };

package/dist/email/emailSendManager.d.ts

@@ -0,0 +1,45 @@
+import { CloudflareManager } from "../client/manager";
+/**
+ * Out-of-Worker sends through the Cloudflare Email Service REST API — the control-plane counterpart to
+ * the in-Worker `send_email` binding. Used by the CLI's `pithy email test` to render and deliver one
+ * template through a project's configuration without deploying. Inside a Worker, always prefer the
+ * binding (no token, principle-1 aligned).
+ */
+/** A message to send over REST. `from` mirrors the binding's `{ email, name }`; the wire uses `address`. */
+export interface EmailSendInput {
+    to: string | string[];
+    from: {
+        email: string;
+        name?: string;
+    };
+    subject: string;
+    html: string;
+    text: string;
+    replyTo?: string;
+}
+/** What the send returned: the assigned message id and any synchronous delivery breakdown. */
+export interface EmailSendResult {
+    messageId?: string;
+    delivered: string[];
+    queued: string[];
+    permanentBounces: string[];
+}
+export declare class CloudflareEmailSendManager extends CloudflareManager {
+    getServiceType(): string;
+    /**
+     * Prove reach by reading the account's sending limits; never throws (returns false on any failure).
+     * `/email/sending/limits` has no typed SDK method — only `send` and `subdomains` do — so this stays
+     * on the documented raw-`fetch` escape hatch. Probing `subdomains.list` instead would change what
+     * the check proves: a token scoped to send but not to read subdomains would start reporting false.
+     */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Send one message through the Email Sending API. Throws `cloudflare/request_failed` on any API
+     * error — the SDK unwraps the envelope and raises on `success: false`, so a resolved call is a send.
+     *
+     * `from` is sent as the object form only when a display name exists; the SDK's object form requires
+     * `name`, and the bare-string form is the wire's own representation of "address, no display name".
+     */
+    send(message: EmailSendInput): Promise<EmailSendResult>;
+}
+//# sourceMappingURL=emailSendManager.d.ts.map

package/dist/email/emailSendManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailSendManager.d.ts","sourceRoot":"","sources":["../../src/email/emailSendManager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D,cAAc,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACG,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAU9C;IAED;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAkB5D;CACF"}

package/dist/email/emailSendManager.js

@@ -0,0 +1,52 @@
+import { cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+//#region src/email/emailSendManager.ts
+var CloudflareEmailSendManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Email Sending";
+	}
+	/**
+	* Prove reach by reading the account's sending limits; never throws (returns false on any failure).
+	* `/email/sending/limits` has no typed SDK method — only `send` and `subdomains` do — so this stays
+	* on the documented raw-`fetch` escape hatch. Probing `subdomains.list` instead would change what
+	* the check proves: a token scoped to send but not to read subdomains would start reporting false.
+	*/
+	async validateServiceAccess() {
+		try {
+			return (await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.getAccountId()}/email/sending/limits`, { headers: { Authorization: `Bearer ${this.getApiToken()}` } })).ok;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Send one message through the Email Sending API. Throws `cloudflare/request_failed` on any API
+	* error — the SDK unwraps the envelope and raises on `success: false`, so a resolved call is a send.
+	*
+	* `from` is sent as the object form only when a display name exists; the SDK's object form requires
+	* `name`, and the bare-string form is the wire's own representation of "address, no display name".
+	*/
+	async send(message) {
+		return cloudflareRequest("Email Service send", async () => {
+			const result = await this.getClient().emailSending.send({
+				account_id: this.getAccountId(),
+				to: message.to,
+				from: message.from.name ? {
+					address: message.from.email,
+					name: message.from.name
+				} : message.from.email,
+				subject: message.subject,
+				html: message.html,
+				text: message.text,
+				...message.replyTo ? { reply_to: message.replyTo } : {}
+			});
+			return {
+				messageId: result.message_id,
+				delivered: result.delivered,
+				queued: result.queued,
+				permanentBounces: result.permanent_bounces
+			};
+		});
+	}
+};
+//#endregion
+export { CloudflareEmailSendManager };

package/dist/env/devVars.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Cloudflare credential keys pithy reads out-of-Worker (CLI, provisioning, live tests). These are
+ * wrangler's own env-var names plus the Secrets Store id. From this single bootstrap token
+ * (`CLOUDFLARE_API_TOKEN`) pithy **mints** the scoped, least-privilege tokens each use case needs —
+ * most notably the secrets manager's runtime token, minted at provision time and written straight into
+ * the Secrets Store, so no scoped token is ever supplied or kept here.
+ *
+ * **Where they are read from is not this module's answer any more (#182).** They are account-scoped, so
+ * they live in `<config>/cloudflare.json` — or, since #206, in `<config>/cloudflare.<name>.json` when a
+ * project's root config names its account. See `@pithy-sh/cli`'s `cloudflare/config`, which owns the
+ * file, which file, the `process.env` overlay, and the split diagnostic. The names stay here because
+ * both ends need them and the Worker-side package is the one both can import.
+ *
+ * **The overlay has an off switch, and it is not `PITHY_CONFIG_DIR` (#218).** Relocating the config
+ * directory moves the *file*; these four names are still read out of the ambient environment, which is
+ * how a CLI run in an empty scratch directory reached a real account off a token a shell had exported
+ * hours earlier. `PITHY_OFFLINE` is the word that stops it, and it lives with the overlay it governs —
+ * `PITHY_OFFLINE_ENV` in `@pithy-sh/cli`'s `cloudflare/config`. Anything outside the CLI that grows a
+ * reason to read one of these names off `process.env` inherits that obligation with it.
+ */
+export declare const CLOUDFLARE_ENV_KEYS: readonly ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN", "SECRETS_STORE_ID", "R2_CREDENTIALS"];
+/**
+ * Which of {@link CLOUDFLARE_ENV_KEYS} an environment actually carries a value for. The one place that
+ * list is turned into a check.
+ *
+ * **Non-empty, not merely present.** `vitest.shared.ts`'s `NO_ACCOUNT` pins all four keys to `""`, and
+ * the `process.env` overlay in `@pithy-sh/cli`'s `cloudflare/config` already reads a blank as unset. A
+ * predicate keying on presence would report every guarded unit project as leaking.
+ *
+ * **This module is bundled into workerd as well as run on the host, and that is why it imports nothing.**
+ * The repository-root `vitest.workers.setup.ts` imports this function relatively and every workers
+ * project loads it, so a `node:` import here breaks seventeen suites at collection. `vitest.shared.ts`
+ * already leans on the same property for {@link CLOUDFLARE_ENV_KEYS} and says so. Nothing gates the
+ * import half — `@pithy-sh/core` has `worker-safety.test.ts` and this package has no equivalent — so it
+ * is a constraint a reader has to be told, which is what this paragraph is. The other half is gated:
+ * `packages/cli/src/ci/testIsolation.test.ts` walks what every workers config imports, so this module
+ * is in that scan and a `process.env` read here is red (#437).
+ */
+export declare function visibleCredentialKeys(env: Readonly<Record<string, string | undefined>>): readonly string[];
+/**
+ * Parse a `.dev.vars` file body into a map: `KEY=value` lines, `#` comments and blanks skipped, and
+ * a single layer of surrounding quotes stripped. Pure — the caller owns the file read.
+ */
+export declare function parseDevVars(content: string): Record<string, string>;
+/**
+ * The keys that only mean anything **together, from one account**: the account id, and a token minted in
+ * that account. Deliberately just the pair.
+ *
+ * The other {@link CLOUDFLARE_ENV_KEYS} stay out, because each fails loudly and immediately when it comes
+ * from the wrong account: a store id this account does not hold 404s on the first call, and an S3 key
+ * that does not belong to the account in the endpoint will not sign. Only the pair can *quietly* succeed
+ * somewhere unintended — a live token against another account's id is a 403 or an empty listing much
+ * later — so only the pair is a group. That is the whole test for membership.
+ *
+ * **A whole file can be the wrong account too.** This pair is the *half-file, half-environment* case; one
+ * level up, a file that is entirely coherent in itself can belong to a different company than the project
+ * reading it, which is what a project's `cloudflare.accountName` and its `accountId` pin answer (#206).
+ *
+ * `SECRETS_STORE_ID` used to be excluded on the grounds that it is "routinely passed per environment
+ * while the pair sits in the file". That was never true: Cloudflare permits **one Secrets Store per
+ * account**, so nothing about the id is per-environment, and it now sits in `cloudflare.json` beside the
+ * pair for exactly that reason (#182). The conclusion was right; the stated reason was not.
+ */
+export declare const CLOUDFLARE_CREDENTIAL_KEYS: readonly ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"];
+//# sourceMappingURL=devVars.d.ts.map

package/dist/env/devVars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devVars.d.ts","sourceRoot":"","sources":["../../src/env/devVars.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,YAC9B,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,CACR,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,MAAM,EAAE,CAE1G;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAapE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,YAAI,uBAAuB,EAAE,sBAAsB,CAAU,CAAC"}

package/dist/env/devVars.js

@@ -0,0 +1,84 @@
+//#region src/env/devVars.ts
+/**
+* The Cloudflare credential keys pithy reads out-of-Worker (CLI, provisioning, live tests). These are
+* wrangler's own env-var names plus the Secrets Store id. From this single bootstrap token
+* (`CLOUDFLARE_API_TOKEN`) pithy **mints** the scoped, least-privilege tokens each use case needs —
+* most notably the secrets manager's runtime token, minted at provision time and written straight into
+* the Secrets Store, so no scoped token is ever supplied or kept here.
+*
+* **Where they are read from is not this module's answer any more (#182).** They are account-scoped, so
+* they live in `<config>/cloudflare.json` — or, since #206, in `<config>/cloudflare.<name>.json` when a
+* project's root config names its account. See `@pithy-sh/cli`'s `cloudflare/config`, which owns the
+* file, which file, the `process.env` overlay, and the split diagnostic. The names stay here because
+* both ends need them and the Worker-side package is the one both can import.
+*
+* **The overlay has an off switch, and it is not `PITHY_CONFIG_DIR` (#218).** Relocating the config
+* directory moves the *file*; these four names are still read out of the ambient environment, which is
+* how a CLI run in an empty scratch directory reached a real account off a token a shell had exported
+* hours earlier. `PITHY_OFFLINE` is the word that stops it, and it lives with the overlay it governs —
+* `PITHY_OFFLINE_ENV` in `@pithy-sh/cli`'s `cloudflare/config`. Anything outside the CLI that grows a
+* reason to read one of these names off `process.env` inherits that obligation with it.
+*/
+const CLOUDFLARE_ENV_KEYS = [
+	"CLOUDFLARE_ACCOUNT_ID",
+	"CLOUDFLARE_API_TOKEN",
+	"SECRETS_STORE_ID",
+	"R2_CREDENTIALS"
+];
+/**
+* Which of {@link CLOUDFLARE_ENV_KEYS} an environment actually carries a value for. The one place that
+* list is turned into a check.
+*
+* **Non-empty, not merely present.** `vitest.shared.ts`'s `NO_ACCOUNT` pins all four keys to `""`, and
+* the `process.env` overlay in `@pithy-sh/cli`'s `cloudflare/config` already reads a blank as unset. A
+* predicate keying on presence would report every guarded unit project as leaking.
+*
+* **This module is bundled into workerd as well as run on the host, and that is why it imports nothing.**
+* The repository-root `vitest.workers.setup.ts` imports this function relatively and every workers
+* project loads it, so a `node:` import here breaks seventeen suites at collection. `vitest.shared.ts`
+* already leans on the same property for {@link CLOUDFLARE_ENV_KEYS} and says so. Nothing gates the
+* import half — `@pithy-sh/core` has `worker-safety.test.ts` and this package has no equivalent — so it
+* is a constraint a reader has to be told, which is what this paragraph is. The other half is gated:
+* `packages/cli/src/ci/testIsolation.test.ts` walks what every workers config imports, so this module
+* is in that scan and a `process.env` read here is red (#437).
+*/
+function visibleCredentialKeys(env) {
+	return CLOUDFLARE_ENV_KEYS.filter((key) => (env[key] ?? "").length > 0);
+}
+/**
+* Parse a `.dev.vars` file body into a map: `KEY=value` lines, `#` comments and blanks skipped, and
+* a single layer of surrounding quotes stripped. Pure — the caller owns the file read.
+*/
+function parseDevVars(content) {
+	const vars = {};
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq === -1) continue;
+		vars[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+	}
+	return vars;
+}
+/**
+* The keys that only mean anything **together, from one account**: the account id, and a token minted in
+* that account. Deliberately just the pair.
+*
+* The other {@link CLOUDFLARE_ENV_KEYS} stay out, because each fails loudly and immediately when it comes
+* from the wrong account: a store id this account does not hold 404s on the first call, and an S3 key
+* that does not belong to the account in the endpoint will not sign. Only the pair can *quietly* succeed
+* somewhere unintended — a live token against another account's id is a 403 or an empty listing much
+* later — so only the pair is a group. That is the whole test for membership.
+*
+* **A whole file can be the wrong account too.** This pair is the *half-file, half-environment* case; one
+* level up, a file that is entirely coherent in itself can belong to a different company than the project
+* reading it, which is what a project's `cloudflare.accountName` and its `accountId` pin answer (#206).
+*
+* `SECRETS_STORE_ID` used to be excluded on the grounds that it is "routinely passed per environment
+* while the pair sits in the file". That was never true: Cloudflare permits **one Secrets Store per
+* account**, so nothing about the id is per-environment, and it now sits in `cloudflare.json` beside the
+* pair for exactly that reason (#182). The conclusion was right; the stated reason was not.
+*/
+const CLOUDFLARE_CREDENTIAL_KEYS = ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"];
+//#endregion
+export { CLOUDFLARE_CREDENTIAL_KEYS, CLOUDFLARE_ENV_KEYS, parseDevVars, visibleCredentialKeys };

package/dist/hostnames/customHostnamesManager.d.ts

@@ -0,0 +1,51 @@
+import type { CustomHostnameCreateResponse, CustomHostnameDeleteResponse, CustomHostnameGetResponse, CustomHostnameListResponse } from "cloudflare/resources/custom-hostnames/custom-hostnames";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+/**
+ * Config for the Custom Hostnames manager: the shared client config plus the zone the hostnames
+ * live under. Custom hostnames are a zone-scoped resource — the REST API addresses them by
+ * `zone_id`, so the zone is required configuration here.
+ */
+export interface CustomHostnamesManagerConfig extends CloudflareManagerConfig {
+    /** The zone id custom hostnames are created and managed under (the CF zone serving the apex). */
+    zoneId: string;
+}
+/** Options for creating a custom hostname. */
+export interface CreateCustomHostnameOptions {
+    /**
+     * The minimum TLS version the issued certificate negotiates. Defaults to `1.2`. Custom hostnames
+     * use HTTP DCV with a DV certificate.
+     */
+    minTlsVersion?: "1.0" | "1.1" | "1.2" | "1.3";
+}
+/**
+ * Out-of-Worker Custom Hostnames access over the REST API: create, look up, and remove custom
+ * hostnames on a zone from a CLI/CI/provisioning context. Custom hostnames let a zone serve domains
+ * it does not own DNS for — a customer CNAMEs their domain to a fallback origin on the zone, and CF
+ * issues a certificate via HTTP domain-control validation. Addressed by zone id.
+ */
+export declare class CloudflareCustomHostnamesManager extends CloudflareManager {
+    private readonly zoneId;
+    constructor(config: CustomHostnamesManagerConfig);
+    /**
+     * Create a custom hostname with HTTP DCV and a DV certificate. Idempotent: if a custom hostname
+     * already exists for this hostname, the existing record is returned instead of creating a duplicate.
+     */
+    addCustomHostname(hostname: string, options?: CreateCustomHostnameOptions): Promise<CustomHostnameCreateResponse | CustomHostnameListResponse>;
+    /** Look up a custom hostname by its fully qualified name. Returns null when none matches. */
+    getCustomHostname(hostname: string): Promise<CustomHostnameListResponse | null>;
+    /** Fetch a custom hostname by its id. */
+    getCustomHostnameById(customHostnameId: string): Promise<CustomHostnameGetResponse>;
+    /** List every custom hostname on the zone. */
+    listCustomHostnames(): Promise<CustomHostnameListResponse[]>;
+    /** Remove a custom hostname by its id. */
+    removeCustomHostname(customHostnameId: string): Promise<CustomHostnameDeleteResponse>;
+    /** The zone this manager targets and the account it lives in. */
+    getCustomHostnamesInfo(): {
+        zoneId: string;
+        accountId: string;
+    };
+    getServiceType(): string;
+    /** Prove access by listing custom hostnames on the zone. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=customHostnamesManager.d.ts.map

package/dist/hostnames/customHostnamesManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customHostnamesManager.d.ts","sourceRoot":"","sources":["../../src/hostnames/customHostnamesManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC3B,MAAM,wDAAwD,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8CAA8C;AAC9C,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;CAC/C;AAED;;;;;GAKG;AACH,qBAAa,gCAAiC,SAAQ,iBAAiB;IACrE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,MAAM,EAAE,4BAA4B,EAM/C;IAED;;;OAGG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,4BAA4B,GAAG,0BAA0B,CAAC,CAepE;IAED,6FAA6F;IACvF,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAapF;IAED,yCAAyC;IACnC,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAIxF;IAED,8CAA8C;IACxC,mBAAmB,IAAI,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAQjE;IAED,0CAA0C;IACpC,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAI1F;IAED,iEAAiE;IACjE,sBAAsB,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE9D;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,0EAA0E;IACpE,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAS9C;CACF"}

package/dist/hostnames/customHostnamesManager.js

@@ -0,0 +1,84 @@
+import { CloudflareNotConfiguredError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+//#region src/hostnames/customHostnamesManager.ts
+/**
+* Out-of-Worker Custom Hostnames access over the REST API: create, look up, and remove custom
+* hostnames on a zone from a CLI/CI/provisioning context. Custom hostnames let a zone serve domains
+* it does not own DNS for — a customer CNAMEs their domain to a fallback origin on the zone, and CF
+* issues a certificate via HTTP domain-control validation. Addressed by zone id.
+*/
+var CloudflareCustomHostnamesManager = class extends CloudflareManager {
+	zoneId;
+	constructor(config) {
+		super(config);
+		if (!config.zoneId) throw new CloudflareNotConfiguredError({ detail: "Missing zoneId for Custom Hostnames REST access." });
+		this.zoneId = config.zoneId;
+	}
+	/**
+	* Create a custom hostname with HTTP DCV and a DV certificate. Idempotent: if a custom hostname
+	* already exists for this hostname, the existing record is returned instead of creating a duplicate.
+	*/
+	async addCustomHostname(hostname, options) {
+		const existing = await this.getCustomHostname(hostname);
+		if (existing) return existing;
+		return cloudflareRequest(`add custom hostname '${hostname}'`, () => this.getClient().customHostnames.create({
+			zone_id: this.zoneId,
+			hostname,
+			ssl: {
+				method: "http",
+				type: "dv",
+				settings: { min_tls_version: options?.minTlsVersion ?? "1.2" }
+			}
+		}));
+	}
+	/** Look up a custom hostname by its fully qualified name. Returns null when none matches. */
+	async getCustomHostname(hostname) {
+		return cloudflareRequest(`get custom hostname '${hostname}'`, async () => {
+			for await (const candidate of this.getClient().customHostnames.list({
+				zone_id: this.zoneId,
+				hostname: { exact: hostname }
+			})) if (candidate.hostname === hostname) return candidate;
+			return null;
+		});
+	}
+	/** Fetch a custom hostname by its id. */
+	async getCustomHostnameById(customHostnameId) {
+		return cloudflareRequest(`get custom hostname by id '${customHostnameId}'`, () => this.getClient().customHostnames.get(customHostnameId, { zone_id: this.zoneId }));
+	}
+	/** List every custom hostname on the zone. */
+	async listCustomHostnames() {
+		return cloudflareRequest("list custom hostnames", async () => {
+			const hostnames = [];
+			for await (const candidate of this.getClient().customHostnames.list({ zone_id: this.zoneId })) hostnames.push(candidate);
+			return hostnames;
+		});
+	}
+	/** Remove a custom hostname by its id. */
+	async removeCustomHostname(customHostnameId) {
+		return cloudflareRequest(`remove custom hostname '${customHostnameId}'`, () => this.getClient().customHostnames.delete(customHostnameId, { zone_id: this.zoneId }));
+	}
+	/** The zone this manager targets and the account it lives in. */
+	getCustomHostnamesInfo() {
+		return {
+			zoneId: this.zoneId,
+			accountId: this.accountId
+		};
+	}
+	getServiceType() {
+		return "Cloudflare Custom Hostnames";
+	}
+	/** Prove access by listing custom hostnames on the zone. Never throws. */
+	async validateServiceAccess() {
+		try {
+			for await (const _candidate of this.getClient().customHostnames.list({
+				zone_id: this.zoneId,
+				per_page: 1
+			})) break;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareCustomHostnamesManager };