@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/tokens/accountTokensManager.d.ts

@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+import { CfTokenVerification } from "../user/userManager";
+/**
+ * One access policy to attach to a minted token: a set of permission groups (named, resolved to ids
+ * at mint time) and the resources they apply to. This is the reusable unit — every use case that
+ * needs a scoped CF token (the secrets manager is the first) describes itself as a list of these,
+ * and the manager turns names into the CF policy shape. `effect` defaults to `allow`.
+ */
+export interface TokenPermission {
+    /** Permission-group names to grant, resolved to ids against the live account list (e.g. "Secrets Store Read"). */
+    permissionGroupNames: string[];
+    /** The resource scope the groups apply to (e.g. `{ "com.cloudflare.api.account.<id>": "*" }`). */
+    resources: Record<string, string>;
+    /** Allow or deny the groups against the resources. Defaults to `allow`. */
+    effect?: "allow" | "deny";
+}
+/**
+ * The whole-account resource scope for a token policy: `{ "com.cloudflare.api.account.<id>": "*" }`.
+ * Account-level permission groups (Secrets Store, D1, Workers, …) scope to this. One helper so the
+ * exact resource key format lives in a single place instead of being hand-spelled per use case.
+ */
+export declare function accountResource(accountId: string): Record<string, string>;
+/**
+ * A permission group available to account-owned tokens, as returned by the permission-groups list.
+ * Only the id and name matter for resolution — the manager maps a requested name to its id.
+ */
+export declare const CfPermissionGroup: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type CfPermissionGroup = z.output<typeof CfPermissionGroup>;
+/**
+ * A freshly minted account-owned token. The `value` is the secret bearer credential — present **only**
+ * in the create response, never re-readable — so it is captured here and must be stored at once
+ * (e.g. into the Secrets Store). Never log it.
+ */
+export declare const MintedAccountToken: z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+        expired: "expired";
+    }>>;
+}, z.core.$strip>;
+export type MintedAccountToken = z.output<typeof MintedAccountToken>;
+/**
+ * An existing account-owned token's metadata, as returned by list/get. No `value` — Cloudflare never
+ * returns a token's secret after creation — so this is only enough to find a token by name and
+ * address it for deletion.
+ */
+export declare const AccountTokenSummary: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+        expired: "expired";
+    }>>;
+}, z.core.$strip>;
+export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
+/**
+ * Out-of-Worker control plane for **account-owned** Cloudflare API tokens: mint scoped, least-privilege
+ * tokens, find them by name, and delete them. Account-owned (not user-bound) by design — CLAUDE.md
+ * prefers org-level tokens that outlive any one person.
+ *
+ * This is the reusable seam behind every "pithy mints its own scoped token" case. A caller hands it a
+ * token name and a set of {@link TokenPermission}s (permission-group names + resource scope); the
+ * manager resolves the names to ids against the live account list and creates the token. The secrets
+ * manager's runtime credential is the first concrete use; more follow without touching this class.
+ */
+export declare class CloudflareAccountTokensManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by listing permission groups — a read, never a token create/delete. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /**
+     * Verify the **calling** token against this account — `GET /accounts/{id}/tokens/verify`.
+     *
+     * Distinct from {@link CloudflareUserManager.verifyToken}, which hits the *user*-scoped
+     * `/user/tokens/verify` and returns `Invalid API Token` for an account-owned (`cfat_*`) credential.
+     * Since `CLAUDE.md` prefers account-owned tokens over user-bound ones, the user endpoint is the wrong
+     * one for the common case, and using it reports a working token as invalid.
+     */
+    verifyToken(): Promise<CfTokenVerification>;
+    /**
+     * The name of an account-owned token by id, or `null` — `GET /accounts/{id}/tokens/{token_id}`.
+     *
+     * Distinct from {@link CloudflareUserManager.getTokenName}, which hits `GET /user/tokens/:id` and
+     * answers `9109 — Valid user-level authentication not found` for a `cfat_*` caller. Both halves of
+     * the account-token identity read — verify and name — are account-scoped, or neither is.
+     *
+     * **Best effort, by contract.** Reading a token record needs `API Tokens Read`, which the
+     * least-privilege tokens {@link mintToken} produces deliberately do not carry: a 403 is the normal
+     * answer for a CI credential asking its own name, not a fault. So a denied read returns `null` and
+     * the caller falls back to the token id from {@link verifyToken} — which any account token can call
+     * with no permission at all. Every other failure still throws.
+     */
+    getTokenName(tokenId: string): Promise<string | null>;
+    /** Every permission group available to account-owned tokens in this account (SDK auto-paginates). */
+    listPermissionGroups(): Promise<CfPermissionGroup[]>;
+    /**
+     * Resolve permission-group names to their `{ id }` references against the account's live group list.
+     * Throws a clear, actionable error naming any name that does not exist, or any name that is
+     * **ambiguous** — Cloudflare reuses display names across resource scopes (e.g. account vs zone), so a
+     * name that maps to more than one id can't be resolved without picking the wrong scope. Either way a
+     * typo'd or ambiguous group fails loudly at mint time, never silently widening or narrowing scope.
+     */
+    resolvePermissionGroups(names: string[]): Promise<Array<{
+        id: string;
+    }>>;
+    /**
+     * Mint a new account-owned token named `name` carrying `permissions`. Resolves every permission
+     * group name to its id (one group-list fetch for all policies), builds the CF policy set, and
+     * creates the token. Returns the token's one-time secret `value` — store it immediately. A 403 (the
+     * calling token cannot create tokens) is reraised as an actionable "grant 'Account API Tokens
+     * Write'" error so the cause is obvious; this doubles as the fail-fast preflight when provisioning
+     * runs the mint first.
+     */
+    mintToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+    /**
+     * Resolve names against a prefetched name→ids index, throwing on any unknown or ambiguous name.
+     * The shared core of {@link resolvePermissionGroups} and {@link mintToken}: take the group list once,
+     * resolve every name against it. Ambiguity (a name with more than one id) is a hard error, not a
+     * silent pick — see {@link resolvePermissionGroups}.
+     */
+    private resolveAgainstIndex;
+    /** Every account-owned token's metadata (SDK auto-paginates). No secret values — list is metadata only. */
+    listTokens(): Promise<AccountTokenSummary[]>;
+    /** Find an account token by exact name, or `null` — for idempotent re-mint (SDK auto-paginates). */
+    findTokenByName(name: string): Promise<AccountTokenSummary | null>;
+    /** Delete an account token by id. */
+    deleteToken(tokenId: string): Promise<void>;
+    /**
+     * Delete every account token with the given name; returns how many were removed. Names are not
+     * unique in Cloudflare, so any duplicates (e.g. a prior interrupted run) are swept here. A no-op
+     * when none match. Used by teardown.
+     */
+    deleteTokensByName(name: string): Promise<number>;
+    /**
+     * Roll an existing token's secret: regenerate its value **in place**, keeping the same token id,
+     * name, and policies (the dashboard's "Roll" action). Returns the new secret value — the only time
+     * Cloudflare hands it back — so it must be stored at once. The seam the deferred value-rotation
+     * builds on: a credential self-rolls without ever changing identity.
+     */
+    rollTokenValue(tokenId: string): Promise<string>;
+    /**
+     * Ensure a named token exists and return a **fresh** secret for it. If a token of this name already
+     * exists, roll its value in place (same id and policies, new secret); otherwise mint a new one.
+     * Either way the caller gets a usable secret to store — the idempotent path for a credential that
+     * lives in the Secrets Store, since Cloudflare never returns a token's existing secret. Mirrors the
+     * dashboard's roll-or-create.
+     */
+    rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
+}
+//# sourceMappingURL=accountTokensManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accountTokensManager.d.ts","sourceRoot":"","sources":["../../src/tokens/accountTokensManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kHAAkH;IAClH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzE;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;iBAK8E,CAAC;AAC7G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAO6D,CAAC;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;iBAMuD,CAAC;AACxF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,cAAc,IAAI,MAAM,CAEvB;IAED,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAKhD;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1D;IAED,qGAAqG;IAC/F,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAWzD;IAED;;;;;;OAMG;IACG,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAE7E;IAED;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2BzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,2GAA2G;IACrG,UAAU,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CASjD;IAED,oGAAoG;IAC9F,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAQvE;IAED,qCAAqC;IAC/B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhD;IAED;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtD;IAED;;;;;OAKG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrD;IAED;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAKzF;CACF"}

