@pithy-sh/cloudflare 0.4.2 → 0.6.0

package/dist/tokens/permissions.d.ts

@@ -25,9 +25,58 @@ export declare const PERMISSION_GROUPS: {
     readonly "ai:read": readonly ["Workers AI Read"];
     readonly "zone:read": readonly ["Zone Read"];
     readonly "routes:write": readonly ["Workers Routes Write"];
+    readonly "analytics:read": readonly ["Account Analytics Read"];
+    readonly "images:write": readonly ["Images Write"];
+    readonly "stream:write": readonly ["Stream Write"];
+    readonly "queues:write": readonly ["Queues Write"];
+    readonly "artifacts:write": readonly ["Artifacts Write"];
 };
 /** 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 declare const OAUTH_SCOPES: {
+    readonly "d1:read": readonly ["d1.read"];
+    readonly "d1:write": readonly ["d1.write"];
+    readonly "workers:write": readonly ["workers-scripts.write"];
+    readonly "secrets:read": readonly ["secrets-store.read"];
+    readonly "secrets:write": readonly ["secrets-store.write"];
+    readonly "email:routing": readonly ["email-routing-rule.write"];
+    readonly "kv:write": readonly ["workers-kv-storage.write"];
+    readonly "r2:read": readonly ["workers-r2.read"];
+    readonly "r2:write": readonly ["workers-r2.write"];
+    readonly "vectorize:read": readonly ["vectorize.read"];
+    readonly "vectorize:write": readonly ["vectorize.write"];
+    readonly "ai:read": readonly ["ai.read"];
+    readonly "zone:read": readonly ["zone.read"];
+    readonly "routes:write": readonly ["workers-routes.write"];
+    readonly "analytics:read": readonly ["account-analytics.read"];
+    readonly "images:write": readonly ["images.write"];
+    readonly "stream:write": readonly ["stream.write"];
+    readonly "queues:write": readonly ["queues.write"];
+    readonly "artifacts:write": readonly ["artifacts.write"];
+};
+/**
+ * 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 declare function oauthScopesFor(keys: readonly string[]): string[];
 /**
  * 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/dist/tokens/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/tokens/permissions.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,YAAG,SAAS;aAIrB,UAAU,YAAG,UAAU;aACvB,eAAe,YAAG,uBAAuB;aACzC,cAAc,YAAG,oBAAoB;aACrC,eAAe,YAAG,qBAAqB;aACvC,eAAe,YAAG,2BAA2B;aAC7C,UAAU,YAAG,0BAA0B;aACvC,SAAS,YAAG,yBAAyB;aACrC,UAAU,YAAG,0BAA0B;aACvC,gBAAgB,YAAG,gBAAgB;aACnC,iBAAiB,YAAG,iBAAiB;aACrC,SAAS,YAAG,iBAAiB;aAK7B,WAAW,YAAG,WAAW;aAazB,cAAc,YAAG,sBAAsB;CAC/B,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,aAAa,EAAqB,CAAC;AAElF,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/tokens/permissions.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,YAAG,SAAS;aAIrB,UAAU,YAAG,UAAU;aACvB,eAAe,YAAG,uBAAuB;aACzC,cAAc,YAAG,oBAAoB;aACrC,eAAe,YAAG,qBAAqB;aACvC,eAAe,YAAG,2BAA2B;aAC7C,UAAU,YAAG,0BAA0B;aACvC,SAAS,YAAG,yBAAyB;aACrC,UAAU,YAAG,0BAA0B;aACvC,gBAAgB,YAAG,gBAAgB;aACnC,iBAAiB,YAAG,iBAAiB;aACrC,SAAS,YAAG,iBAAiB;aAK7B,WAAW,YAAG,WAAW;aAiBzB,cAAc,YAAG,sBAAsB;aAQvC,gBAAgB,YAAG,wBAAwB;aAK3C,cAAc,YAAG,cAAc;aAC/B,cAAc,YAAG,cAAc;aAI/B,cAAc,YAAG,cAAc;aAI/B,iBAAiB,YAAG,iBAAiB;CAC7B,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;CAoBoC,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAShE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,aAAa,EAAqB,CAAC;AAElF,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D"}

package/dist/tokens/permissions.js

@@ -26,9 +26,63 @@ const PERMISSION_GROUPS = {
 	"vectorize:write": ["Vectorize Write"],
 	"ai:read": ["Workers AI Read"],
 	"zone:read": ["Zone Read"],
-	"routes:write": ["Workers Routes Write"]
+	"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"]
 };
 /**
+* **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.
+*/
+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"]
+};
+/**
+* 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.
+*/
+function oauthScopesFor(keys) {
+	resolvePermissionKeys([...keys]);
+	const scopes = [];
+	for (const key of keys) for (const scope of OAUTH_SCOPES[key]) 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.
 *
@@ -64,4 +118,4 @@ function resolvePermissionKeys(keys) {
 	return names;
 }
 //#endregion
-export { PERMISSION_GROUPS, ZONE_SCOPED_PERMISSIONS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys };
+export { OAUTH_SCOPES, PERMISSION_GROUPS, ZONE_SCOPED_PERMISSIONS, isPermissionKey, isZoneScopedPermission, oauthScopesFor, resolvePermissionKeys };

package/dist/tokens/profiles.d.ts

@@ -1,13 +1,13 @@
 // 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 { type TokenPermission } from "./accountTokensManager";
 import { type PermissionKey } from "./permissions";
 /**
  * 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
@@ -37,21 +37,11 @@ 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";
 /** 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. */
@@ -69,23 +59,9 @@ export declare function tokenSecretName(profile: string): string;
  */
 export declare function defineTokenProfile(profile: TokenProfile): 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.
- *
- * 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.
- */
-export interface TokenProfileSeamInput extends TokenProfileSeam {
-    readonly secretScope?: string;
-}
-/**
- * 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 declare function resolveTokenProfiles(capabilities: readonly Capability[]): Record<string, TokenProfile>;
 /**
@@ -105,6 +81,10 @@ export declare function permissionsForKeys(keys: PermissionKey[], accountId: str
  * 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/dist/tokens/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/tokens/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAmB,KAAK,eAAe,EAAiB,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA+C,CAAC;AAE9F,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAe7C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,2GAA2G;IAC3G,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kGAAkG;AAClG,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,CAAC;AAKxD,iHAAiH;AACjH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAGtE;AAkCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CActG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,eAAe,GACzB,YAAY,CAgBd;AAsBD,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAG9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,EAAE,CAG9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAK9F"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/tokens/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,EAAmB,KAAK,eAAe,EAAiB,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAGvB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA+C,CAAC;AAE9F,4GAA4G;AAC5G,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAe7C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,oFAAoF;IACpF,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,0GAA0G;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,2GAA2G;IAC3G,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iHAAiH;AACjH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sDAAsD;IACtD,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAGtE;AAiFD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAMtG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,eAAe,GACzB,YAAY,CAgBd;AAsBD,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAG9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,EAAE,CAG9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAK9F"}

package/dist/tokens/profiles.js

@@ -3,6 +3,7 @@
 import { CloudflareNotConfiguredError } from "../client/errors.js";
 import { accountResource, zoneResources } from "./accountTokensManager.js";
 import { PERMISSION_GROUPS, isPermissionKey, isZoneScopedPermission, resolvePermissionKeys } from "./permissions.js";
+import { RUNTIME_PROFILE, RUNTIME_TOKEN_SECRET } from "./runtime.js";
 //#region src/tokens/profiles.ts
 /** The valid stores, for validating a `--store` flag or a profile's `defaultStore`. */
 const TOKEN_STORES = [
@@ -24,8 +25,6 @@ const CI_SYSTEM_BASE = [
 	"secrets:read",
 	"secrets:write"
 ];
-/** The valid secret scopes, for validating a capability's declaration. */
-const TOKEN_SECRET_SCOPES = ["environment", "global"];
 /** The env-var / secret name a profile's token is stored under: `CF_TOKEN_<PROFILE>`. */
 function tokenSecretName(profile) {
 	return `CF_TOKEN_${profile.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
@@ -42,14 +41,23 @@ function defineTokenProfile(profile) {
 function assertPermissionKeys(keys, where) {
 	for (const key of keys) 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;
 }
-/** 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) {
 	const permissions = [...CI_SYSTEM_BASE];
 	for (const capability of capabilities) for (const key of assertPermissionKeys(capability.ciPermissions ?? [], `Capability "${capability.name}"`)) if (!permissions.includes(key)) permissions.push(key);
+	if (capabilities.some((capability) => capability.requiredBindings.some((binding) => binding.type === "queue")) && !permissions.includes("queues:write")) permissions.push("queues:write");
+	if (capabilities.some((capability) => capability.requiredBindings.some((binding) => binding.type === "artifacts")) && !permissions.includes("artifacts:write")) permissions.push("artifacts:write");
 	return {
 		name: CI_SYSTEM_PROFILE,
 		permissions,
@@ -58,44 +66,44 @@ function ciSystemProfile(capabilities) {
 		description: "The one CI pipeline credential: deploy Workers, migrate, and every composed capability's CI needs. Set it as CI's CLOUDFLARE_API_TOKEN."
 	};
 }
-/** Build a concrete, validated worker-consumer {@link TokenProfile} from a capability's structural seam entry. */
-function profileFromSeam(name, seam, capability) {
-	const store = seam.defaultStore;
-	if (store !== void 0 && !TOKEN_STORES.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 !== void 0 && !TOKEN_SECRET_SCOPES.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(", ")}.`
-	});
+/**
+* Build the aggregating `runtime` profile: every composed capability's `runtimePermissions`, each once,
+* in first-declared order — or nothing, when the composition declares none.
+*
+* **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.
+*/
+function runtimeProfile(capabilities) {
+	const permissions = [];
+	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 void 0;
 	return {
-		name,
-		permissions: assertPermissionKeys(seam.permissions, `Token profile "${name}"`),
-		resources: seam.resources,
-		secret: seam.secret ?? tokenSecretName(name),
-		secretScope: scope,
-		defaultStore: store,
-		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.
 */
 function resolveTokenProfiles(capabilities) {
-	const profiles = { [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 } : {}
+	};
 }
 /**
 * Resolve a profile by name from the aggregated registry, applying an adopter override. An unknown
@@ -152,6 +160,10 @@ function permissionsForKeys(keys, accountId) {
 * 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/dist/tokens/runtime.d.ts

@@ -0,0 +1,16 @@
+// 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 declare 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 declare const RUNTIME_TOKEN_SECRET = "RUNTIME_CF_API_TOKEN";
+//# sourceMappingURL=runtime.d.ts.map

package/dist/tokens/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/tokens/runtime.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC"}

package/dist/tokens/runtime.js

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/tokens/runtime.ts
+/**
+* **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). */
+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`).
+*/
+const RUNTIME_TOKEN_SECRET = "RUNTIME_CF_API_TOKEN";
+//#endregion
+export { RUNTIME_PROFILE, RUNTIME_TOKEN_SECRET };

package/dist/workers/buildsManager.js

@@ -3,8 +3,8 @@
 import { CloudflareInvalidResponseError, cloudflareApiErrors, cloudflareRefusal, cloudflareRequest, decodeResponse, messageOf } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfRepoConnection } from "./buildsTypes.js";
-import { z } from "zod";
 import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
 //#region src/workers/buildsManager.ts
 /** The Cloudflare REST API v4 base URL. The Builds endpoints live under `/accounts/{id}/builds`. */
 const CF_API_BASE = "https://api.cloudflare.com/client/v4";

package/dist/workflows/stepFailure.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { z } from "zod";
 import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
 import { MAX_WORKFLOW_STEP_TEXT, decodeWorkflowStepMessage, splitWorkflowStepCode } from "@pithy-sh/core/src/workflow/stepMessage";
 import { guaranteedErrorParams } from "@pithy-sh/core/src/error/messageParams";
 import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";

package/dist/workflows/workflowsClient.js

@@ -3,8 +3,8 @@
 import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { stepFailure, terminalWorkflowError } from "./stepFailure.js";
-import { z } from "zod";
 import { UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
 //#region src/workflows/workflowsClient.ts
 const WorkflowInstanceStatus = z.enum([
 	"queued",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/cloudflare",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
-    "typecheck": "tsc -p tsconfig.json",
+    "typecheck": "bun check -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
     "test:integration": "vitest run --config vitest.integration.config.ts",
@@ -40,7 +40,7 @@
     "js-base64": "^3.9.2"
   },
   "peerDependencies": {
-    "@pithy-sh/core": "^0.9.0",
+    "@pithy-sh/core": "^0.11.0",
     "zod": "^4.4.0"
   },
   "devDependencies": {

package/src/ai/aiManager.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { AIRunParams, AIRunResponse } from "cloudflare/resources/ai/ai";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { AIRunResponse } from "cloudflare/resources/ai/ai";
 import type { ModelListResponse } from "cloudflare/resources/ai/models/models";
 import { fromUint8Array } from "js-base64";
 import { z } from "zod";
@@ -128,6 +129,39 @@ export interface AnalyzeImageOptions {
 
 const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable for alt text.";
 
+/**
+ * What a Workers AI model name may look like: `@<namespace>/` and then one to three segments, each made of
+ * letters, digits, `.`, `_` and `-` and starting with a letter or digit — `@cf/baai/bge-m3`,
+ * `@cf/llava-hf/llava-1.5-7b-hf`, `@hf/thebloke/deepseek-coder-6.7b-instruct-awq`.
+ *
+ * **The name goes into the request path unencoded, so this pattern is the whole of the defense.** A segment
+ * cannot be `.` or `..` (it must start with a letter or digit), and nothing that ends a path, opens a query
+ * or a fragment, or escapes a character (`?`, `#`, `%`, `\`, whitespace) is in the alphabet. A name outside
+ * it is refused before a request exists.
+ */
+const AI_MODEL_NAME = /^@[a-z0-9][a-z0-9-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*){1,3}$/;
+
+/**
+ * The REST path that runs `model`: `/accounts/<id>/ai/run/@cf/baai/bge-m3`, the model's slashes literal.
+ *
+ * **Not the SDK's `ai.run` (#709).** cloudflare 7.0.0 builds that path with its `path` tag, which
+ * percent-encodes every path parameter, the `/`s inside a model name included. Cloudflare routes on the
+ * literal slashes, so `/ai/run/@cf%2Fbaai%2Fbge-m3` answers 7000 "No route for that URI" for every model.
+ * The path is built here instead, and a name that could change its shape is refused by {@link AI_MODEL_NAME}.
+ *
+ * @throws ValidationError (`validation/invalid_input`) when `model` is not a Workers AI model name.
+ */
+export function aiRunPath(accountId: string, model: string): string {
+  if (!AI_MODEL_NAME.test(model)) {
+    throw new ValidationError({
+      message: `"${model.slice(0, 120)}" is not a Workers AI model name.`,
+      action: "Pass a model name such as @cf/baai/bge-m3. The Workers AI model catalog lists them.",
+      detail: `model name ${JSON.stringify(model)} does not match ${AI_MODEL_NAME}`,
+    });
+  }
+  return `/accounts/${encodeURIComponent(accountId)}/ai/run/${model}`;
+}
+
 /**
  * Out-of-Worker Workers AI access over the REST API: run any model, generate text, generate
  * embeddings, analyze an image, and list models from a CLI/CI/provisioning context. Inside a
@@ -138,12 +172,17 @@ const DEFAULT_IMAGE_PROMPT = "Describe this image in a concise sentence suitable
 export class CloudflareAIManager extends CloudflareManager {
   /**
    * Run a Cloudflare AI model by name with an arbitrary JSON input. The single seam every typed
-   * helper builds on. The account id is injected for you; the rest of `input` is the model's body.
+   * helper builds on. The account is addressed for you; `input` is the model's body.
+   *
+   * Through the SDK's raw `post` to {@link aiRunPath}, not `ai.run`, whose path encoding Cloudflare cannot
+   * route. A malformed model name throws `validation/invalid_input` before any request is sent.
    */
   async runModel(model: string, input: Record<string, unknown>): Promise<AIRunResponse> {
-    return cloudflareRequest(`AI run model '${model}'`, () =>
-      this.getClient().ai.run(model, { account_id: this.accountId, ...input } as AIRunParams),
-    );
+    const path = aiRunPath(this.accountId, model);
+    return cloudflareRequest(`AI run model '${model}'`, async () => {
+      const envelope = await this.getClient().post<{ result: AIRunResponse }>(path, { body: input });
+      return envelope.result;
+    });
   }
 
   /**