src/ops-cloudflare-config.ts

Functions

Imports

It imports src/env.ts, src/ops-cloudflare.ts. Imported by src/tools/cloudflare.ts.

Source

1import type { Env } from "./env";
2import { CF_API, CfReadError, cfGetAll, cloudflareCredentials, type FetchLike } from "./ops-cloudflare";
3
4// The reads behind capsid_admin_read_ops's Cloudflare actions: Access applications and policies, and Email
5// Routing rules and destination addresses. Ruled 2026-09-29, "Capsid MCP roadmap,
6// build or don't build". Only src/tools/cloudflare.ts imports
7// this module (test/ops-cloudflare-config.test.ts), and that tool is admin only.
8//
9// Every reader copies named fields into a fresh object. Nothing Cloudflare returns is
10// passed through whole, because these objects carry secrets beside their settings: an
11// Access for SaaS app holds saas_app.client_secret, and SCIM provisioning holds
12// scim_config.authentication.{password, token, client_secret}. A field Cloudflare adds
13// later is therefore dropped until it is named here. Never read: saas_app, scim_config,
14// aud, or any other field not listed below.
15//
16// Permissions, all on CF_OPS_TOKEN (the steps to add them are in src/ops-cloudflare.ts
17// and docs/portal.md, "The Cloudflare token"). A 403 names the one that is missing.
18
19export const CF_CONFIG_ACTIONS = ["access_apps", "access_policies", "email_rules", "email_addresses"] as const;
20export type CfConfigAction = (typeof CF_CONFIG_ACTIONS)[number];
21
22export const CF_PERMISSION = {
23  access: "Account / Access: Apps and Policies / Read",
24  zones: "Zone / Zone / Read (Zone Resources: All zones from the account)",
25  rules: "Zone / Email Routing Rules / Read",
26  addresses: "Account / Email Routing Addresses / Read",
27} as const;
28
29// Access lists page up to 1000; zones, rules and addresses up to 50. One size for all.
30const PER_PAGE = 50;
31const MAX_TEXT = 512;
32
33interface AccessAppOut {
34  id: string | null;
35  name: string | null;
36  domain: string | null;
37  type: string | null;
38  self_hosted_domains: string[];
39  destinations: Array<{ type: string | null; uri: string | null; hostname: string | null }>;
40  policies: Array<{ name: string | null; decision: string | null }>;
41}
42
43interface AccessRuleOut {
44  type: string;
45  // Present only for the rule types whose value is not a secret: email (the address),
46  // email_domain (the domain), group (the group id; the rule carries no name) and
47  // service_token (the token id, never the token).
48  value?: string;
49}
50
51interface AccessPolicyOut {
52  id: string | null;
53  name: string | null;
54  decision: string | null;
55  include: AccessRuleOut[];
56  exclude: AccessRuleOut[];
57  require: AccessRuleOut[];
58}
59
60interface EmailRuleOut {
61  name: string | null;
62  enabled: boolean | null;
63  priority: number | null;
64  matchers: Array<{ type: string | null; field: string | null; value: string | null }>;
65  actions: Array<{ type: string | null; value: string[] }>;
66}
67
68interface EmailAddressOut {
69  email: string | null;
70  verified: boolean;
71}
72
73type CfConfigResult =
74  | { action: "access_apps"; count: number; apps: AccessAppOut[] }
75  | { action: "access_policies"; count: number; policies: AccessPolicyOut[] }
76  | { action: "email_rules"; zones: Array<{ zone: string; count: number; rules: EmailRuleOut[] }> }
77  | { action: "email_addresses"; count: number; addresses: EmailAddressOut[] };
78
79const text = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v.slice(0, MAX_TEXT) : null);
80const obj = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
81const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
82const texts = (v: unknown): string[] => list(v).map(text).filter((s): s is string => s !== null);
83
84/** One list read, with a 403 turned into the permission the token lacks. Any other
85 *  failure keeps Cloudflare's own message. */
86async function readAll(fetchImpl: FetchLike, token: string, url: string, what: string, permission: string): Promise<unknown[]> {
87  try {
88    return await cfGetAll(fetchImpl, token, url, what, PER_PAGE);
89  } catch (err) {
90    if (err instanceof CfReadError && err.status === 403) {
91      throw new Error(
92        `${what} was refused with 403: CF_OPS_TOKEN lacks ${permission}. ` +
93          `Add it at dash.cloudflare.com/profile/api-tokens, token capsid-portal-read, Edit (docs/portal.md, "The Cloudflare token"). ` +
94          `Cloudflare said: ${err.message}`
95      );
96    }
97    throw err;
98  }
99}
100
101function toAccessApp(raw: unknown): AccessAppOut {
102  const a = obj(raw);
103  return {
104    id: text(a.id),
105    name: text(a.name),
106    domain: text(a.domain),
107    type: text(a.type),
108    self_hosted_domains: texts(a.self_hosted_domains),
109    destinations: list(a.destinations).map((d) => {
110      const o = obj(d);
111      return { type: text(o.type), uri: text(o.uri), hostname: text(o.hostname) };
112    }),
113    policies: list(a.policies).map((p) => {
114      const o = obj(p);
115      return { name: text(o.name), decision: text(o.decision) };
116    }),
117  };
118}
119
120// The one field each value-bearing rule type may show. Every other type shows its
121// type alone: its value is an identity provider id, a list id, an IP range or a
122// claim, none of which the tool was ruled to return.
123const RULE_VALUE: Record<string, string> = {
124  email: "email",
125  email_domain: "domain",
126  group: "id",
127  service_token: "token_id",
128};
129
130function toAccessRule(raw: unknown): AccessRuleOut {
131  const r = obj(raw);
132  const type = Object.keys(r)[0];
133  if (type === undefined) return { type: "unknown" };
134  const out: AccessRuleOut = { type: type.slice(0, 64) };
135  if (Object.hasOwn(RULE_VALUE, type)) {
136    const value = text(obj(r[type])[RULE_VALUE[type]]);
137    if (value !== null) out.value = value;
138  }
139  return out;
140}
141
142function toAccessPolicy(raw: unknown): AccessPolicyOut {
143  const p = obj(raw);
144  return {
145    id: text(p.id),
146    name: text(p.name),
147    decision: text(p.decision),
148    include: list(p.include).map(toAccessRule),
149    exclude: list(p.exclude).map(toAccessRule),
150    require: list(p.require).map(toAccessRule),
151  };
152}
153
154function toEmailRule(raw: unknown): EmailRuleOut {
155  const r = obj(raw);
156  return {
157    name: text(r.name),
158    enabled: typeof r.enabled === "boolean" ? r.enabled : null,
159    priority: typeof r.priority === "number" ? r.priority : null,
160    matchers: list(r.matchers).map((m) => {
161      const o = obj(m);
162      return { type: text(o.type), field: text(o.field), value: text(o.value) };
163    }),
164    actions: list(r.actions).map((a) => {
165      const o = obj(a);
166      return { type: text(o.type), value: texts(o.value) };
167    }),
168  };
169}
170
171function toEmailAddress(raw: unknown): EmailAddressOut {
172  const a = obj(raw);
173  // Cloudflare's verified is the time of verification, or null while unverified.
174  return { email: text(a.email), verified: typeof a.verified === "string" && a.verified.length > 0 };
175}
176
177/** The zones Email Routing rules are read for: the one named, or every zone in the
178 *  account the token can list. A name no zone has fails, never an empty answer. */
179async function zonesFor(fetchImpl: FetchLike, token: string, account: string, zone: string | undefined): Promise<Array<{ id: string; name: string }>> {
180  const url = new URL(`${CF_API}/zones`);
181  url.searchParams.set("account.id", account);
182  if (zone !== undefined) url.searchParams.set("name", zone);
183  const raw = await readAll(fetchImpl, token, url.toString(), "the zones list", CF_PERMISSION.zones);
184  const zones = raw
185    .map((z) => ({ id: text(obj(z).id), name: text(obj(z).name) }))
186    .filter((z): z is { id: string; name: string } => z.id !== null && z.name !== null);
187  if (zone !== undefined && !zones.some((z) => z.name === zone)) {
188    throw new Error(`no zone named ${zone} in the account CF_OPS_TOKEN can list.`);
189  }
190  return zone === undefined ? zones : zones.filter((z) => z.name === zone);
191}
192
193/** One cloudflare_config action. Credentials missing fails with what is unset, and
194 *  nothing is fetched. */
195export async function readCloudflareConfig(
196  env: Pick<Env, "CF_OPS_TOKEN" | "CF_ACCOUNT_ID" | "R2_ACCOUNT_ID">,
197  action: CfConfigAction,
198  zone: string | undefined,
199  fetchImpl: FetchLike
200): Promise<CfConfigResult> {
201  const creds = cloudflareCredentials(env);
202  if (!creds.ok) throw new Error(`the Cloudflare read is not configured: ${creds.reason}.`);
203  const { token } = creds;
204  const account = `${CF_API}/accounts/${encodeURIComponent(creds.account)}`;
205  switch (action) {
206    case "access_apps": {
207      const apps = (await readAll(fetchImpl, token, `${account}/access/apps`, "the Access applications list", CF_PERMISSION.access)).map(toAccessApp);
208      return { action, count: apps.length, apps };
209    }
210    case "access_policies": {
211      const policies = (await readAll(fetchImpl, token, `${account}/access/policies`, "the Access policies list", CF_PERMISSION.access)).map(toAccessPolicy);
212      return { action, count: policies.length, policies };
213    }
214    case "email_rules": {
215      const out: Array<{ zone: string; count: number; rules: EmailRuleOut[] }> = [];
216      for (const z of await zonesFor(fetchImpl, token, creds.account, zone)) {
217        const url = `${CF_API}/zones/${encodeURIComponent(z.id)}/email/routing/rules`;
218        const rules = (await readAll(fetchImpl, token, url, `the Email Routing rules for ${z.name}`, CF_PERMISSION.rules)).map(toEmailRule);
219        out.push({ zone: z.name, count: rules.length, rules });
220      }
221      return { action, zones: out };
222    }
223    case "email_addresses": {
224      const addresses = (await readAll(fetchImpl, token, `${account}/email/routing/addresses`, "the Email Routing addresses list", CF_PERMISSION.addresses)).map(
225        toEmailAddress
226      );
227      return { action, count: addresses.length, addresses };
228    }
229  }
230  throw new Error(`unknown cloudflare_config action '${String(action)}'.`);
231}