@pithy-sh/cloudflare 0.1.2 → 0.1.4

package/dist/tokens/profiles.js

@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareNotConfiguredError } from "../client/errors.js";
+import { accountResource } from "./accountTokensManager.js";
+import { isPermissionKey, resolvePermissionKeys } from "./permissions.js";
+//#region src/tokens/profiles.ts
+/** The valid stores, for validating a `--store` flag or a profile's `defaultStore`. */
+const TOKEN_STORES = [
+	"secrets-store",
+	"dev-vars",
+	"ephemeral"
+];
+/** The name of the one CI system token — the single least-privilege credential a CI pipeline runs under. */
+const CI_SYSTEM_PROFILE = "ci-system";
+/**
+* The base permissions the `ci-system` token always carries: deploy Workers, run migrations against
+* remote D1, and read/write the Secrets Store (a deployed Worker binding CFSS secrets needs Secrets
+* Store access at deploy). Every composed capability's {@link Capability.ciPermissions} unions on top.
+*/
+const CI_SYSTEM_BASE = [
+	"workers:write",
+	"d1:read",
+	"d1:write",
+	"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, "_")}`;
+}
+/**
+* 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.
+*/
+function defineTokenProfile(profile) {
+	resolvePermissionKeys(profile.permissions);
+	return profile;
+}
+/** Validate a capability's declared permission keys, throwing an actionable error on any unknown one. */
+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)."
+	});
+	return keys;
+}
+/** Build the aggregating `ci-system` profile: the base permissions ∪ every capability's `ciPermissions`. */
+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);
+	return {
+		name: CI_SYSTEM_PROFILE,
+		permissions,
+		secret: tokenSecretName(CI_SYSTEM_PROFILE),
+		defaultStore: "dev-vars",
+		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(", ")}.`
+	});
+	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
+	};
+}
+/**
+* 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.
+*/
+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;
+}
+/**
+* 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.
+*/
+function resolveProfile(profiles, name, override) {
+	const base = profiles[name];
+	if (!base) throw new CloudflareNotConfiguredError({
+		message: `Unknown token profile: ${name}.`,
+		action: `Use one of: ${Object.keys(profiles).join(", ")}.`,
+		detail: `resolve token profile: ${name} is not in the registry`
+	});
+	if (!override) return base;
+	return {
+		...base,
+		permissions: override.permissions ?? base.permissions,
+		resources: override.resources ?? base.resources,
+		defaultStore: override.store ?? base.defaultStore
+	};
+}
+/** Build the account-scoped {@link TokenPermission}s for a set of permission keys — the mint input. */
+function permissionsForKeys(keys, accountId) {
+	return [{
+		permissionGroupNames: resolvePermissionKeys(keys),
+		resources: accountResource(accountId)
+	}];
+}
+/**
+* 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.
+*/
+function profilePermissions(profile, accountId) {
+	const resources = profile.resources && profile.resources !== "account" ? profile.resources : accountResource(accountId);
+	return [{
+		permissionGroupNames: resolvePermissionKeys(profile.permissions),
+		resources
+	}];
+}
+//#endregion
+export { CI_SYSTEM_PROFILE, TOKEN_STORES, defineTokenProfile, permissionsForKeys, profilePermissions, resolveProfile, resolveTokenProfiles, tokenSecretName };

package/dist/turnstile/turnstileManager.d.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Widget, WidgetListResponse } from "cloudflare/resources/turnstile/widgets";
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * The two widget modes Pithy provisions. `managed` is Cloudflare's *visible* managed widget (CF decides
+ * whether to show interaction) — used where a challenge should be seen (a login page). `invisible` runs
+ * silently — used where a form should not interrupt (a lead capture). One of each per domain, max.
+ */
+export type TurnstileWidgetMode = "managed" | "invisible";
+/**
+ * The server-side response from Turnstile's `/siteverify` endpoint. Pithy validates the raw JSON
+ * through this object before trusting it — a humanity check is a security boundary (CLAUDE.md §HTTP:
+ * Turnstile is composable middleware). `challenge_ts` is an ISO-8601 string on the wire, decoded to
+ * a `Date` via the `JsonDate` codec.
+ */
+export declare const TurnstileVerification: z.ZodObject<{
+    success: z.ZodBoolean;
+    "error-codes": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    challenge_ts: z.ZodOptional<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+    hostname: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    cdata: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TurnstileVerification = z.output<typeof TurnstileVerification>;
+/** Options for a server-side `verify` call. */
+export interface TurnstileVerifyOptions {
+    /** The end-user IP the token was issued to, for an extra integrity check. */
+    remoteIp?: string;
+    /** The expected action label, asserted by Cloudflare against the token. */
+    action?: string;
+}
+/**
+ * Out-of-Worker Turnstile access over the REST API: server-side token verification against
+ * `/siteverify`, plus widget management (create/list/update/rotate/delete) via the SDK. Inside a
+ * Worker the same siteverify call works over `fetch`; this manager is the CLI/CI/provisioning
+ * counterpart, addressed by account.
+ */
+export declare class CloudflareTurnstileManager extends CloudflareManager {
+    /**
+     * Verify a Turnstile token server-side against `/siteverify`. The secret is the widget's secret
+     * key (never the sitekey). The raw response is validated through `TurnstileVerification`; a
+     * malformed body throws `cloudflare/invalid_response`, a network failure is wrapped as
+     * `cloudflare/request_failed`.
+     */
+    verify(token: string, secret: string, options?: TurnstileVerifyOptions): Promise<TurnstileVerification>;
+    /** Find a widget by name. Returns null when no widget matches; never throws on a missing match. */
+    getTurnstile(name: string): Promise<WidgetListResponse | null>;
+    /**
+     * Every widget claiming `domain`, matched case-insensitively (hostnames are). The sibling of
+     * {@link getTurnstile}, keyed on the domain instead of the name — and **plural**, deliberately:
+     * Cloudflare's widget names are not unique and a domain may legitimately appear on several widgets,
+     * so returning one would hide the rest from a caller deciding whether the domain is free.
+     *
+     * Exact hostname equality only. Cloudflare treats a widget's domain as covering its subdomains, but
+     * this is the input to a *refusal*, and a refusal inferred from a subdomain relationship would block
+     * `app.example.com` because someone once made a widget for `example.com`.
+     */
+    listTurnstilesByDomain(domain: string): Promise<WidgetListResponse[]>;
+    /**
+     * Create a widget for the given domains in the requested mode — `managed` (visible) or `invisible`
+     * (silent). Defaults to `invisible` so existing callers keep their behavior.
+     */
+    addTurnstile(name: string, domains: string[], mode?: TurnstileWidgetMode): Promise<Widget>;
+    /** Delete a widget by its sitekey. */
+    deleteTurnstile(siteKey: string): Promise<void>;
+    /** Replace the allowed domains on an existing widget (kept in invisible mode). */
+    updateTurnstileDomains(siteKey: string, domains: string[], name: string): Promise<Widget>;
+    /** Rotate a widget's secret key, invalidating the old secret immediately. */
+    rotateTurnstile(siteKey: string): Promise<Widget>;
+    getServiceType(): string;
+    /** Prove access by listing widgets. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+}
+//# sourceMappingURL=turnstileManager.d.ts.map

package/dist/turnstile/turnstileManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstileManager.d.ts","sourceRoot":"","sources":["../../src/turnstile/turnstileManager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AACzF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQtD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;iBAUsD,CAAC;AACzF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,iBAAiB;IAC/D;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA4B5G;IAED,mGAAmG;IAC7F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOnE;IAED;;;;;;;;;OASG;IACG,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAS1E;IAED;;;OAGG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,mBAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5G;IAED,sCAAsC;IAChC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpD;IAED,kFAAkF;IAC5E,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ9F;IAED,6EAA6E;IACvE,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQtD;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,qDAAqD;IAC/C,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;CACF"}

package/dist/turnstile/turnstileManager.js

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/turnstile/turnstileManager.ts
+/** The siteverify endpoint Turnstile tokens are validated against (server-side, not the SDK). */
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/** Per-call SDK timeout + retry budget for widget management operations. */
+const requestOptions = {
+	timeout: 1e4,
+	maxRetries: 3
+};
+/**
+* The server-side response from Turnstile's `/siteverify` endpoint. Pithy validates the raw JSON
+* through this object before trusting it — a humanity check is a security boundary (CLAUDE.md §HTTP:
+* Turnstile is composable middleware). `challenge_ts` is an ISO-8601 string on the wire, decoded to
+* a `Date` via the `JsonDate` codec.
+*/
+const TurnstileVerification = z.object({
+	success: z.boolean().describe("Whether the token passed the humanity challenge."),
+	"error-codes": z.array(z.string()).default([]).describe("Machine-readable failure reasons; empty on success."),
+	messages: z.array(z.string()).optional().describe("Optional human-readable notices from Cloudflare."),
+	challenge_ts: JsonDate.optional().describe("When the challenge was solved (ISO-8601 on the wire, Date in JS)."),
+	hostname: z.string().optional().describe("The hostname the challenge was solved on."),
+	action: z.string().optional().describe("The customer-supplied action label bound to the token."),
+	cdata: z.string().optional().describe("The customer-supplied context data bound to the token.")
+}).describe("Server-side Turnstile siteverify response from challenges.cloudflare.com.");
+/**
+* Out-of-Worker Turnstile access over the REST API: server-side token verification against
+* `/siteverify`, plus widget management (create/list/update/rotate/delete) via the SDK. Inside a
+* Worker the same siteverify call works over `fetch`; this manager is the CLI/CI/provisioning
+* counterpart, addressed by account.
+*/
+var CloudflareTurnstileManager = class extends CloudflareManager {
+	/**
+	* Verify a Turnstile token server-side against `/siteverify`. The secret is the widget's secret
+	* key (never the sitekey). The raw response is validated through `TurnstileVerification`; a
+	* malformed body throws `cloudflare/invalid_response`, a network failure is wrapped as
+	* `cloudflare/request_failed`.
+	*/
+	async verify(token, secret, options) {
+		const body = new URLSearchParams({
+			secret,
+			response: token
+		});
+		if (options?.remoteIp) body.set("remoteip", options.remoteIp);
+		if (options?.action) body.set("action", options.action);
+		const raw = await cloudflareRequest("Turnstile siteverify", async () => {
+			const response = await fetch(SITEVERIFY_URL, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body
+			});
+			if (!response.ok) throw new CloudflareInvalidResponseError({
+				message: "Turnstile siteverify returned a non-OK status.",
+				detail: `siteverify responded ${response.status} ${response.statusText}.`
+			});
+			return await response.json();
+		});
+		const parsed = TurnstileVerification.safeParse(raw);
+		if (!parsed.success) throw new CloudflareInvalidResponseError({
+			message: "Turnstile siteverify response had an unexpected shape.",
+			detail: parsed.error.message
+		});
+		return parsed.data;
+	}
+	/** Find a widget by name. Returns null when no widget matches; never throws on a missing match. */
+	async getTurnstile(name) {
+		return cloudflareRequest(`Turnstile get widget '${name}'`, async () => {
+			for await (const widget of this.getClient().turnstile.widgets.list({ account_id: this.accountId })) if (widget.name === name) return widget;
+			return null;
+		});
+	}
+	/**
+	* Every widget claiming `domain`, matched case-insensitively (hostnames are). The sibling of
+	* {@link getTurnstile}, keyed on the domain instead of the name — and **plural**, deliberately:
+	* Cloudflare's widget names are not unique and a domain may legitimately appear on several widgets,
+	* so returning one would hide the rest from a caller deciding whether the domain is free.
+	*
+	* Exact hostname equality only. Cloudflare treats a widget's domain as covering its subdomains, but
+	* this is the input to a *refusal*, and a refusal inferred from a subdomain relationship would block
+	* `app.example.com` because someone once made a widget for `example.com`.
+	*/
+	async listTurnstilesByDomain(domain) {
+		const wanted = domain.toLowerCase();
+		return cloudflareRequest(`Turnstile list widgets for '${domain}'`, async () => {
+			const matches = [];
+			for await (const widget of this.getClient().turnstile.widgets.list({ account_id: this.accountId })) if (widget.domains?.some((each) => each.toLowerCase() === wanted)) matches.push(widget);
+			return matches;
+		});
+	}
+	/**
+	* Create a widget for the given domains in the requested mode — `managed` (visible) or `invisible`
+	* (silent). Defaults to `invisible` so existing callers keep their behavior.
+	*/
+	async addTurnstile(name, domains, mode = "invisible") {
+		return cloudflareRequest(`Turnstile create widget '${name}'`, () => this.getClient().turnstile.widgets.create({
+			account_id: this.accountId,
+			domains,
+			mode,
+			name
+		}, requestOptions));
+	}
+	/** Delete a widget by its sitekey. */
+	async deleteTurnstile(siteKey) {
+		await cloudflareRequest(`Turnstile delete widget '${siteKey}'`, () => this.getClient().turnstile.widgets.delete(siteKey, { account_id: this.accountId }, requestOptions));
+	}
+	/** Replace the allowed domains on an existing widget (kept in invisible mode). */
+	async updateTurnstileDomains(siteKey, domains, name) {
+		return cloudflareRequest(`Turnstile update domains for '${siteKey}'`, () => this.getClient().turnstile.widgets.update(siteKey, {
+			account_id: this.accountId,
+			domains,
+			mode: "invisible",
+			name
+		}, requestOptions));
+	}
+	/** Rotate a widget's secret key, invalidating the old secret immediately. */
+	async rotateTurnstile(siteKey) {
+		return cloudflareRequest(`Turnstile rotate secret for '${siteKey}'`, () => this.getClient().turnstile.widgets.rotateSecret(siteKey, {
+			account_id: this.accountId,
+			invalidate_immediately: true
+		}, requestOptions));
+	}
+	getServiceType() {
+		return "Cloudflare Turnstile";
+	}
+	/** Prove access by listing widgets. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getClient().turnstile.widgets.list({ account_id: this.accountId });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { CloudflareTurnstileManager, TurnstileVerification };

package/dist/user/userManager.d.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { CloudflareManager } from "../client/manager";
+/**
+ * Out-of-Worker read access to the **user/token** identity behind a CF API token — `GET /user` and
+ * `GET /user/tokens/verify`/`/user/tokens/:id`. The audit CLI emitter uses it to attribute a
+ * control-plane action (`pithy migrate`, `pithy deploy`, …) to the right actor: a user token
+ * (`cfut_*`) resolves to the developer's email, an account token (`cfat_*`) to the token's name.
+ *
+ * These are *user-scoped* endpoints, so they need a user-bound token — CLAUDE.md prefers
+ * account-owned tokens for provisioning, but actor attribution is exactly the case where the token's
+ * own identity is the point. Reads only; never mints, never logs a token value.
+ */
+/** The CF user behind a user token. The SDK omits `email` from its type, but the API returns it. */
+export declare const CfUserIdentity: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CfUserIdentity = z.output<typeof CfUserIdentity>;
+/** The result of verifying the calling token: its id and lifecycle status. */
+export declare const CfTokenVerification: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+}, z.core.$strip>;
+export type CfTokenVerification = z.output<typeof CfTokenVerification>;
+export declare class CloudflareUserManager extends CloudflareManager {
+    getServiceType(): string;
+    /** Prove access by reading the user record. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** The Cloudflare user behind a user (`cfut_*`) token — `GET /user`. */
+    getUser(): Promise<CfUserIdentity>;
+    /** Verify the calling token and read its id + status — `GET /user/tokens/verify`. */
+    verifyToken(): Promise<CfTokenVerification>;
+    /** The name of a token by id, or `null` if it can't be read — `GET /user/tokens/:id`. */
+    getTokenName(tokenId: string): Promise<string | null>;
+}
+//# sourceMappingURL=userManager.d.ts.map

package/dist/user/userManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userManager.d.ts","sourceRoot":"","sources":["../../src/user/userManager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;GASG;AAEH,oGAAoG;AACpG,eAAO,MAAM,cAAc;;;iBAKiE,CAAC;AAC7F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB;;;iBAK4D,CAAC;AAC7F,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAKvE,qBAAa,qBAAsB,SAAQ,iBAAiB;IAC1D,cAAc,IAAI,MAAM,CAEvB;IAED,6DAA6D;IACvD,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED,wEAAwE;IAClE,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAGvC;IAED,qFAAqF;IAC/E,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAGhD;IAED,yFAAyF;IACnF,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAI1D;CACF"}

package/dist/user/userManager.js

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { cloudflareRequest, decodeResponse } from "../client/errors.js";
+import { CloudflareManager } from "../client/manager.js";
+import { z } from "zod";
+//#region src/user/userManager.ts
+/**
+* Out-of-Worker read access to the **user/token** identity behind a CF API token — `GET /user` and
+* `GET /user/tokens/verify`/`/user/tokens/:id`. The audit CLI emitter uses it to attribute a
+* control-plane action (`pithy migrate`, `pithy deploy`, …) to the right actor: a user token
+* (`cfut_*`) resolves to the developer's email, an account token (`cfat_*`) to the token's name.
+*
+* These are *user-scoped* endpoints, so they need a user-bound token — CLAUDE.md prefers
+* account-owned tokens for provisioning, but actor attribution is exactly the case where the token's
+* own identity is the point. Reads only; never mints, never logs a token value.
+*/
+/** The CF user behind a user token. The SDK omits `email` from its type, but the API returns it. */
+const CfUserIdentity = z.object({
+	id: z.string().optional().describe("The Cloudflare user id — stable cross-reference for the actor."),
+	email: z.string().optional().describe("The Cloudflare user's email — the human actor's identifier.")
+}).describe("The identity behind a Cloudflare user (`cfut_*`) API token, from `GET /user`.");
+/** The result of verifying the calling token: its id and lifecycle status. */
+const CfTokenVerification = z.object({
+	id: z.string().describe("The token's id — addresses it for a follow-up name lookup."),
+	status: z.string().describe("The token's lifecycle status (`active` | `disabled` | `expired`).")
+}).describe("The result of `GET /user/tokens/verify` for the calling Cloudflare API token.");
+/** Just the token's name, the piece the account-token actor path needs. */
+const TokenName = z.object({ name: z.string() });
+var CloudflareUserManager = class extends CloudflareManager {
+	getServiceType() {
+		return "Cloudflare User";
+	}
+	/** Prove access by reading the user record. Never throws. */
+	async validateServiceAccess() {
+		try {
+			await this.getUser();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** The Cloudflare user behind a user (`cfut_*`) token — `GET /user`. */
+	async getUser() {
+		const raw = await cloudflareRequest("get user", () => this.getClient().user.get());
+		return decodeResponse(CfUserIdentity, raw, "user get");
+	}
+	/** Verify the calling token and read its id + status — `GET /user/tokens/verify`. */
+	async verifyToken() {
+		const raw = await cloudflareRequest("verify token", () => this.getClient().user.tokens.verify());
+		return decodeResponse(CfTokenVerification, raw, "token verify");
+	}
+	/** The name of a token by id, or `null` if it can't be read — `GET /user/tokens/:id`. */
+	async getTokenName(tokenId) {
+		const raw = await cloudflareRequest(`get token ${tokenId}`, () => this.getClient().user.tokens.get(tokenId));
+		const parsed = TokenName.safeParse(raw);
+		return parsed.success ? parsed.data.name : null;
+	}
+};
+//#endregion
+export { CfTokenVerification, CfUserIdentity, CloudflareUserManager };

package/dist/workers/buildsManager.d.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CloudflareManager } from "../client/manager";
+import { CfBuild, CfBuildLog, CfBuildToken, CfBuildTrigger, CfRepoConnection, type CfTriggerEnvVar } from "./buildsTypes";
+/** Arguments for `createRepoConnection`. */
+export interface CreateRepoConnectionArgs {
+    /** The git provider hosting the repo. */
+    providerType: "gitlab" | "github";
+    /** The repository's id in the git provider. */
+    repoId: string;
+    /** The repo path relative to the provider account. */
+    repoName: string;
+    /** The provider account identifier (e.g. 'group:15366484'). */
+    providerAccountId: string;
+    /** The provider account display name. */
+    providerAccountName: string;
+}
+/** Arguments for `upsertTrigger`. */
+export interface UpsertTriggerArgs {
+    /** The immutable Worker id (hex UUID) the trigger builds — not the worker name. */
+    scriptName: string;
+    /** The repo connection UUID to build from. */
+    repoConnectionId: string;
+    /** The build token UUID the trigger authenticates with. */
+    buildTokenUuid: string;
+    /** The trigger's human-readable name. */
+    triggerName: string;
+    /** Branch patterns whose pushes auto-fire the trigger (must be non-empty). */
+    branchIncludes: string[];
+    /** Branch patterns excluded from auto-firing. */
+    branchExcludes?: string[];
+    /** Path patterns whose changes auto-fire the trigger. */
+    pathIncludes?: string[];
+    /** The shell command that builds the Worker. */
+    buildCommand: string;
+    /** The shell command CF Builds runs to deploy after a build. */
+    deployCommand: string;
+    /** The repo subdirectory builds run from. Defaults to '/'. */
+    rootDirectory?: string;
+    /** Whether build caching is enabled. Defaults to true. */
+    buildCachingEnabled?: boolean;
+}
+/** A subset of trigger fields that can be patched after creation. */
+export interface UpdateTriggerArgs {
+    /** A branch filter to set on the trigger. */
+    branchFilter?: string;
+    /** The build command to set. */
+    buildCommand?: string;
+    /** The deploy command to set. */
+    deployCommand?: string;
+    /** The root directory to set. */
+    rootDirectory?: string;
+}
+/**
+ * Out-of-Worker access to the Cloudflare Builds API: repo connections, build triggers, builds, and
+ * trigger env vars. CF Builds is the CI/CD layer for Workers — it clones a git repo, runs a build
+ * command, and reports outcomes.
+ *
+ * As of the SDK version this package targets, the Builds endpoints are NOT exposed as typed SDK
+ * resources, so this manager uses the documented escape hatch (`getApiToken()` + raw `fetch`) against
+ * explicit `/accounts/{id}/builds/...` paths. Every request goes through `cloudflareRequest` so
+ * failures wrap as `cloudflare/request_failed`, and every response is validated with Zod
+ * (`cloudflare/invalid_response` on mismatch).
+ */
+export declare class CloudflareBuildsManager extends CloudflareManager {
+    /**
+     * Issue a raw CF REST call and unwrap the `{ result, success, errors }` envelope. A failure —
+     * either a non-2xx status **or** a 200 carrying `success: false` — throws `cloudflare/request_failed`
+     * with the structured CF error codes pinned to the front of `detail` (so idempotency checks read a
+     * stable marker, never a substring a verbose body could push past truncation). An unparseable body
+     * throws `cloudflare/invalid_response`.
+     */
+    private call;
+    /**
+     * Register a git repository with CF Builds. `PUT /builds/repos/connections` is CF's documented
+     * upsert — calling with the same repo id returns the existing connection.
+     */
+    createRepoConnection(args: CreateRepoConnectionArgs): Promise<CfRepoConnection>;
+    /**
+     * Upsert a build trigger linking a Worker script to a repo. Tries `POST /builds/triggers`; on the
+     * 409 "trigger already exists" conflict, falls back to listing the script's triggers and returning
+     * the matching one. Idempotent.
+     */
+    upsertTrigger(args: UpsertTriggerArgs): Promise<CfBuildTrigger>;
+    /** List the build tokens available on the account. */
+    listBuildTokens(): Promise<CfBuildToken[]>;
+    /** Patch an existing build trigger's configuration. */
+    updateTrigger(triggerId: string, args: UpdateTriggerArgs): Promise<CfBuildTrigger>;
+    /** Delete a build trigger. */
+    deleteTrigger(triggerId: string): Promise<void>;
+    /** Manually start a build for a trigger at a specific branch + commit. */
+    triggerManualBuild(triggerId: string, branch: string, commitHash: string): Promise<CfBuild>;
+    /** Get a build's current status and metadata by id. */
+    getBuild(buildId: string): Promise<CfBuild>;
+    /** Cancel a running build. */
+    cancelBuild(buildId: string): Promise<void>;
+    /** Get the log output for a build. */
+    getBuildLogs(buildId: string): Promise<CfBuildLog[]>;
+    /** List all builds for a Worker script. */
+    listBuildsByScript(scriptName: string): Promise<CfBuild[]>;
+    /**
+     * List the build triggers for a Worker script. `externalScriptId` must be the immutable Worker id
+     * (hex UUID), resolved via `CloudflareWorkersManager.getWorkerInternalId`. Returns an empty array
+     * when the script has no triggers (CF 404 code 12000).
+     */
+    listTriggersByScript(externalScriptId: string): Promise<CfBuildTrigger[]>;
+    /**
+     * Bulk-upsert environment variables on a build trigger. The wire body is a map keyed by variable
+     * name (`{ NAME: { is_secret, value }, ... }`), not an array.
+     */
+    upsertTriggerEnvVars(triggerId: string, envVars: CfTriggerEnvVar[]): Promise<void>;
+    getServiceType(): string;
+    /** Prove access by listing build triggers. Never throws. */
+    validateServiceAccess(): Promise<boolean>;
+    /** Validate a raw CF result against a Zod schema, throwing `cloudflare/invalid_response` on mismatch. */
+    private validate;
+}
+//# sourceMappingURL=buildsManager.d.ts.map

package/dist/workers/buildsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildsManager.d.ts","sourceRoot":"","sources":["../../src/workers/buildsManager.ts"],"names":[],"mappings":"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"}