@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/src/tokens/permissions.ts

@@ -46,12 +46,93 @@ export const PERMISSION_GROUPS = {
   //
   // Still not a group that can alter a zone. "Workers Routes Write" writes routes on a zone; changing
   // the zone itself would be "Zone Write", which this catalog does not have and will not get.
+  //
+  // Only this group is zone-limited. "Workers Scripts Write" is account-scoped and attaches a custom
+  // domain — a proxied DNS record and a certificate — on any zone the account holds (measured, #709;
+  // docs/TOKENS.md). So a token carrying the base can reach every zone's hostnames whatever this scopes.
   "routes:write": ["Workers Routes Write"],
+  // **Reading the account's analytics, and nothing else (#728).** The GraphQL Analytics API's account-level
+  // datasets — Stream minutes viewed, Images delivered — answer to this group. Cloudflare also has
+  // "Analytics Read", which is the **zone** group and reaches none of them.
+  //
+  // A second credential class for the kit: every other key here acts on resources the project owns,
+  // and this one reads the Cloudflare account. Its grain is the whole account, never one environment, so
+  // a capability reading it narrows the answer itself — media joins it to this environment's own assets.
+  "analytics:read": ["Account Analytics Read"],
+  // **Media's Cloudflare products, so the catalog can mint what an operator used to make by hand (#728).**
+  // A direct upload, a signing change and a delete on Cloudflare Images and on Stream. Both groups are
+  // account-scoped and edit only the account's Images and Stream libraries; they are carried by the one
+  // `runtime` token a deployed application holds, never by `ci-system`.
+  "images:write": ["Images Write"],
+  "stream:write": ["Stream Write"],
+  // **Creating and deleting the queue behind a `queue` binding (#662).** `pithy provision` creates one per
+  // binding and `pithy feature destroy` deletes a feature's, so `ci-system` carries it wherever a composition
+  // binds a queue. A Worker sends through its producer binding and needs no API token for it.
+  "queues:write": ["Queues Write"],
+  // **Listing and deleting the repos in a feature's Artifacts namespace, then the namespace (#673).** `pithy feature
+  // destroy` reaps them, because a repo costs storage and nothing else deletes one, so `ci-system` carries it wherever
+  // a composition binds `artifacts`. The account catalog names the group Write; the API schema's label says Edit. A Worker creates, reads and mints through its binding and needs no API token for any of it.
+  "artifacts:write": ["Artifacts Write"],
 } as const;
 
 /** A known permission key — one of {@link PERMISSION_GROUPS}'s keys. */
 export type PermissionKey = keyof typeof PERMISSION_GROUPS;
 
