@pithy-sh/cloudflare 0.5.0 → 0.6.0

package/src/client/clients.ts

@@ -4,6 +4,8 @@
 import { CloudflareAIManager } from "../ai/aiManager";
 import { CloudflareVectorizeManager } from "../ai/vectorizeManager";
 import { CloudflareVectorizeProvisioner } from "../ai/vectorizeProvisioner";
+import { CloudflareAnalyticsManager } from "../analytics/analyticsManager";
+import { CloudflareArtifactsManager } from "../artifacts/artifactsManager";
 import { CloudflareD1Manager } from "../d1/d1Manager";
 import { CloudflareD1Provisioner } from "../d1/d1Provisioner";
 import { CloudflareEmailRoutingManager } from "../email/emailRoutingManager";
@@ -14,6 +16,7 @@ import { CloudflareKVProvisioner } from "../kv/kvProvisioner";
 import { CloudflareImageManager } from "../media/imageManager";
 import { CloudflareStreamManager } from "../media/streamManager";
 import { CloudflareQueueManager } from "../queue/queueManager";
+import { CloudflareQueueProvisioner } from "../queue/queueProvisioner";
 import type { R2Credentials } from "../r2/r2Credentials";
 import { CloudflareR2Manager } from "../r2/r2Manager";
 import { CloudflareR2Provisioner } from "../r2/r2Provisioner";
@@ -35,7 +38,7 @@ import type { CloudflareManagerConfig } from "./manager";
  *
  * Resource-scoped managers (KV, D1, queues, Vectorize indexes, secret stores, hostname zones, R2
  * buckets) are keyed by their resource id, so repeated calls for the same id return one shared