package/dist/tokens/accountTokensManager.js

@@ -0,0 +1,282 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError, CloudflareRequestError, cloudflareRequest, decodeResponse, isAuthorizationError, messageOf } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { CfTokenVerification } from "../user/userManager.js";
+import { z } from "zod";
+//#region src/tokens/accountTokensManager.ts
+/**
+* The whole-account resource scope for a token policy: `{ "com.cloudflare.api.account.<id>": "*" }`.
+* Account-level permission groups (Secrets Store, D1, Workers, …) scope to this. One helper so the
+* exact resource key format lives in a single place instead of being hand-spelled per use case.
+*/
+function accountResource(accountId) {
+	return { [`com.cloudflare.api.account.${accountId}`]: "*" };
+}
+/**
+* A permission group available to account-owned tokens, as returned by the permission-groups list.
+* Only the id and name matter for resolution — the manager maps a requested name to its id.
+*/
+const CfPermissionGroup = z.object({
+	id: z.string().describe("The CF-assigned permission-group id, referenced in a token policy."),
+	name: z.string().describe("The human-readable permission-group name (e.g. 'Secrets Store Read').")
+}).describe("A Cloudflare account-token permission group: the id a policy references and its display name.");
+/**
+* A freshly minted account-owned token. The `value` is the secret bearer credential — present **only**
+* in the create response, never re-readable — so it is captured here and must be stored at once
+* (e.g. into the Secrets Store). Never log it.
+*/
+const MintedAccountToken = z.object({
+	id: z.string().describe("The CF-assigned token id, used to address the token for get/delete."),
+	value: z.string().describe("The secret token value — returned once on create, never again. Store immediately."),
+	name: z.string().optional().describe("The token name as registered with Cloudflare."),
+	status: z.enum([
+		"active",
+		"disabled",
+		"expired"
+	]).optional().describe("The token's lifecycle status.")
+}).describe("A newly created account-owned API token, including its one-time secret value.");
+/**
+* An existing account-owned token's metadata, as returned by list/get. No `value` — Cloudflare never
+* returns a token's secret after creation — so this is only enough to find a token by name and
+* address it for deletion.
+*/
+const AccountTokenSummary = z.object({
+	id: z.string().describe("The CF-assigned token id, used to address the token for deletion."),
+	name: z.string().describe("The token name, the key callers match on for idempotent re-mint."),
+	status: z.enum([
+		"active",
+		"disabled",
+		"expired"
+	]).optional().describe("The token's lifecycle status.")
+}).describe("An existing account-owned API token's metadata (never its secret value).");
+/**
+* Out-of-Worker control plane for **account-owned** Cloudflare API tokens: mint scoped, least-privilege
+* tokens, find them by name, and delete them. Account-owned (not user-bound) by design — CLAUDE.md
+* prefers org-level tokens that outlive any one person.
+*
+* This is the reusable seam behind every "pithy mints its own scoped token" case. A caller hands it a
+* token name and a set of {@link TokenPermission}s (permission-group names + resource scope); the
+* manager resolves the names to ids against the live account list and creates the token. The secrets
+* manager's runtime credential is the first concrete use; more follow without touching this class.
+*/
+var CloudflareAccountTokensManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare Account API Tokens";
+	}
+	/** Prove access by listing permission groups — a read, never a token create/delete. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.listPermissionGroups();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Verify the **calling** token against this account — `GET /accounts/{id}/tokens/verify`.
+	*
+	* Distinct from {@link CloudflareUserManager.verifyToken}, which hits the *user*-scoped
+	* `/user/tokens/verify` and returns `Invalid API Token` for an account-owned (`cfat_*`) credential.
+	* Since `CLAUDE.md` prefers account-owned tokens over user-bound ones, the user endpoint is the wrong
+	* one for the common case, and using it reports a working token as invalid.
+	*/
+	async verifyToken() {
+		const raw = await cloudflareRequest("verify account token", () => this.getClient().accounts.tokens.verify({ account_id: this.accountId }));
+		return decodeResponse(CfTokenVerification, raw, "account token verify");
+	}
+	/**
+	* The name of an account-owned token by id, or `null` — `GET /accounts/{id}/tokens/{token_id}`.
+	*
+	* Distinct from {@link CloudflareUserManager.getTokenName}, which hits `GET /user/tokens/:id` and
+	* answers `9109 — Valid user-level authentication not found` for a `cfat_*` caller. Both halves of
+	* the account-token identity read — verify and name — are account-scoped, or neither is.
+	*
+	* **Best effort, by contract.** Reading a token record needs `API Tokens Read`, which the
+	* least-privilege tokens {@link mintToken} produces deliberately do not carry: a 403 is the normal
+	* answer for a CI credential asking its own name, not a fault. So a denied read returns `null` and
+	* the caller falls back to the token id from {@link verifyToken} — which any account token can call
+	* with no permission at all. Every other failure still throws.
+	*/
+	async getTokenName(tokenId) {
+		const raw = await cloudflareRequest(`get account token ${tokenId}`, async () => {
+			try {
+				return await this.getClient().accounts.tokens.get(tokenId, { account_id: this.accountId });
+			} catch (error) {
+				if (isAuthorizationError(error)) return null;
+				throw error;
+			}
+		});
+		const parsed = TokenName.safeParse(raw);
+		return parsed.success ? parsed.data.name : null;
+	}
+	/** Every permission group available to account-owned tokens in this account (SDK auto-paginates). */
+	async listPermissionGroups() {
+		return cloudflareRequest("list account token permission groups", async () => {
+			const out = [];
+			for await (const group of this.getClient().accounts.tokens.permissionGroups.list({ account_id: this.accountId })) {
+				const parsed = CfPermissionGroup.safeParse(group);
+				if (parsed.success) out.push(parsed.data);
+			}
+			return out;
+		});
+	}
+	/**
+	* Resolve permission-group names to their `{ id }` references against the account's live group list.
+	* Throws a clear, actionable error naming any name that does not exist, or any name that is
+	* **ambiguous** — Cloudflare reuses display names across resource scopes (e.g. account vs zone), so a
+	* name that maps to more than one id can't be resolved without picking the wrong scope. Either way a
+	* typo'd or ambiguous group fails loudly at mint time, never silently widening or narrowing scope.
+	*/
+	async resolvePermissionGroups(names) {
+		return this.resolveAgainstIndex(indexByName(await this.listPermissionGroups()), names);
+	}
+	/**
+	* Mint a new account-owned token named `name` carrying `permissions`. Resolves every permission
+	* group name to its id (one group-list fetch for all policies), builds the CF policy set, and
+	* creates the token. Returns the token's one-time secret `value` — store it immediately. A 403 (the
+	* calling token cannot create tokens) is reraised as an actionable "grant 'Account API Tokens
+	* Write'" error so the cause is obvious; this doubles as the fail-fast preflight when provisioning
+	* runs the mint first.
+	*/
+	async mintToken(name, permissions) {
+		const index = indexByName(await this.listPermissionGroups());
+		const policies = permissions.map((permission) => ({
+			effect: permission.effect ?? "allow",
+			permission_groups: this.resolveAgainstIndex(index, permission.permissionGroupNames),
+			resources: permission.resources
+		}));
+		let raw;
+		try {
+			raw = await this.getClient().accounts.tokens.create({
+				account_id: this.accountId,
+				name,
+				policies
+			});
+		} catch (error) {
+			if (isAuthorizationError(error)) throw new CloudflareNotConfiguredError({
+				message: "The Cloudflare API token is not allowed to create account tokens.",
+				action: "Grant it 'Account API Tokens Write' (Account → API Tokens → Edit), then re-run.",
+				detail: `mint account token '${name}': ${messageOf(error)}`
+			}, { cause: error });
+			throw new CloudflareRequestError({
+				message: `Failed to mint account token '${name}'.`,
+				detail: messageOf(error)
+			}, { cause: error });
+		}
+		return decodeResponse(MintedAccountToken, raw, "account token create");
+	}
+	/**
+	* Resolve names against a prefetched name→ids index, throwing on any unknown or ambiguous name.
+	* The shared core of {@link resolvePermissionGroups} and {@link mintToken}: take the group list once,
+	* resolve every name against it. Ambiguity (a name with more than one id) is a hard error, not a
+	* silent pick — see {@link resolvePermissionGroups}.
+	*/
+	resolveAgainstIndex(index, names) {
+		const unknown = names.filter((name) => !index.has(name));
+		if (unknown.length > 0) throw new CloudflareNotConfiguredError({
+			message: `Unknown Cloudflare permission group(s): ${unknown.join(", ")}.`,
+			action: "Check the exact permission-group names against the account's available groups.",
+			detail: `resolve permission groups: not found in account ${this.accountId} — ${unknown.join(", ")}`
+		});
+		const ambiguous = names.filter((name) => (index.get(name)?.length ?? 0) > 1);
+		if (ambiguous.length > 0) throw new CloudflareNotConfiguredError({
+			message: `Ambiguous Cloudflare permission group(s): ${ambiguous.join(", ")}.`,
+			action: "These names map to more than one permission group; scope the token by a unique group name.",
+			detail: `resolve permission groups: name maps to multiple ids in account ${this.accountId} — ${ambiguous.join(", ")}`
+		});
+		return names.map((name) => ({ id: index.get(name)[0] }));
+	}
+	/** Every account-owned token's metadata (SDK auto-paginates). No secret values — list is metadata only. */
+	async listTokens() {
+		return cloudflareRequest("list account tokens", async () => {
+			const out = [];
+			for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+				const parsed = AccountTokenSummary.safeParse(token);
+				if (parsed.success) out.push(parsed.data);
+			}
+			return out;
+		});
+	}
+	/** Find an account token by exact name, or `null` — for idempotent re-mint (SDK auto-paginates). */
+	async findTokenByName(name) {
+		return cloudflareRequest(`find account token ${name}`, async () => {
+			for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+				const parsed = AccountTokenSummary.safeParse(token);
+				if (parsed.success && parsed.data.name === name) return parsed.data;
+			}
+			return null;
+		});
+	}
+	/** Delete an account token by id. */
+	async deleteToken(tokenId) {
+		await cloudflareRequest(`delete account token ${tokenId}`, () => this.getClient().accounts.tokens.delete(tokenId, { account_id: this.accountId }));
+	}
+	/**
+	* Delete every account token with the given name; returns how many were removed. Names are not
+	* unique in Cloudflare, so any duplicates (e.g. a prior interrupted run) are swept here. A no-op
+	* when none match. Used by teardown.
+	*/
+	async deleteTokensByName(name) {
+		return cloudflareRequest(`delete account tokens named ${name}`, async () => {
+			const ids = [];
+			for await (const token of this.getClient().accounts.tokens.list({ account_id: this.accountId })) {
+				const parsed = AccountTokenSummary.safeParse(token);
+				if (parsed.success && parsed.data.name === name) ids.push(parsed.data.id);
+			}
+			for (const id of ids) await this.getClient().accounts.tokens.delete(id, { account_id: this.accountId });
+			return ids.length;
+		});
+	}
+	/**
+	* Roll an existing token's secret: regenerate its value **in place**, keeping the same token id,
+	* name, and policies (the dashboard's "Roll" action). Returns the new secret value — the only time
+	* Cloudflare hands it back — so it must be stored at once. The seam the deferred value-rotation
+	* builds on: a credential self-rolls without ever changing identity.
+	*/
+	async rollTokenValue(tokenId) {
+		const raw = await cloudflareRequest(`roll account token value ${tokenId}`, () => this.getClient().accounts.tokens.value.update(tokenId, {
+			account_id: this.accountId,
+			body: {}
+		}));
+		return decodeResponse(RolledTokenValue, raw, "account token value roll");
+	}
+	/**
+	* Ensure a named token exists and return a **fresh** secret for it. If a token of this name already
+	* exists, roll its value in place (same id and policies, new secret); otherwise mint a new one.
+	* Either way the caller gets a usable secret to store — the idempotent path for a credential that
+	* lives in the Secrets Store, since Cloudflare never returns a token's existing secret. Mirrors the
+	* dashboard's roll-or-create.
+	*/
+	async rollToken(name, permissions) {
+		const existing = await this.findTokenByName(name);
+		if (!existing) return this.mintToken(name, permissions);
+		const value = await this.rollTokenValue(existing.id);
+		return {
+			id: existing.id,
+			value,
+			name: existing.name,
+			status: existing.status
+		};
+	}
+};
+/** The rolled secret value Cloudflare returns from a value-roll — a non-empty bearer string. */
+const RolledTokenValue = z.string().min(1);
+/** Just the token's name, the piece the account-token actor path needs. */
+const TokenName = z.object({ name: z.string().describe("The token's registered name — the audit actor id for an account token.") }).describe("The one field a token-record read is narrowed to: its name.");
+/**
+* Index permission groups by display name, collecting **every** id that bears a name. A list rather
+* than one id per name on purpose: Cloudflare reuses display names across scopes, and a name with
+* more than one id is ambiguous — the resolver rejects it rather than silently pick one.
+*/
+function indexByName(groups) {
+	const index = /* @__PURE__ */ new Map();
+	for (const group of groups) {
+		const ids = index.get(group.name) ?? [];
+		ids.push(group.id);
+		index.set(group.name, ids);
+	}
+	return index;
+}
+//#endregion
+export { AccountTokenSummary, CfPermissionGroup, CloudflareAccountTokensManager, MintedAccountToken, accountResource };

