@pithy-sh/cloudflare 0.1.0

package/src/secrets/secretsStoreManager.ts

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+
+/** Scopes attached to every secret we create. CF requires at least one; "workers" is the bind target. */
+const DEFAULT_SCOPES = ["workers"] as const;
+
+/**
+ * One secret in the store, decoded from the CF list response. CF Secrets Store never returns
+ * plaintext over REST — values are bind-only by design — so this carries only metadata. The
+ * `created`/`modified` ISO strings decode through `JsonDate` to real `Date`s at the wire boundary.
+ */
+export const CfSecretEntry = z
+  .object({
+    id: z.string().describe("The CF-assigned secret identifier, used to address delete by id."),
+    name: z.string().describe("The secret's name within the store (the key the CLI references)."),
+    status: z.enum(["pending", "active", "deleted"]).describe("The secret's lifecycle status in the store."),
+    created: JsonDate.describe("When the secret was created (ISO string on the wire, Date in app)."),
+    modified: JsonDate.describe("When the secret was last modified (ISO string on the wire, Date in app)."),
+  })
+  .describe("A single Cloudflare Secrets Store secret's metadata (never its plaintext value).");
+export type CfSecretEntry = z.output<typeof CfSecretEntry>;
+
+/** Config for the Secrets Store manager: the shared client config plus the store it targets. */
+export interface SecretsStoreManagerConfig extends CloudflareManagerConfig {
+  /** The CF Secrets Store id (the REST API addresses stores by id). */
+  storeId: string;
+}
+
+/**
+ * Out-of-Worker access to the account-level Cloudflare Secrets Store over the REST API: provisioning
+ * and audit from a CLI/CI context. Inside a Worker, secret values resolve via bindings — this manager
+ * is the REST counterpart for managing the store, addressed by store id.
+ *
+ * CF Secrets Store does not expose secret plaintext via REST (values are bind-only by design), so
+ * there is no `getSecret`. The provisioning and audit flows only need put, delete, and list.
+ */
+export class CloudflareSecretsStoreManager extends CloudflareManager {
+  private readonly storeId: string;
+
+  constructor(config: SecretsStoreManagerConfig) {
+    super(config);
+    if (!config.storeId) {
+      throw new CloudflareNotConfiguredError({ detail: "Missing storeId for Secrets Store REST access." });
+    }
+    this.storeId = config.storeId;
+  }
+
+  getServiceType(): string {
+    return "Cloudflare Secrets Store";
+  }
+
+  /** Prove access by listing the store's secrets. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.listSecrets();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Insert or update a secret. An existing entry is updated in place via `edit`; otherwise a fresh
+   * secret is created.
+   *
+   * `edit` is what makes this safe. The old value is overwritten, never deleted first, so a failed
+   * update leaves the prior value intact and bound — there is no window where the secret is absent
+   * from the store (which, for a secret like the master encryption key, is a platform-level outage).
+   * Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+   */
+  async putSecret(name: string, value: string): Promise<void> {
+    const existing = await this.findByName(name);
+    if (!existing) {
+      await this.createSecret(name, value);
+      return;
+    }
+
+    await cloudflareRequest(`put secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.edit(existing.id, {
+        account_id: this.accountId,
+        store_id: this.storeId,
+        value,
+        scopes: [...DEFAULT_SCOPES],
+      }),
+    );
+  }
+
+  /** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
+  async deleteSecret(name: string): Promise<void> {
+    const existing = await this.findByName(name);
+    if (!existing) {
+      throw new NotFoundError({
+        message: `Secret '${name}' was not found in the store.`,
+        detail: `delete secret ${name}: no entry with that name`,
+      });
+    }
+    await cloudflareRequest(`delete secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.delete(existing.id, {
+        account_id: this.accountId,
+        store_id: this.storeId,
+      }),
+    );
+  }
+
+  /**
+   * Delete a secret, treating an absent one as already done.
+   *
+   * The typed not-found on {@link deleteSecret} is right for a caller that named a specific secret and
+   * needs to hear it was not there. It is wrong for anything reconciling toward absence — teardown, a
+   * reaper, a re-run of a provisioning step — where "gone" is the goal and a second delete is a no-op,
+   * not a failure. Two callers race on the store all the time: another runner's sweep, or a listing that
+   * has not caught up.
+   *
+   * Given as its own method rather than a flag, so which semantics a call site wants is legible at the
+   * call site. The alternative every caller reaches for otherwise is `.catch(() => {})`, which also
+   * swallows the auth failure and the outage — and a teardown that swallows is how debris becomes
+   * permanent with no signal at all.
+   */
+  async deleteSecretIfPresent(name: string): Promise<boolean> {
+    const existing = await this.findByName(name);
+    if (!existing) return false;
+    await cloudflareRequest(`delete secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.delete(existing.id, {
+        account_id: this.accountId,
+        store_id: this.storeId,
+      }),
+    );
+    return true;
+  }
+
+  /**
+   * List every secret in the store. The SDK auto-paginates via `for await`, so callers receive the
+   * full set in one array. Each entry is Zod-validated (`CfSecretEntry`) at the wire boundary.
+   */
+  async listSecrets(): Promise<CfSecretEntry[]> {
+    return cloudflareRequest("list secrets", async () => {
+      const out: CfSecretEntry[] = [];
+      for await (const entry of this.getClient().secretsStore.stores.secrets.list(this.storeId, {
+        account_id: this.accountId,
+      })) {
+        out.push(decodeResponse(CfSecretEntry, entry, "Secrets Store list entry"));
+      }
+      return out;
+    });
+  }
+
+  /** Whether a secret with the given name currently exists in the store. */
+  async exists(name: string): Promise<boolean> {
+    return (await this.findByName(name)) !== undefined;
+  }
+
+  /** The store this manager targets and the account it lives in. */
+  getSecretsStoreInfo(): { storeId: string; accountId: string } {
+    return { storeId: this.storeId, accountId: this.accountId };
+  }
+
+  /** Create a single secret with the default scopes. */
+  private async createSecret(name: string, value: string): Promise<void> {
+    await cloudflareRequest(`create secret ${name}`, () =>
+      this.getClient().secretsStore.stores.secrets.create(this.storeId, {
+        account_id: this.accountId,
+        body: [{ name, value, scopes: [...DEFAULT_SCOPES] }],
+      }),
+    );
+  }
+
+  private async findByName(name: string): Promise<CfSecretEntry | undefined> {
+    const all = await this.listSecrets();
+    return all.find((entry) => entry.name === name);
+  }
+}

package/src/secrets/secretsStores.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * The **account-level** view of Cloudflare Secrets Store: which stores exist, and nothing else.
+ *
+ * Its sibling {@link CloudflareSecretsStoreManager} is addressed *by store id* — it demands one in its
+ * constructor, because every operation it has is inside a store. That is the right shape for putting and
+ * deleting secrets and the wrong shape for the one question asked before any store id is known: which
+ * store does this account have?
+ *
+ * **One store per account**, which is what makes the answer usable at all. `pithy add secrets` resolves
+ * the id here, once, at provisioning time, and writes it into `<config>/cloudflare.json` — so every later
+ * run is a plain file read. Discovery on every invocation was considered and rejected (#182): a CLI that
+ * cannot run offline because it has to ask Cloudflare where its own store is has lost more than the key
+ * was costing.
+ */
+
+/**
+ * One store in the account, decoded from the CF list response.
+ *
+ * Metadata only — a store holds secrets whose plaintext the REST API never returns. The `created` and
+ * `modified` ISO strings decode through `JsonDate` at the wire boundary, as every other response here
+ * does, so nothing downstream parses a date string a second time.
+ */
+export const CfSecretsStore = z
+  .object({
+    id: z.string().describe("The CF-assigned store identifier — the value that becomes SECRETS_STORE_ID."),
+    name: z.string().describe("The store's display name, for naming it back to an operator who has two."),
+    created: JsonDate.describe("When the store was created (ISO string on the wire, Date in app)."),
+    modified: JsonDate.describe("When the store was last modified (ISO string on the wire, Date in app)."),
+  })
+  .describe("A single Cloudflare Secrets Store's metadata. Never a secret, and never a secret's value.");
+export type CfSecretsStore = z.output<typeof CfSecretsStore>;
+
+/** Account-level Secrets Store operations: listing the account's stores. Addressed by account, not store. */
+export class CloudflareSecretsStoresManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Secrets Store (account)";
+  }
+
+  /** Prove access by listing the account's stores. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.listStores();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Every Secrets Store in the account. The SDK auto-paginates via `for await`, so a caller receives
+   * the full set in one array, and each entry is Zod-validated at the wire boundary.
+   *
+   * **Returns the list, never a choice.** Cloudflare permits one store per account, so the ordinary
+   * answer has exactly one element — but "ordinarily one" is not "always one", and picking the first of
+   * two would be guessing which store holds an adopter's production secrets. The caller decides, and the
+   * only correct decision for two is to refuse and name them.
+   */
+  async listStores(): Promise<CfSecretsStore[]> {
+    return cloudflareRequest("list secrets stores", async () => {
+      const out: CfSecretsStore[] = [];
+      for await (const store of this.getClient().secretsStore.stores.list({ account_id: this.accountId })) {
+        out.push(decodeResponse(CfSecretsStore, store, "Secrets Store list entry"));
+      }
+      return out;
+    });
+  }
+}

package/src/test-utils/emailRoutingRules.ts

@@ -0,0 +1,122 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { CloudflareRequestError } from "../client/errors";
+import type { IntegrationCreds } from "./harness";
+
+/**
+ * A zone's Email Routing rules, read whole.
+ *
+ * `CloudflareEmailRoutingManager` reads the same endpoint and keeps only `id` and `name`, because
+ * matching by name and deleting by id is all provisioning needs. Two callers here need more.
+ *
+ * **A live test has to see what Cloudflare stored, not what we sent.** #47's open question is whether
+ * the `matchers`/`actions` shape `ensureWorkerRoute` posts still matches the current API — and a test
+ * that asserts on its own request argument answers nothing. So the rule comes back in full and the
+ * assertions are on the stored copy.
+ *
+ * **The reaper needs names it can hand back to `removeWorkerRoute`.** A run that dies between creating
+ * a rule and tearing it down leaves live mail routing to a Worker that is about to be deleted, which is
+ * the one piece of debris in this repo that changes what happens to somebody's mail rather than costing
+ * a few cents.
+ *
+ * ## Two documented traps, both live here so nobody has to rediscover them
+ *
+ * **Every zone has a catch-all rule whether or not anything is configured** — no name, priority
+ * `2147483647`, `matchers: [{ type: "all" }]`. A rule count of 1 means nothing. {@link namedRules}
+ * drops it, so a caller counting *our* rules counts ours.
+ *
+ * **`result_info` on this endpoint carries no `total_pages`** on a single-page zone. The paging loop
+ * therefore stops on a short page, exactly as the manager's does.
+ */
+
+/** 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;
+
+/** One matcher on a routing rule: which mail the rule claims. */
+export const EmailRoutingMatcher = z
+  .object({
+    type: z.string().describe("`literal` for one address, `all` for the zone's catch-all."),
+    field: z.string().optional().describe("The header the literal matches on — `to` for every rule Pithy writes."),
+    value: z.string().optional().describe("The address a `literal` matcher claims. Absent on a catch-all."),
+  })
+  .describe("One matcher on an Email Routing rule.");
+
+/** One action on a routing rule: what happens to the mail it claimed. */
+export const EmailRoutingAction = z
+  .object({
+    type: z.string().describe("`worker` for a Worker delivery, `drop` for the default catch-all, `forward` otherwise."),
+    value: z.array(z.string()).default([]).describe("The action's targets — a single Worker script name for `worker`."),
+  })
+  .describe("One action on an Email Routing rule.");
+
+/** One Email Routing rule, as the zone stores it. */
+export const EmailRoutingRule = z
+  .object({
+    id: z.string().describe("Cloudflare's id for the rule — what a delete addresses."),
+    name: z.string().default("").describe("The rule's name. Empty on the default catch-all every zone carries."),
+    enabled: z
+      .boolean()
+      .default(false)
+      .describe("Whether the rule is live. The catch-all's flag doubles as the zone's."),
+    priority: z.number().default(0).describe("Match order, lowest first. The catch-all sits at 2147483647."),
+    matchers: z.array(EmailRoutingMatcher).default([]).describe("Which mail this rule claims."),
+    actions: z.array(EmailRoutingAction).default([]).describe("What happens to the mail this rule claimed."),
+  })
+  .describe("One Email Routing rule on a zone, read back in full.");
+
+/** One Email Routing rule, as the zone stores it. */
+export type EmailRoutingRule = z.output<typeof EmailRoutingRule>;
+
+/** The list envelope, validated because a response read is a boundary. */
+const RuleListEnvelope = z
+  .object({
+    success: z.boolean().describe("Cloudflare's own verdict on the request."),
+    result: z.array(EmailRoutingRule).nullable().default([]).describe("This page of rules. Null on a failed call."),
+    result_info: z
+      .object({
+        page: z.number().optional().describe("The page just returned."),
+        total_pages: z.number().optional().describe("Total pages, when Cloudflare states one. Often absent."),
+      })
+      .nullish()
+      .describe("The paging block, when the response carries one."),
+  })
+  .describe("A page of a zone's Email Routing rules.");
+
+/** Every Email Routing rule on a zone, paged to exhaustion. */
+export async function listEmailRoutingRules(creds: IntegrationCreds, zoneId: string): Promise<EmailRoutingRule[]> {
+  const rules: EmailRoutingRule[] = [];
+
+  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 response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
+    if (!response.ok) {
+      throw new CloudflareRequestError({
+        message: "Could not read the zone's Email Routing rules.",
+        action: "Check the token carries Email Routing Rules: Read on this zone.",
+        detail: `Email Routing rule list returned ${response.status}.`,
+      });
+    }
+
+    const envelope = RuleListEnvelope.parse(await response.json());
+    const batch = envelope.result ?? [];
+    rules.push(...batch);
+
+    const totalPages = envelope.result_info?.total_pages;
+    if (totalPages !== undefined ? page >= totalPages : batch.length < RULES_PER_PAGE) break;
+  }
+
+  return rules;
+}
+
+/**
+ * The rules somebody named — the zone's own rules, without the unnamed catch-all Cloudflare puts on
+ * every zone configured or not.
+ */
+export function namedRules(rules: readonly EmailRoutingRule[]): EmailRoutingRule[] {
+  return rules.filter((rule) => rule.name !== "");
+}

package/src/test-utils/fixtureReportSetup.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { reportFixtureEstate } from "./fixtures";
+
+/**
+ * The `globalSetup` for an integration config whose suites **create nothing** — the fixture report, and
+ * no debris sweep.
+ *
+ * `integrationSetup.ts` beside this does both, and it is the right entry point for a package that mints
+ * a Worker, a database or a bucket. A package whose live suites only *read* a third party — a token
+ * endpoint, a siteverify — has nothing to reclaim, and pointing it at the sweeping setup would mean
+ * every run of it deleted stale resources across the whole account on behalf of suites it does not run.
+ * That is somebody else's housekeeping, done at a surprising moment, and it costs a run half a minute
+ * of REST calls that answer nothing about the code under test.
+ *
+ * The report half is not optional either way, which is the whole reason this file exists rather than
+ * the config simply declaring no `globalSetup`. Vitest runs no hooks inside a `describe.skipIf(true)`,
+ * so a suite that skips for want of a fixture is exactly the suite that cannot say which fixture — see
+ * the long note in `fixtures.ts`. A config with no `globalSetup` gets a silent skip, and a silent skip
+ * is the failure mode #106 exists to remove.
+ *
+ * **Switch a config to `integrationSetup` the moment one of its suites creates a Cloudflare resource.**
+ * A suite that mints and a run that never sweeps is how debris becomes permanent.
+ *
+ * Never throws, for the same reason its neighbor does not: a report that fails the run it was meant to
+ * explain is worse than no report.
+ */
+export default function setup(): void {
+  reportFixtureEstate();
+}