- * instance. Account-scoped managers (AI, Images, Stream, Workers, Builds, Turnstile) are singletons.
+ * instance. Account-scoped managers (AI, Images, Stream, Analytics, Workers, Builds, Turnstile) are singletons.
  */
 export class CloudflareClients {
   private readonly config: CloudflareManagerConfig;
@@ -62,6 +65,8 @@ export class CloudflareClients {
 
   private streamManager?: CloudflareStreamManager;
 
+  private analyticsManager?: CloudflareAnalyticsManager;
+
   private workersManager?: CloudflareWorkersManager;
 
   private buildsManager?: CloudflareBuildsManager;
@@ -81,6 +86,10 @@ export class CloudflareClients {
 
   private r2ProvisionerManager?: CloudflareR2Provisioner;
 
+  private queueProvisionerManager?: CloudflareQueueProvisioner;
+
+  private artifactsManager?: CloudflareArtifactsManager;
+
   private vectorizeProvisionerManager?: CloudflareVectorizeProvisioner;
 
   constructor(config: CloudflareManagerConfig) {
@@ -167,6 +176,12 @@ export class CloudflareClients {
     return this.streamManager;
   }
 
+  /** The account-scoped GraphQL Analytics manager. */
+  analytics(): CloudflareAnalyticsManager {
+    this.analyticsManager ??= new CloudflareAnalyticsManager(this.config);
+    return this.analyticsManager;
+  }
+
   /** The account-scoped Workers (scripts/deployments) manager. */
   workers(): CloudflareWorkersManager {
     this.workersManager ??= new CloudflareWorkersManager(this.config);
@@ -209,6 +224,18 @@ export class CloudflareClients {
     return this.r2ProvisionerManager;
   }
 
+  /** The account-scoped Queues control plane — create, find, and delete queues. */
+  queueProvisioner(): CloudflareQueueProvisioner {
+    this.queueProvisionerManager ??= new CloudflareQueueProvisioner(this.config);
+    return this.queueProvisionerManager;
+  }
+
+  /** The account-scoped Artifacts control plane — list and delete the repos in a namespace (#673). */
+  artifacts(): CloudflareArtifactsManager {
+    this.artifactsManager ??= new CloudflareArtifactsManager(this.config);
+    return this.artifactsManager;
+  }
+
   /** The account-scoped Vectorize control plane — create, find, list, and delete indexes and their metadata indexes. */
   vectorizeProvisioner(): CloudflareVectorizeProvisioner {
     this.vectorizeProvisionerManager ??= new CloudflareVectorizeProvisioner(this.config);

package/src/media/imageManager.ts

@@ -8,7 +8,8 @@ import type {
   DirectUploadCreateResponse,
 } from "cloudflare/resources/images/v2/direct-uploads";
 import type { V2ListParams } from "cloudflare/resources/images/v2/v2";
-import { cloudflareRequest } from "../client/errors";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
 import { CloudflareManager } from "../client/manager";
 
 /**
@@ -29,6 +30,59 @@ function encodeMetadata(metadata: unknown): unknown {
   return metadata === undefined || metadata === null ? metadata : JSON.stringify(metadata);
 }
 
+/** One of the account's Images URL-signing keys. The value is the HMAC secret signed URLs are minted with. */
+export const ImagesSigningKey = z
+  .object({
+    name: z.string().min(1).describe("The key's name. Cloudflare provisions one named `default`."),
+    value: z.string().min(1).describe("The key itself — the HMAC-SHA256 secret a signed delivery URL is minted with."),
+  })
+  .describe("One Cloudflare Images URL-signing key.");
+export type ImagesSigningKey = z.infer<typeof ImagesSigningKey>;
+
+const SigningKeysResponse = z
+  .object({ keys: z.array(ImagesSigningKey).optional().describe("The account's signing keys.") })
+  .describe("The Images signing-keys response.");
+
+/** One Images variant, and whether it serves an image without a signature whatever the image requires. */
+export const ImagesVariant = z
+  .object({
+    id: z.string().describe("The variant's name, as it appears in a delivery URL."),
+    neverRequireSignedURLs: z
+      .boolean()
+      .describe("Whether this variant serves every image unsigned, even one uploaded with requireSignedURLs."),
+  })
+  .describe("One Cloudflare Images variant's signing posture.");
+export type ImagesVariant = z.infer<typeof ImagesVariant>;
+
+const VariantsResponse = z
+  .object({
+    variants: z
+      .record(
+        z.string(),
+        z
+          .object({
+            id: z.string().describe("The variant name."),
+            neverRequireSignedURLs: z.boolean().optional().describe("Whether it ignores signing."),
+          })
+          .describe("One variant as the API returns it."),
+      )
+      .optional()
+      .describe("Every variant, keyed by name."),
+  })
+  .describe("The Images variants response.");
+
+/** Parse an Images response the SDK types loosely, refusing a shape we cannot read. */
+function parseResponse<T>(schema: z.ZodType<T>, response: unknown, what: string): T {
+  const result = schema.safeParse(response);
+  if (!result.success) {
+    throw new CloudflareInvalidResponseError({
+      message: `An Images ${what} response had an unexpected shape.`,
+      detail: result.error.message,
+    });
+  }
+  return result.data;
+}
+
 /**
  * Out-of-Worker Cloudflare Images access over the REST API: upload, fetch, edit, delete, list, and
  * direct-upload URLs from a CLI/CI/provisioning context. Image metadata is an arbitrary
@@ -109,6 +163,44 @@ export class CloudflareImageManager extends CloudflareManager {
     });
   }
 
+  /**
+   * The account's URL-signing keys — what a signed delivery URL for an image uploaded with
+   * `requireSignedURLs` is minted with. Cloudflare provisions a `default` key per account.
+   */
+  async signingKeys(): Promise<ImagesSigningKey[]> {
+    return cloudflareRequest("Images list signing keys", async () => {
+      const response = await this.getClient().images.v1.keys.list({ account_id: this.accountId }, requestOptions);
+      return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+    });
+  }
+
+  /** Create a named signing key, or roll it if it exists. Answers with every key the account then holds. */
+  async createSigningKey(name: string): Promise<ImagesSigningKey[]> {
+    return cloudflareRequest(`Images create signing key '${name}'`, async () => {
+      const response = await this.getClient().images.v1.keys.update(
+        name,
+        { account_id: this.accountId },
+        requestOptions,
+      );
+      return parseResponse(SigningKeysResponse, response, "signing keys").keys ?? [];
+    });
+  }
+
+  /**
+   * Every variant, with whether it serves unsigned. A variant set to `neverRequireSignedURLs` delivers a
+   * private image to anyone holding its URL, which is why media's provisioning reads this.
+   */
+  async listVariants(): Promise<ImagesVariant[]> {
+    return cloudflareRequest("Images list variants", async () => {
+      const response = await this.getClient().images.v1.variants.list({ account_id: this.accountId }, requestOptions);
+      const variants = parseResponse(VariantsResponse, response, "variants").variants ?? {};
+      return Object.values(variants).map((variant) => ({
+        id: variant.id,
+        neverRequireSignedURLs: variant.neverRequireSignedURLs === true,
+      }));
+    });
+  }
+
   getServiceType(): string {
     return "Cloudflare Images";
   }

package/src/media/streamManager.ts

@@ -68,6 +68,19 @@ function parseDownloadStatus(response: unknown): StreamDownloadStatus {
   return result.data;
 }
 
+/**
+ * A Stream signing key: what a signed playback token for a video uploaded with `requireSignedURLs` is
+ * signed with. The JWK is base64 of the key's JSON, as Cloudflare returns it — a single line, so it is
+ * the form stored, where the PEM is not.
+ */
+export const StreamSigningKey = z
+  .object({
+    id: z.string().min(1).describe("The key id — the `kid` a signed token names."),
+    jwk: z.string().min(1).describe("The RSA private key as base64-encoded JWK, as Cloudflare returns it."),
+  })
+  .describe("One Cloudflare Stream signing key.");
+export type StreamSigningKey = z.infer<typeof StreamSigningKey>;
+
 /**
  * Out-of-Worker Cloudflare Stream access over the REST API: delete, fetch, edit, direct uploads,
  * and download (MP4 + audio-only) management from a CLI/CI/provisioning context. Video metadata is
@@ -182,6 +195,27 @@ export class CloudflareStreamManager extends CloudflareManager {
     );
   }
 
+  /**
+   * Create a signing key. Cloudflare returns the private half once, on creation, and never again — so the
+   * caller stores it, and a lost key is replaced by creating another.
+   */
+  async createSigningKey(): Promise<StreamSigningKey> {
+    return cloudflareRequest("Stream create signing key", async () => {
+      const response = await this.getClient().stream.keys.create(
+        { account_id: this.accountId, body: {} },
+        requestOptions,
+      );
+      const parsed = StreamSigningKey.safeParse(response);
+      if (!parsed.success) {
+        throw new CloudflareInvalidResponseError({
+          message: "A Stream signing-key response had an unexpected shape.",
+          detail: parsed.error.message,
+        });
+      }
+      return parsed.data;
+    });
+  }
+
   getServiceType(): string {
     return "Cloudflare Stream";
   }

package/src/oauth/scopes.ts

@@ -10,8 +10,8 @@ import { oauthScopesFor } from "../tokens/permissions";
  *   the person who signed in.
  * - `offline_access` — the only way Cloudflare issues a refresh token. Without it a session dies at the
  *   hour and every command after it opens a browser (measured 2026-10-15).
- * - `account-api-tokens.write` — the mint. A session mints `ci-system` and every worker-consumer token
- *   the project declares, so the hand-made bootstrap token stops being a setup step.
+ * - `account-api-tokens.write` — the mint. A session mints `ci-system` and `runtime` as the project
+ *   composes them, so the hand-made bootstrap token stops being a setup step.
  * - `account-settings.read` — `GET /accounts`, so the account is discovered rather than stored. On its own
  *   it lists the account; `d1.write` alone listed nothing (both measured 2026-10-15), so discovery must not
  *   lean on whichever other scope a project happens to request.

package/src/queue/queueProvisioner.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse, isNotFoundError } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** A queue's identity, decoded from the Queues API's `queue_id` and `queue_name`. */
+export const QueueInfo = z
+  .object({
+    id: z.string().describe("The CF-assigned queue id, which the REST API addresses a queue by."),
+    name: z.string().describe("The queue name a producer binding names it by."),
+  })
+  .describe("A Cloudflare Queue's identity, as the Queues API returns it.");
+export type QueueInfo = z.output<typeof QueueInfo>;
+
+/** The Queues API's own spelling of a queue's identity, mapped onto {@link QueueInfo}. */
+const QueueRecord = z
+  .object({
+    queue_id: z.string().describe("The CF-assigned queue id."),
+    queue_name: z.string().describe("The queue name."),
+  })
+  .transform(({ queue_id, queue_name }) => ({ id: queue_id, name: queue_name }))
+  .describe("A queue as the Queues API returns it.");
+
+/**
+ * Account-level Queues control plane: **find, create and delete queues** (#662).
+ *
+ * `pithy provision` creates the queue behind every `queue` binding a composition declares, and `pithy feature
+ * destroy` deletes a feature's. A `queues.producers` entry names a queue, and `wrangler deploy` refuses one that
+ * does not exist, so the entry is only honest because this stands the queue up. Addressed by account — unlike
+ * {@link CloudflareQueueManager}, which targets one queue to send into.
+ */
+export class CloudflareQueueProvisioner extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Queues (control plane)";
+  }
+
+  /** Prove access by listing queues — a read, never a create or a delete. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().queues.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Find a queue by exact name in the account, or `null` — for idempotent provisioning. */
+  async findQueueByName(name: string): Promise<QueueInfo | null> {
+    return cloudflareRequest(`find queue ${name}`, async () => {
+      for await (const queue of this.getClient().queues.list({ account_id: this.accountId })) {
+        const parsed = QueueRecord.safeParse(queue);
+        if (parsed.success && parsed.data.name === name) return parsed.data;
+      }
+      return null;
+    });
+  }
+
+  /** Create a queue by name; returns its id and name. */
+  async createQueue(name: string): Promise<QueueInfo> {
+    const response = await cloudflareRequest(`create queue ${name}`, () =>
+      this.getClient().queues.create({ account_id: this.accountId, queue_name: name }),
+    );
+    return decodeResponse(QueueRecord, response, "queue create");
+  }
+
+  /** Delete a queue by id. Idempotent — a missing queue is not an error, so teardown can re-run safely. */
+  async deleteQueue(queueId: string): Promise<void> {
+    await cloudflareRequest(`delete queue ${queueId}`, async () => {
+      try {
+        await this.getClient().queues.delete(queueId, { account_id: this.accountId });
+      } catch (error) {
+        if (isNotFoundError(error)) return;
+        throw error;
+      }
+    });
+  }
+}

package/src/r2/r2Manager.ts

@@ -33,11 +33,29 @@ const LIST_PARTS_PAGE_SIZE = 1000;
  * the bucket it targets. R2 signs presigned URLs with the S3 keys, not the CF API token — both
  * come from config (no environment coupling).
  */
-export interface R2ManagerConfig extends CloudflareManagerConfig, R2Credentials {
+export interface R2ManagerConfig extends Omit<CloudflareManagerConfig, "apiToken">, R2Credentials {
   /** The R2 bucket all object operations target. */
   bucketName: string;
+  /**
+   * A Cloudflare API token, for the one call here that is not S3: {@link CloudflareR2Manager.validateServiceAccess}.
+   *
+   * **Absent in a Worker (#728).** Every object operation is S3, signed with the key pair, so a Worker's
+   * object store holds no API token: the application's one is `runtime`, and R2 needs none of it. Without
+   * one, `validateServiceAccess` answers `false` and nothing calls the Cloudflare API. An empty string is
+   * still refused, because that is an unresolved value rather than a decision.
+   */
+  apiToken?: string;
 }
 
+/**
+ * What the base client is built with when the config carries no API token. Never sent: {@link noApiToken}
+ * is the provider, and the base reads the token through it at every call and refuses an empty one.
+ */
+const S3_ONLY = "r2-s3-only";
+
+/** The token provider of an S3-only manager: no token, so any Cloudflare API call is refused before it is sent. */
+const noApiToken = (): string => "";
+
 /** How long a presigned URL stays valid. Shared by every presign method so the option reads the same. */
 export interface PresignOptions {
   /** Lifetime in seconds. Defaults to one hour — long enough for a large upload, short enough to leak little. */
@@ -168,8 +186,15 @@ export class CloudflareR2Manager extends CloudflareManager {
 
   private s3Client: S3Client | null = null;
 
+  private readonly s3Only: boolean;
+
   constructor(config: R2ManagerConfig) {
-    super(config);
+    super(
+      config.apiToken === undefined
+        ? { ...config, apiToken: S3_ONLY, tokenProvider: noApiToken }
+        : { ...config, apiToken: config.apiToken },
+    );
+    this.s3Only = config.apiToken === undefined;
     if (!config.bucketName) {
       throw new CloudflareNotConfiguredError({ detail: "Missing bucketName for R2 access." });
     }
@@ -538,6 +563,8 @@ export class CloudflareR2Manager extends CloudflareManager {
    * not merely that an S3 client could be built. Never throws.
    */
   async validateServiceAccess(): Promise<boolean> {
+    // An S3-only manager holds no API token to read the bucket record with.
+    if (this.s3Only) return false;
     try {
       await this.getClient().r2.buckets.get(this.bucketName, { account_id: this.accountId });
       return true;

package/src/tokens/accountTokensManager.ts

@@ -185,6 +185,18 @@ export const AccountTokenSummary = z
       .describe(
         "The token's access policies, when the list response carries them. **A live token's own scope is the record of how it was minted** — it is how a `ci-system` token minted before zone-scoped routes (#651) can be told from one minted after, without reading the token record (which needs a grant these least-privilege tokens deliberately lack). Absent and empty are different facts: a response that says nothing means the scope could not be read, never that the token has none.",
       ),
+    // **Not `nullAsAbsent`, and that is the field.** Everywhere else a `null` means the response did not say;
+    // here it is Cloudflare's answer — nothing has ever authenticated with this token. Absent stays "did
+    // not say", and a shape this does not model degrades to absent rather than dropping the token, for the
+    // reason `policies` gives.
+    last_used_on: z
+      .string()
+      .nullable()
+      .optional()
+      .catch(undefined)
+      .describe(
+        "When something last authenticated with the token, as Cloudflare measures it against the live account. Read because `pithy token forget` acts on it (#762): `null` means never, so a local copy may be its only one. Absent means the response did not say, which is not a claim either way.",
+      ),
   })
   .describe("An existing account-owned API token's metadata (never its secret value).");
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;

package/src/tokens/permissions.ts

@@ -51,6 +51,28 @@ export const PERMISSION_GROUPS = {
   // 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. */
@@ -89,6 +111,11 @@ export const OAUTH_SCOPES = {
   "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[]>;
 
 /**

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 } : {}),
+  };
 }
 
 /**