@pithy-sh/cloudflare 0.1.0

package/src/tokens/permissions.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareNotConfiguredError } from "../client/errors";
+
+/**
+ * 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 const PERMISSION_GROUPS = {
+  "d1:read": ["D1 Read"],
+  // "D1 Write", not "D1 Edit" — Cloudflare names the D1 group Write while several other services use
+  // Edit, and the account catalog has no group called "D1 Edit" at all. `accountTokensManager.integration.test.ts`
+  // now checks every name here against the live account, which is the only place that can tell.
+  "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"],
+  // Read-only, and read-only is the whole point: Pithy attaches routes to zones and never creates,
+  // transfers, or deletes one — a zone is the adopter's relationship with their registrar. This exists
+  // so `pithy init` and `pithy worker add` can offer the account's real zones instead of asking someone
+  // to paste an id off a dashboard page.
+  "zone:read": ["Zone Read"],
+} as const;
+
+/** 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 function isPermissionKey(key: string): key is PermissionKey {
+  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.
+ */
+export function resolvePermissionKeys(keys: string[]): string[] {
+  const names: string[] = [];
+  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;
+}

package/src/tokens/profiles.ts

@@ -0,0 +1,238 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability, TokenProfileSeam } from "@pithy-sh/core/src/capability/capability";
+import { CloudflareNotConfiguredError } from "../client/errors";
+import { accountResource, type TokenPermission } from "./accountTokensManager";
+import { isPermissionKey, type PermissionKey, resolvePermissionKeys } 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 const TOKEN_STORES: readonly TokenStore[] = ["secrets-store", "dev-vars", "ephemeral"];
+
+/** The name of the one CI system token — the single least-privilege credential a CI pipeline runs under. */
+export 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: readonly PermissionKey[] = [
+  "workers:write",
+  "d1:read",
+  "d1:write",
+  "secrets:read",
+  "secrets:write",
+];
+
+/**
+ * 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";
+
+/** 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. */
+  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 function tokenSecretName(profile: string): string {
+  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.
+ */
+export function defineTokenProfile(profile: TokenProfile): TokenProfile {
+  resolvePermissionKeys(profile.permissions); // throws on an unknown key
+  return profile;
+}
+
+/** Validate a capability's declared permission keys, throwing an actionable error on any unknown one. */
+function assertPermissionKeys(keys: readonly string[], where: string): PermissionKey[] {
+  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 as PermissionKey[];
+}
+
+/** Build the aggregating `ci-system` profile: the base permissions ∪ every capability's `ciPermissions`. */
+function ciSystemProfile(capabilities: readonly Capability[]): TokenProfile {
+  const permissions: PermissionKey[] = [...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.",
+  };
+}
+
+/**
+ * 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;
+}
+
+/** 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(", ")}.`,
+    });
+  }
+  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,
+  };
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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 function resolveProfile(
+  profiles: Record<string, TokenProfile>,
+  name: string,
+  override?: ProfileOverride,
+): TokenProfile {
+  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. */
+export function permissionsForKeys(keys: PermissionKey[], accountId: string): TokenPermission[] {
+  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.
+ */
+export function profilePermissions(profile: TokenProfile, accountId: string): TokenPermission[] {
+  const resources =
+    profile.resources && profile.resources !== "account" ? profile.resources : accountResource(accountId);
+  return [{ permissionGroupNames: resolvePermissionKeys(profile.permissions), resources }];
+}

package/src/turnstile/turnstileManager.ts

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import type { Cloudflare } from "cloudflare";
+import type { Widget, WidgetListResponse } from "cloudflare/resources/turnstile/widgets";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/** 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: Cloudflare.RequestOptions = { timeout: 10000, maxRetries: 3 };
+
+/**
+ * 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 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.");
+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 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`.
+   */
+  async verify(token: string, secret: string, options?: TurnstileVerifyOptions): Promise<TurnstileVerification> {
+    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()) as unknown;
+    });
+
+    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: string): Promise<WidgetListResponse | null> {
+    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: string): Promise<WidgetListResponse[]> {
+    const wanted = domain.toLowerCase();
+    return cloudflareRequest(`Turnstile list widgets for '${domain}'`, async () => {
+      const matches: WidgetListResponse[] = [];
+      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: string, domains: string[], mode: TurnstileWidgetMode = "invisible"): Promise<Widget> {
+    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: string): Promise<void> {
+    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: string, domains: string[], name: string): Promise<Widget> {
+    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: string): Promise<Widget> {
+    return cloudflareRequest(`Turnstile rotate secret for '${siteKey}'`, () =>
+      this.getClient().turnstile.widgets.rotateSecret(
+        siteKey,
+        { account_id: this.accountId, invalidate_immediately: true },
+        requestOptions,
+      ),
+    );
+  }
+
+  getServiceType(): string {
+    return "Cloudflare Turnstile";
+  }
+
+  /** Prove access by listing widgets. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getClient().turnstile.widgets.list({ account_id: this.accountId });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/user/userManager.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest, decodeResponse } from "../client/errors";
+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 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`.");
+export type CfUserIdentity = z.output<typeof CfUserIdentity>;
+
+/** The result of verifying the calling token: its id and lifecycle status. */
+export 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.");
+export type CfTokenVerification = z.output<typeof CfTokenVerification>;
+
+/** Just the token's name, the piece the account-token actor path needs. */
+const TokenName = z.object({ name: z.string() });
+
+export class CloudflareUserManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare User";
+  }
+
+  /** Prove access by reading the user record. Never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.getUser();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** The Cloudflare user behind a user (`cfut_*`) token — `GET /user`. */
+  async getUser(): Promise<CfUserIdentity> {
+    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(): Promise<CfTokenVerification> {
+    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: string): Promise<string | null> {
+    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;
+  }
+}