package/dist/tokens/permissions.d.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The permission catalog: short, stable permission **keys** (`d1:read`) mapped to the Cloudflare
+ * account **permission-group display names** they grant (`"D1 Read"`). Token profiles are declared in
+ * these keys, so the profiles read cleanly and the CF-specific names live in one place. The names are
+ * resolved to permission-group **ids** against the live account at mint time
+ * (`CloudflareAccountTokensManager.resolvePermissionGroups`), which fails loudly on an unknown or
+ * ambiguous name — so a name that drifts from Cloudflare's catalog is caught at mint, never silently
+ * mis-scoped. Verify the exact names against the account when adding a key; an adopter can override a
+ * profile's keys if their account differs.
+ */
+export declare const PERMISSION_GROUPS: {
+    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 Rules Write"];
+    readonly "kv:write": readonly ["Workers KV Storage Write"];
+    readonly "r2:read": readonly ["Workers R2 Storage Read"];
+    readonly "r2:write": readonly ["Workers R2 Storage Write"];
+    readonly "vectorize:read": readonly ["Vectorize Read"];
+    readonly "vectorize:write": readonly ["Vectorize Write"];
+    readonly "ai:read": readonly ["Workers AI Read"];
+    readonly "zone:read": readonly ["Zone Read"];
+};
+/** A known permission key — one of {@link PERMISSION_GROUPS}'s keys. */
+export type PermissionKey = keyof typeof PERMISSION_GROUPS;
+/** Narrow an arbitrary string to a {@link PermissionKey}. */
+export declare function isPermissionKey(key: string): key is PermissionKey;
+/**
+ * Resolve permission keys to the CF permission-group display names they grant, de-duped in first-seen
+ * order. An unknown key fails with an actionable error naming the valid keys — caught at the CLI/config
+ * boundary before any CF call.
+ */
+export declare function resolvePermissionKeys(keys: string[]): string[];
+//# sourceMappingURL=permissions.d.ts.map

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