+/**
+ * **The third column: the OAuth scope each key needs a signed-in session to hold (#759).**
+ *
+ * A session mints only what it could do itself. Cloudflare refuses a mint whose permission groups the
+ * session's scopes do not cover — *"The OAuth session does not include the scopes required for the
+ * requested permission groups"*, measured 2026-10-15 — so the scopes `pithy cloudflare connect` asks for
+ * are derived from the permissions the project's tokens carry, through this table, and never listed by
+ * hand. `satisfies` over {@link PermissionKey} makes a key added above without a scope here a type error.
+ *
+ * **The ids pair with the group names one to one.** `GET /oauth/scopes` names each scope exactly as the
+ * permission group it grants — `d1.write` is "D1 Write", `workers-routes.write` is "Workers Routes Write" —
+ * which is what lets the integration test check this column against Cloudflare's own catalog the way
+ * the group names are checked against the account. A write scope also covers its read: a session holding
+ * `d1.write` minted a "D1 Read" token, so a key never needs both.
+ *
+ * Dot-delimited, always. The colon form (`account:read`) is what a first-party client like wrangler asks
+ * for, and a third-party client can neither register one nor request it.
+ */
+export const OAUTH_SCOPES = {
+  "d1:read": ["d1.read"],
+  "d1:write": ["d1.write"],
+  "workers:write": ["workers-scripts.write"],
+  "secrets:read": ["secrets-store.read"],
+  "secrets:write": ["secrets-store.write"],
+  "email:routing": ["email-routing-rule.write"],
+  "kv:write": ["workers-kv-storage.write"],
+  "r2:read": ["workers-r2.read"],
+  "r2:write": ["workers-r2.write"],
+  "vectorize:read": ["vectorize.read"],
+  "vectorize:write": ["vectorize.write"],
+  "ai:read": ["ai.read"],
+  "zone:read": ["zone.read"],
+  "routes:write": ["workers-routes.write"],
+  "analytics:read": ["account-analytics.read"],
+  "images:write": ["images.write"],
+  "stream:write": ["stream.write"],
+  "queues:write": ["queues.write"],
+  "artifacts:write": ["artifacts.write"],
+} as const satisfies Record<PermissionKey, readonly string[]>;
+
+/**
+ * Resolve permission keys to the OAuth scopes a session needs to act — or mint — with them, de-duped in
+ * first-seen order. An unknown key is refused exactly as {@link resolvePermissionKeys} refuses it.
+ */
+export function oauthScopesFor(keys: readonly string[]): string[] {
+  resolvePermissionKeys([...keys]);
+  const scopes: string[] = [];
+  for (const key of keys) {
+    for (const scope of OAUTH_SCOPES[key as PermissionKey]) {
+      if (!scopes.includes(scope)) scopes.push(scope);
+    }
+  }
+  return scopes;
+}
+
 /**
  * The keys whose Cloudflare permission group is **zone-scoped**: a policy carrying one must name zone
  * resources (`com.cloudflare.api.account.zone.<id>`), never the account resource.

package/src/tokens/profiles.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { Capability, TokenProfileSeam } from "@pithy-sh/core/src/capability/capability";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
 import { CloudflareNotConfiguredError } from "../client/errors";
 import { accountResource, type TokenPermission, zoneResources } from "./accountTokensManager";
 import {
@@ -11,12 +11,13 @@ import {
   type PermissionKey,
   resolvePermissionKeys,
 } from "./permissions";
+import { RUNTIME_PROFILE, RUNTIME_TOKEN_SECRET } from "./runtime";
 
 /**
  * Where a minted token's value is written.
  *
- * - `secrets-store` — the CF Secrets Store; a Worker reads it via its binding. The destination for a
- *   worker-consumer token; resolved from the token's declared secret (its registry backend) unless a
+ * - `secrets-store` — the CF Secrets Store; a Worker reads it via its binding. The destination for the
+ *   `runtime` token; resolved from the token's declared secret (its registry backend) unless a
  *   profile or `--store` names it directly.
  * - `dev-vars` — `<config>/<project>/tokens.json`, keyed by environment and outside every checkout.
  *   **Read by an operator, never by a command** — nothing resolves a credential from it. The store for
@@ -62,26 +63,12 @@ export interface TokenProfile {
   resources?: "account" | Record<string, string>;
   /** The secret-registry name the minted value is stored under; its declared backend is the destination. */
   secret: string;
-  /**
-   * Whether the value behind {@link secret} differs per environment (the default) or is one value every
-   * environment shares. It decides the environment segment of the **CF Secrets Store entry name** the
-   * minted value is written to, and nothing else — never the variable key, which is a variable name
-   * and stays verbatim. A `global` profile writes one entry with the literal `global` in that slot,
-   * matching what provisioning wrote; an `environment` profile writes one entry per environment.
-   */
-  secretScope?: TokenSecretScope;
   /** A built-in destination override (`dev-vars`/`ephemeral`/`secrets-store`); else the secret's backend. */
   defaultStore?: TokenStore;
   /** Why this profile exists / what job consumes it. */
   description: string;
 }
 
-/** Whether a profile's secret is one value per environment or one value shared by all of them. */
-export type TokenSecretScope = "environment" | "global";
-
-/** The valid secret scopes, for validating a capability's declaration. */
-const TOKEN_SECRET_SCOPES: readonly TokenSecretScope[] = ["environment", "global"];
-
 /** An adopter's override of a profile's defaults (from `pithy.config.ts` or CLI flags). Every field optional. */
 export interface ProfileOverride {
   /** Replace the profile's permission keys. */
@@ -112,15 +99,21 @@ function assertPermissionKeys(keys: readonly string[], where: string): Permissio
     if (!isPermissionKey(key)) {
       throw new CloudflareNotConfiguredError({
         message: `${where} declares an unknown permission key: ${key}.`,
-        action:
-          "Use a known permission key (d1:read, d1:write, workers:write, secrets:read, secrets:write, email:routing, kv:write).",
+        action: `Use a known permission key: ${Object.keys(PERMISSION_GROUPS).join(", ")}.`,
       });
     }
   }
   return keys as PermissionKey[];
 }
 
