@pithy-sh/cloudflare 0.5.0 → 0.7.0

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

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";