@@ -0,0 +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;CACjB,CAAC;AAEX,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE3D,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9D"}

package/dist/tokens/permissions.js

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError } from "../client/errors.js";
+//#region src/tokens/permissions.ts
+/**
+* The permission catalog: short, stable permission **keys** (`d1:read`) mapped to the Cloudflare
+* account **permission-group display names** they grant (`"D1 Read"`). Token profiles are declared in
+* these keys, so the profiles read cleanly and the CF-specific names live in one place. The names are
+* resolved to permission-group **ids** against the live account at mint time
+* (`CloudflareAccountTokensManager.resolvePermissionGroups`), which fails loudly on an unknown or
+* ambiguous name — so a name that drifts from Cloudflare's catalog is caught at mint, never silently
+* mis-scoped. Verify the exact names against the account when adding a key; an adopter can override a
+* profile's keys if their account differs.
+*/
+const PERMISSION_GROUPS = {
+	"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 Rules Write"],
+	"kv:write": ["Workers KV Storage Write"],
+	"r2:read": ["Workers R2 Storage Read"],
+	"r2:write": ["Workers R2 Storage Write"],
+	"vectorize:read": ["Vectorize Read"],
+	"vectorize:write": ["Vectorize Write"],
+	"ai:read": ["Workers AI Read"],
+	"zone:read": ["Zone Read"]
+};
+/** Narrow an arbitrary string to a {@link PermissionKey}. */
+function isPermissionKey(key) {
+	return key in PERMISSION_GROUPS;
+}
+/**
+* Resolve permission keys to the CF permission-group display names they grant, de-duped in first-seen
+* order. An unknown key fails with an actionable error naming the valid keys — caught at the CLI/config
+* boundary before any CF call.
+*/
+function resolvePermissionKeys(keys) {
+	const names = [];
+	for (const key of keys) {
+		if (!isPermissionKey(key)) throw new CloudflareNotConfiguredError({
+			message: `Unknown token permission key: ${key}.`,
+			action: `Use one of: ${Object.keys(PERMISSION_GROUPS).join(", ")}.`,
+			detail: `resolve permission keys: ${key} is not in the permission catalog`
+		});
+		for (const name of PERMISSION_GROUPS[key]) if (!names.includes(name)) names.push(name);
+	}
+	return names;
+}
+//#endregion
+export { PERMISSION_GROUPS, isPermissionKey, resolvePermissionKeys };

