@pithy-sh/cloudflare 0.3.0 → 0.4.0

package/src/tokens/profiles.ts

@@ -3,8 +3,14 @@
 
 import type { Capability, TokenProfileSeam } from "@pithy-sh/core/src/capability/capability";
 import { CloudflareNotConfiguredError } from "../client/errors";
-import { accountResource, type TokenPermission } from "./accountTokensManager";
-import { isPermissionKey, type PermissionKey, resolvePermissionKeys } from "./permissions";
+import { accountResource, type TokenPermission, zoneResources } from "./accountTokensManager";
+import {
+  isPermissionKey,
+  isZoneScopedPermission,
+  PERMISSION_GROUPS,
+  type PermissionKey,
+  resolvePermissionKeys,
+} from "./permissions";
 
 /**
  * Where a minted token's value is written.
@@ -221,17 +227,58 @@ export function resolveProfile(
   };
 }
 
+/**
+ * Refuse a zone-scoped key anywhere a policy is being built **account-scoped**.
+ *
+ * A zone-level permission group handed the account resource is the quiet failure (#651): Cloudflare
+ * mints the token without complaint and then answers "No access to the specified resource" at the call,
+ * which is a CI failure hours later with nothing in it naming the scope. Which zones a token gets is
+ * never a typed choice — it is the project's declared `domains`, resolved at mint time — so a key naming
+ * one in a profile or behind `--permission` is a mistake, and this is where it is caught.
+ */
+function assertAccountScoped(keys: readonly string[], where: string): void {
+  const zoneScoped = keys.filter(isZoneScopedPermission);
+  if (zoneScoped.length === 0) return;
+  throw new CloudflareNotConfiguredError({
+    message: `${where} names zone-scoped permission(s): ${zoneScoped.join(", ")}.`,
+    action:
+      "A zone permission is not chosen by hand — declare the Worker's `domains` in pithy.config.ts and the mint scopes the token to those zones. Remove the key.",
+    detail: `build token policy: ${zoneScoped.join(", ")} cannot take the account resource`,
+  });
+}
+
 /** Build the account-scoped {@link TokenPermission}s for a set of permission keys — the mint input. */
 export function permissionsForKeys(keys: PermissionKey[], accountId: string): TokenPermission[] {
+  assertAccountScoped(keys, "This token");
   return [{ permissionGroupNames: resolvePermissionKeys(keys), resources: accountResource(accountId) }];
 }
 