-/** Build the aggregating `ci-system` profile: the base permissions ∪ every capability's `ciPermissions`. */
+/**
+ * Build the aggregating `ci-system` profile: the base permissions ∪ every capability's `ciPermissions` ∪
+ * `queues:write` where a composed capability binds a queue ∪ `artifacts:write` where one binds Artifacts.
+ *
+ * **The queue permission is derived from the binding, not declared (#662).** `pithy provision` creates the queue
+ * behind every `queue` binding it composes, the adopter's own app's included, and the app has no `ciPermissions`
+ * anyone would think to write. A permission read off the binding cannot be forgotten by whoever declares it.
+ */
 function ciSystemProfile(capabilities: readonly Capability[]): TokenProfile {
   const permissions: PermissionKey[] = [...CI_SYSTEM_BASE];
   for (const capability of capabilities) {
@@ -128,6 +121,16 @@ function ciSystemProfile(capabilities: readonly Capability[]): TokenProfile {
       if (!permissions.includes(key)) permissions.push(key);
     }
   }
+  const bindsQueue = capabilities.some((capability) =>
+    capability.requiredBindings.some((binding) => binding.type === "queue"),
+  );
+  if (bindsQueue && !permissions.includes("queues:write")) permissions.push("queues:write");
+  // **And `artifacts:write` where one binds Artifacts (#673)**, for the same reason: `pithy feature destroy` reaps
+  // every repo in the feature's namespace under this token, and the app that binds it declares no `ciPermissions`.
+  const bindsArtifacts = capabilities.some((capability) =>
+    capability.requiredBindings.some((binding) => binding.type === "artifacts"),
+  );
+  if (bindsArtifacts && !permissions.includes("artifacts:write")) permissions.push("artifacts:write");
   return {
     name: CI_SYSTEM_PROFILE,
     permissions,
@@ -139,66 +142,47 @@ function ciSystemProfile(capabilities: readonly Capability[]): TokenProfile {
 }
 
 /**
- * The seam fields this package reads. Core's {@link TokenProfileSeam} is the structural contract every
- * capability declares against; `secretScope` is additive on top of it, so it is named here rather than
- * in core — a seam value that omits it is still assignable, and one that carries it is read as declared.
+ * Build the aggregating `runtime` profile: every composed capability's `runtimePermissions`, each once,
+ * in first-declared order — or nothing, when the composition declares none.
  *
- * Exported so a capability can type its `tokenProfiles` entry against it. Declaring `secretScope` as an
- * inline object literal directly in `tokenProfiles` still trips TypeScript's excess-property check
- * against core's narrower `TokenProfileSeam`; declare the entry as its own `const` (with `as const` or
- * `satisfies TokenProfileSeamInput`) and it flows through.
+ * **One token per deployed application, the way `ci-system` is one per pipeline.** A capability names
+ * what its Workers call Cloudflare with and never a token of its own, so a second credential is not
+ * something a capability can ask for. The token is minted per environment into the Secrets Store, so
+ * revoking staging's leaves production reading. A key whose group is zone-scoped is refused here: a
+ * Worker's token is account-scoped, and its zones would have to be chosen by hand.
  */
-export interface TokenProfileSeamInput extends TokenProfileSeam {
-  readonly secretScope?: string;
-}
-
-/** Build a concrete, validated worker-consumer {@link TokenProfile} from a capability's structural seam entry. */
-function profileFromSeam(name: string, seam: TokenProfileSeamInput, capability: string): TokenProfile {
-  const store = seam.defaultStore;
-  if (store !== undefined && !(TOKEN_STORES as readonly string[]).includes(store)) {
-    throw new CloudflareNotConfiguredError({
-      message: `Token profile "${name}" (capability "${capability}") declares an unknown store: ${store}.`,
-      action: `Use one of: ${TOKEN_STORES.join(", ")}.`,
-    });
-  }
-  const scope = seam.secretScope;
-  if (scope !== undefined && !(TOKEN_SECRET_SCOPES as readonly string[]).includes(scope)) {
-    throw new CloudflareNotConfiguredError({
-      message: `Token profile "${name}" (capability "${capability}") declares an unknown secret scope: ${scope}.`,
-      action: `Use one of: ${TOKEN_SECRET_SCOPES.join(", ")}.`,
-    });
+function runtimeProfile(capabilities: readonly Capability[]): TokenProfile | undefined {
+  const permissions: PermissionKey[] = [];
+  for (const capability of capabilities) {
+    const where = `Capability "${capability.name}"`;
+    const keys = assertPermissionKeys(capability.runtimePermissions ?? [], where);
+    assertAccountScoped(keys, `${where}'s runtimePermissions`);
+    for (const key of keys) {
+      if (!permissions.includes(key)) permissions.push(key);
+    }
   }
+  if (permissions.length === 0) return undefined;
   return {
-    name,
-    permissions: assertPermissionKeys(seam.permissions, `Token profile "${name}"`),
-    resources: seam.resources,
-    secret: seam.secret ?? tokenSecretName(name),
-    secretScope: scope as TokenSecretScope | undefined,
-    defaultStore: store as TokenStore | undefined,
-    description: seam.description ?? name,
+    name: RUNTIME_PROFILE,
+    permissions,
+    secret: RUNTIME_TOKEN_SECRET,
+    defaultStore: "secrets-store",
+    description:
+      "The one Cloudflare API token a deployed application holds: every composed capability's runtime needs, per environment. Analytics reads are account-wide by Cloudflare's grain.",
   };
 }
 
 /**
- * The project's token-profile registry: the aggregating `ci-system` profile plus every composed
- * capability's worker-consumer {@link Capability.tokenProfiles} slice. A capability profile that
- * clashes with `ci-system` (or another capability's name) fails loudly at assembly. This is the one
- * registry `pithy token` reads.
+ * The project's token-profile registry: the aggregating `ci-system` profile and, when any composed
+ * capability declares {@link Capability.runtimePermissions}, the aggregating `runtime` profile. Nothing
+ * else — a capability cannot add a profile. This is the one registry `pithy token` reads.
  */
 export function resolveTokenProfiles(capabilities: readonly Capability[]): Record<string, TokenProfile> {
-  const profiles: Record<string, TokenProfile> = { [CI_SYSTEM_PROFILE]: ciSystemProfile(capabilities) };
-  for (const capability of capabilities) {
-    for (const [name, seam] of Object.entries(capability.tokenProfiles ?? {})) {
-      if (profiles[name]) {
-        throw new CloudflareNotConfiguredError({
-          message: `Token profile "${name}" is declared more than once (capability "${capability.name}").`,
-          action: "Give each token profile a unique name.",
-        });
-      }
-      profiles[name] = profileFromSeam(name, seam, capability.name);
-    }
-  }
-  return profiles;
+  const runtime = runtimeProfile(capabilities);
+  return {
+    [CI_SYSTEM_PROFILE]: ciSystemProfile(capabilities),
+    ...(runtime ? { [RUNTIME_PROFILE]: runtime } : {}),
+  };
 }
 
 /**
@@ -263,6 +247,10 @@ export function permissionsForKeys(keys: PermissionKey[], accountId: string): To
  * 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.
  *
+ * **This limits the route, not the token.** The account policy beside it carries Workers Scripts Write,
+ * which attaches a custom domain on any zone the account holds (measured, #709; `docs/TOKENS.md`). Only
+ * the route calls are held to the declared zones.
+ *
  * **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.

package/src/tokens/runtime.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **The names of the one Cloudflare API token a deployed application holds (#728)**, in a module of their
+ * own. A Worker reads the token by {@link RUNTIME_TOKEN_SECRET}, and importing the profile registry to
+ * learn a string would put the token-minting client on every Worker's bundle. Nothing here imports anything.
+ */
+
+/** The name of the one runtime token — the single Cloudflare API token a deployed application holds (#728). */
+export const RUNTIME_PROFILE = "runtime";
+
+/**
+ * The secret the runtime token's value is stored under, and the binding every Worker that calls Cloudflare
+ * reads it through. Unscoped, because it is a binding name: the Secrets Store entry it resolves to carries
+ * the project and environment (`<project>-<env>-runtime-cf-api-token`).
+ */
+export const RUNTIME_TOKEN_SECRET = "RUNTIME_CF_API_TOKEN";