package/dist/tokens/profiles.d.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability, TokenProfileSeam } 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
+ *   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
+ *   the `ci-system` token: mint it here, read the value
+ *   out, and set it as CI's `CLOUDFLARE_API_TOKEN`. It wrote `.dev.vars.<env>` *inside* the project until
+ *   #182; the name stays because it is a public `--store` flag value.
+ * - `ephemeral` — nothing is written; the value is used in-process and discarded. The one-step CI
+ *   path — CI can't read the CF Secrets Store, so it mints and uses the token in the same job.
+ */
+export type TokenStore = "secrets-store" | "dev-vars" | "ephemeral";
+/** The valid stores, for validating a `--store` flag or a profile's `defaultStore`. */
+export declare const TOKEN_STORES: readonly TokenStore[];
+/** The name of the one CI system token — the single least-privilege credential a CI pipeline runs under. */
+export declare const CI_SYSTEM_PROFILE = "ci-system";
+/**
+ * A named token profile: the CF permissions a job needs (short {@link PermissionKey}s), the resource
+ * scope, the **secret** its minted value is stored under (whose registry backend is the destination),
+ * and an optional built-in store override. The consuming code is the source of truth for its access;
+ * adopters override any field per profile.
+ */
+export interface TokenProfile {
+    /** The profile's stable name — the key it is minted, listed, and revoked under. */
+    name: string;
+    /** The CF permissions the token grants, as short catalog keys (resolved to group names at mint). */
+    permissions: PermissionKey[];
+    /** The resource scope: `"account"` (the default) or an explicit CF resource map. */
+    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. */
+    permissions?: PermissionKey[];
+    /** Replace the profile's resource scope with an explicit CF resource map. */
+    resources?: Record<string, string>;
+    /** Replace where the value is written (`--store`). */
+    store?: TokenStore;
+}
+/** The env-var / secret name a profile's token is stored under: `CF_TOKEN_<PROFILE>`. */
+export declare function tokenSecretName(profile: string): string;
+/**
+ * Author a token profile: validates its permission keys against the catalog at author time, so a typo
+ * fails where the profile is declared, not deep in a mint call. Returns the profile unchanged, typed.
+ */
+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.
+ */
+export declare function resolveTokenProfiles(capabilities: readonly Capability[]): Record<string, TokenProfile>;
+/**
+ * Resolve a profile by name from the aggregated registry, applying an adopter override. An unknown
+ * name fails with an actionable error listing the known profiles.
+ */
+export declare function resolveProfile(profiles: Record<string, TokenProfile>, name: string, override?: ProfileOverride): TokenProfile;
+/** Build the account-scoped {@link TokenPermission}s for a set of permission keys — the mint input. */
+export declare function permissionsForKeys(keys: PermissionKey[], accountId: string): TokenPermission[];
+/**
+ * Turn a resolved profile into the {@link TokenPermission}s the account-tokens manager mints from: the
+ * profile's permission keys resolved to CF group names, scoped to the account (or the profile's
+ * explicit resources). One policy per profile — a token carries exactly the access its profile declares.
+ */
+export declare function profilePermissions(profile: TokenProfile, accountId: string): TokenPermission[];
+//# sourceMappingURL=profiles.d.ts.map

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

@@ -0,0 +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,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAmB,KAAK,aAAa,EAAyB,MAAM,eAAe,CAAC;AAE3F;;;;;;;;;;;;;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;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAI9F"}