+/**
+ * The **zone-scoped** policy a project's declared domains require: Workers Routes Write on exactly those
+ * zones, and nothing else.
+ *
+ * This is the second policy on the `ci-system` token, beside the account-scoped one every profile
+ * builds. It exists because `pithy deploy` of an environment with a declared domain calls
+ * `POST /zones/<zone>/workers/routes`, the one deploy step the CI credential could not make (#651) — and
+ * it is a policy of its own rather than a permission on the profile because its resources are zones,
+ * which a profile cannot name: they are resolved from the domains at mint time.
+ *
+ * **Empty for an empty zone list, deliberately.** A project that declares no domain attaches no route,
+ * so it mints exactly the token it minted before this existed. No new permission for a project that
+ * needs none.
+ */
+export function routePermissions(zoneIds: readonly string[]): TokenPermission[] {
+  if (zoneIds.length === 0) return [];
+  return [{ permissionGroupNames: [...PERMISSION_GROUPS["routes:write"]], resources: zoneResources(zoneIds) }];
+}
+
 /**
  * Turn a resolved profile into the {@link TokenPermission}s the account-tokens manager mints from: the
  * profile's permission keys resolved to CF group names, scoped to the account (or the profile's
  * explicit resources). One policy per profile — a token carries exactly the access its profile declares.
  */
 export function profilePermissions(profile: TokenProfile, accountId: string): TokenPermission[] {
+  assertAccountScoped(profile.permissions, `Token profile "${profile.name}"`);
   const resources =
     profile.resources && profile.resources !== "account" ? profile.resources : accountResource(accountId);
   return [{ permissionGroupNames: resolvePermissionKeys(profile.permissions), resources }];

package/src/workers/buildsManager.ts

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
 import { z } from "zod";
 import {
   CloudflareInvalidResponseError,
-  CloudflareRequestError,
   cloudflareApiErrors,
   cloudflareRefusal,
   cloudflareRequest,
@@ -350,12 +350,19 @@ export class CloudflareBuildsManager extends CloudflareManager {
 }
 
 /**
- * Whether a thrown `CloudflareRequestError` carries the given CF error code. Reads the `[cf-codes:…]`
+ * Whether a thrown Cloudflare refusal carries the given CF error code. Reads the `[cf-codes:…]`
  * marker `call()` pins to the front of `detail` (stable across the 2000-char truncation); falls back
  * to a substring scan for errors raised without the structured marker.
+ *
+ * **Narrowed on `PithyError`, not on one subclass of it (#647).** This read used to require a
+ * `CloudflareRequestError`, which was true of every refusal for as long as `cloudflareRefusal` composed
+ * exactly one class. It no longer does: a 429 or a 5xx is now an `UpstreamError`, so that narrowing
+ * would have silently stopped seeing a CF error code the moment Cloudflare answered one under a status
+ * that retries. The code lives in `detail`, which every `PithyError` carries, so the payload is what to
+ * read and the class is not.
  */
 function hasErrorCode(error: unknown, code: number): boolean {
-  if (!(error instanceof CloudflareRequestError)) return false;
+  if (!(error instanceof PithyError)) return false;
   const detail = error.payload.detail ?? "";
   const marker = detail.match(/^\[cf-codes:([\d,]+)\]/);
   if (marker?.[1]) return marker[1].split(",").includes(String(code));

package/src/workflows/workflowsClient.ts

@@ -55,6 +55,15 @@ export const WorkflowInstance = z
   .describe("A Cloudflare Workflow instance's status, as returned by the instance-detail endpoint.");
 export type WorkflowInstance = z.output<typeof WorkflowInstance>;
 
+/** One deployed Workflow definition — its name and the script that hosts it — from the account's list. */
+export const WorkflowDefinition = z
+  .object({
+    name: z.string().describe("The Workflow's account-wide name, e.g. `acme-prod-email-send`."),
+    script_name: z.string().describe("The Worker script whose exported class runs the Workflow."),
+  })
+  .describe("A Workflow definition on the account, as far as teardown needs one: what it is called and who hosts it.");
+export type WorkflowDefinition = z.output<typeof WorkflowDefinition>;
+
 /** Terminal states a poll stops on. */
 const TERMINAL: ReadonlySet<WorkflowInstanceStatus> = new Set(["complete", "errored", "terminated"]);
 
@@ -93,6 +102,39 @@ export class CloudflareWorkflowsClient extends CloudflareManager {
     }
   }
 
+  /**
+   * Every Workflow definition on the account, validated at the wire boundary. What `pithy feature destroy` reads
+   * to find the Workflows a feature's scripts host, by exact script name (#643).
+   */
+  async listWorkflows(): Promise<WorkflowDefinition[]> {
+    return cloudflareRequest("list Workflows", async () => {
+      const out: WorkflowDefinition[] = [];
+      for await (const workflow of this.getClient().workflows.list({ account_id: this.accountId })) {
+        const parsed = WorkflowDefinition.safeParse(workflow);
+        if (!parsed.success) throw new CloudflareInvalidResponseError({ detail: "list Workflows: unexpected shape" });
+        out.push(parsed.data);
+      }
+      return out;
+    });
+  }
+
+  /**
+   * Delete a Workflow definition by name, resolving `false` when there was none (#643). Cloudflare's own
+   * reference says this deletes the Workflow and leaves the Worker script alone; whether deleting the script
+   * deletes its Workflows it does not say, so teardown deletes them explicitly rather than rely on either.
+   */
+  async deleteWorkflow(workflowName: string): Promise<boolean> {
+    return cloudflareRequest(`delete Workflow ${workflowName}`, async () => {
+      try {
+        await this.getClient().workflows.delete(workflowName, { account_id: this.accountId });
+        return true;
+      } catch (error) {
+        if (isNotFoundError(error)) return false;
+        throw error;
+      }
+    });
+  }
+
   /** Create (trigger) a Workflow instance and return its id. */
   async createInstance(workflowName: string, params: unknown, instanceId?: string): Promise<string> {
     return cloudflareRequest(`create instance of ${workflowName}`, async () => {