src/access-sync.ts

Functions

Imports

It imports src/agents.ts, src/env.ts, src/http.ts, src/rate-limit.ts, src/scope.ts, src/signed-requests.ts, src/store-guards.ts. Imported by src/routes.ts.

Source

1import type { Agent } from "./agents";
2import { resolveAgent } from "./agents";
3import type { Env } from "./env";
4import { readBoundedText } from "./signed-requests";
5import { checkRate, type RateLimitPolicy } from "./rate-limit";
6import { checkScope } from "./scope";
7import { auditStatement } from "./store-guards";
8import { textResponse } from "./http";
9
10// THE CLOUDFLARE ACCESS SYNC (job_d0fabaadecb1; design docs/design/design-identity-roles.md,
11// "The Cloudflare sync"; Dustin's rulings of 2026-10-09, people and roles, points 1 and 2).
12// An app with staff keeps its own members list. When it changes, the app's server posts the
13// whole current list here with its own minted agent key, and Capsid, the only holder of the
14// write token, makes that app's Access group hold exactly those emails. Apps never hold the
15// token (ruling 1).
16//
17// - The caller names its namespace and must hold the write grant on it through checkScope
18//   (one enforcement point, test/scope.test.ts). The group is never named by the caller: it is
19//   the one pinned for that namespace in access_sync_groups (migrations/0040), so a key
20//   reaches its own app's group alone.
21// - Before writing, the group is read and its name must equal the pinned name, and every
22//   include rule must be an email rule. Anything else (a renamed group, a hand-added rule,
23//   a pinned id pointing at the wrong group) refuses and writes nothing (ruling 2).
24// - The write is a full PUT: name, the members as one email rule each, and the group's
25//   exclude and require rules carried over unchanged. The list is the app's whole list, so
26//   the group cannot drift from the members page.
27// - `removed` names people the app just removed or expired. For each one the group held
28//   before the write and no longer in the list, the Zero Trust user's seat is freed
29//   (access_seat and gateway_seat false). Freeing a seat never grants or blocks anything by
30//   itself; the allow list and the app's own check do that, so a seat failure is reported and the sync still counts as written.
31// - Every call writes one audit_log row with Cloudflare's answer, refused or not, and the
32//   response carries the same, so the app can show "Waiting for Cloudflare" and retry.
33// - Admin policies list Dustin's emails directly and never this group, so no sync can add
34//   anyone to an admin surface. That is account configuration, not code; docs/portal.md.
35//
36// The token is CF_ACCESS_SYNC_TOKEN, separate from the read-only CF_OPS_TOKEN, with these
37// permissions on this one account and nothing else:
38//   Access: Groups Write              GET and PUT /accounts/{id}/access/groups/{group}
39//   Access: Users Read                GET /accounts/{id}/access/users (the seat lookup)
40//   Zero Trust: Seats Write           PATCH /accounts/{id}/access/seats
41// "Access: Groups Write" is narrower than the design's "Organizations, Identity Providers,
42// and Groups Write": it reaches rule groups only, not organization settings or identity
43// providers (developers.cloudflare.com/fundamentals/api/reference/permissions/, read
44// 2026-10-10).
45
46export const ACCESS_SYNC_PATH = "/ops/access-sync";
47// Its own base and fetch type rather than src/ops-cloudflare.ts's: that module is the
48// read-only watcher path, and test/ops-cloudflare.test.ts keeps its importers to two.
49const CF_API = "https://api.cloudflare.com/client/v4";
50export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
51const ACCESS_SYNC_ACTION = "access-sync";
52const MAX_ACCESS_SYNC_BYTES = 65536;
53// Cloudflare One's limit on rules in one group.
54const MAX_GROUP_MEMBERS = 1000;
55const MAX_REMOVED = 100;
56const CF_TIMEOUT_MS = 10_000;
57const USERS_PER_PAGE = 50;
58const USER_PAGES = 20;
59
60export const ACCESS_SYNC_PERMISSION = {
61  group: "Access: Groups Write",
62  users: "Access: Users Read",
63  seats: "Zero Trust: Seats Write",
64} as const;
65
66// A busy members page adds a handful of people at once, and each change posts the whole
67// list. Fail closed: this path writes to Cloudflare.
68const ACCESS_SYNC_LIMIT: RateLimitPolicy = {
69  prefix: "access-sync:rate:",
70  perHour: 120,
71  perDay: 500,
72  label: "ACCESS_SYNC",
73  onUnavailable: "refuse",
74};
75
76export type Checked<T> = { ok: true; value: T } | { ok: false; refusal: string };
77
78export interface SyncRequest {
79  namespace: string;
80  members: string[];
81  removed: string[];
82}
83
84export interface PinnedGroup {
85  group_id: string;
86  group_name: string;
87}
88
89export interface SyncResult {
90  ok: boolean;
91  namespace: string;
92  group: string;
93  // What Cloudflare holds now (ok) or still held (refused).
94  members: number;
95  added: string[];
96  dropped: string[];
97  // not_members: removed emails the group did not hold before this sync; their seats are
98  // never touched, so a key cannot free the seat of someone outside its own group.
99  seats: { freed: string[]; not_found: string[]; kept: string[]; not_members: string[]; failed: string | null };
100  // Why the group was not written, in words, when ok is false.
101  refusal: string | null;
102  // The HTTP status Cloudflare answered when it refused, or null.
103  cloudflare_status: number | null;
104  // The group is not the one pinned, or holds a rule the sync would erase: the seat's to
105  // fix, not a Cloudflare failure, so a retry cannot help.
106  conflict: boolean;
107}
108
109const EMAIL = /^[^\s@<>()",;:]+@[^\s@<>()",;:]+\.[^\s@<>()",;:]+$/;
110const BODY_KEYS = new Set(["namespace", "members", "removed"]);
111
112/** One email in the form every comparison uses, or null when it is not one. */
113function normalizeEmail(raw: unknown): string | null {
114  if (typeof raw !== "string") return null;
115  const email = raw.trim().toLowerCase();
116  return email.length <= 254 && EMAIL.test(email) ? email : null;
117}
118
119/**
120 * The request a body describes, or why it is refused. The whole body is refused on the
121 * first bad email, so a half-read list is never written as if it were the whole.
122 */
123export function parseSyncBody(body: unknown): Checked<SyncRequest> {
124  const refuse = (refusal: string): Checked<never> => ({ ok: false, refusal });
125  if (!body || typeof body !== "object" || Array.isArray(body)) return refuse("the body must be a JSON object { namespace, members, removed? }");
126  const record = body as Record<string, unknown>;
127  for (const key of Object.keys(record)) if (!BODY_KEYS.has(key)) return refuse(`unknown field '${key}': a sync has namespace, members and removed only (the group is the one pinned for the namespace, never named here)`);
128  if (typeof record.namespace !== "string" || record.namespace === "") return refuse("namespace is required");
129  if (!Array.isArray(record.members)) return refuse("members must be an array of emails: the app's whole current list");
130  if (record.members.length > MAX_GROUP_MEMBERS) return refuse(`at most ${MAX_GROUP_MEMBERS} members (Cloudflare's rules per group); got ${record.members.length}`);
131  const removedRaw = record.removed ?? [];
132  if (!Array.isArray(removedRaw)) return refuse("removed must be an array of emails");
133  if (removedRaw.length > MAX_REMOVED) return refuse(`at most ${MAX_REMOVED} removed emails per sync; got ${removedRaw.length}`);
134  const members = new Set<string>();
135  for (const [i, raw] of record.members.entries()) {
136    const email = normalizeEmail(raw);
137    if (!email) return refuse(`members[${i}] is not an email`);
138    members.add(email);
139  }
140  const removed = new Set<string>();
141  for (const [i, raw] of removedRaw.entries()) {
142    const email = normalizeEmail(raw);
143    if (!email) return refuse(`removed[${i}] is not an email`);
144    removed.add(email);
145  }
146  return { ok: true, value: { namespace: record.namespace, members: [...members].sort(), removed: [...removed].sort() } };
147}
148
149/** Why `agent` may not sync `namespace`'s group, or null. */
150function syncCallerRefusal(agent: Agent, namespace: string): string | null {
151  return checkScope(agent, { tool: ACCESS_SYNC_PATH, grant: "write", namespace });
152}
153
154/** The group pinned for a namespace, or null when the seat has pinned none. */
155async function readPinnedGroup(db: D1Database, namespace: string): Promise<PinnedGroup | null> {
156  const row = await db.prepare("SELECT group_id, group_name FROM access_sync_groups WHERE namespace = ?1").bind(namespace).first<PinnedGroup>();
157  return row ?? null;
158}
159
160class CfWriteError extends Error {
161  readonly status: number;
162  constructor(message: string, status: number) {
163    super(message);
164    this.name = "CfWriteError";
165    this.status = status;
166  }
167}
168
169type Envelope = { success?: unknown; errors?: unknown; result?: unknown; result_info?: unknown };
170
171function messagesOf(errors: unknown): string {
172  if (!Array.isArray(errors)) return "";
173  return errors
174    .map((e) => (e && typeof e === "object" && typeof (e as { message?: unknown }).message === "string" ? (e as { message: string }).message : ""))
175    .filter(Boolean)
176    .join("; ")
177    .slice(0, 300);
178}
179
180// One Cloudflare call. A non-2xx or success false throws with Cloudflare's own words and,
181// for a 403, the permission this call needs. The token is never part of a message.
182async function cfCall(fetchImpl: FetchLike, token: string, method: "GET" | "PUT" | "PATCH", url: string, what: string, permission: string, body?: unknown): Promise<Envelope> {
183  const headers: Record<string, string> = { Authorization: `Bearer ${token}`, "User-Agent": "capsid-access-sync" };
184  if (body !== undefined) headers["Content-Type"] = "application/json";
185  const res = await fetchImpl(url, {
186    method,
187    headers,
188    body: body === undefined ? undefined : JSON.stringify(body),
189    redirect: "manual",
190    signal: AbortSignal.timeout(CF_TIMEOUT_MS),
191  });
192  let parsed: Envelope | null = null;
193  try {
194    parsed = JSON.parse(await res.text()) as Envelope;
195  } catch {
196    throw new CfWriteError(`${what} answered ${res.status} with a body that is not JSON`, res.status);
197  }
198  if (!res.ok || parsed?.success !== true) {
199    const said = messagesOf(parsed?.errors) || "no error message";
200    const lacks = res.status === 403 ? ` CF_ACCESS_SYNC_TOKEN lacks ${permission}.` : "";
201    throw new CfWriteError(`${what} answered ${res.status}.${lacks} Cloudflare said: ${said}`, res.status);
202  }
203  return parsed;
204}
205
206type Rule = Record<string, unknown>;
207
208/** The email an include rule names, or null for any other kind of rule. */
209function ruleEmail(rule: unknown): string | null {
210  if (!rule || typeof rule !== "object") return null;
211  const keys = Object.keys(rule);
212  if (keys.length !== 1 || keys[0] !== "email") return null;
213  return normalizeEmail((rule as { email?: { email?: unknown } }).email?.email);
214}
215
216/**
217 * Make the pinned group hold exactly `req.members`, then free the seats of `req.removed`
218 * that are no longer members. Never throws: every outcome is a SyncResult, so the caller
219 * audits it.
220 */
221export async function runSync(fetchImpl: FetchLike, token: string, account: string, pinned: PinnedGroup, req: SyncRequest): Promise<SyncResult> {
222  const base = `${CF_API}/accounts/${encodeURIComponent(account)}/access`;
223  const groupUrl = `${base}/groups/${encodeURIComponent(pinned.group_id)}`;
224  const result: SyncResult = {
225    ok: false,
226    namespace: req.namespace,
227    group: pinned.group_name,
228    members: 0,
229    added: [],
230    dropped: [],
231    seats: { freed: [], not_found: [], kept: [], not_members: [], failed: null },
232    refusal: null,
233    cloudflare_status: null,
234    conflict: false,
235  };
236  const fail = (refusal: string, status: number | null = null): SyncResult => ({ ...result, refusal, cloudflare_status: status });
237  const conflict = (refusal: string): SyncResult => ({ ...result, refusal, conflict: true });
238
239  let current: { name?: unknown; include?: unknown; exclude?: unknown; require?: unknown };
240  try {
241    current = ((await cfCall(fetchImpl, token, "GET", groupUrl, "the group read", ACCESS_SYNC_PERMISSION.group)).result ?? {}) as typeof current;
242  } catch (err) {
243    return fail(`the group could not be read, so nothing was written: ${errText(err)}`, err instanceof CfWriteError ? err.status : null);
244  }
245  if (current.name !== pinned.group_name) {
246    return conflict(`the group's name is ${JSON.stringify(current.name)}, not the pinned ${JSON.stringify(pinned.group_name)}, so nothing was written; the seat checks the pin in access_sync_groups`);
247  }
248  const include = Array.isArray(current.include) ? current.include : [];
249  const before = new Set<string>();
250  for (const rule of include) {
251    const email = ruleEmail(rule);
252    if (!email) return conflict("the group holds an include rule that is not a single email, which the sync would erase, so nothing was written; remove it in Cloudflare or pin another group");
253    before.add(email);
254  }
255  result.members = before.size;
256
257  const body = {
258    name: pinned.group_name,
259    include: req.members.map((email): Rule => ({ email: { email } })),
260    exclude: Array.isArray(current.exclude) ? current.exclude : [],
261    require: Array.isArray(current.require) ? current.require : [],
262  };
263  try {
264    await cfCall(fetchImpl, token, "PUT", groupUrl, "the group write", ACCESS_SYNC_PERMISSION.group, body);
265  } catch (err) {
266    return fail(`the group write was refused, so the group still holds its old list: ${errText(err)}`, err instanceof CfWriteError ? err.status : null);
267  }
268  const after = new Set(req.members);
269  result.ok = true;
270  result.members = after.size;
271  result.added = req.members.filter((e) => !before.has(e));
272  result.dropped = [...before].filter((e) => !after.has(e)).sort();
273
274  // Seats: only for people the app says it removed, who were in this group before the
275  // write and are not members now. A person on the list keeps their seat whatever `removed`
276  // says, and a person the group never held is not this key's to free.
277  const toFree = req.removed.filter((e) => before.has(e) && !after.has(e));
278  result.seats.kept = req.removed.filter((e) => after.has(e));
279  result.seats.not_members = req.removed.filter((e) => !before.has(e) && !after.has(e));
280  if (toFree.length === 0) return result;
281  try {
282    const seats = await seatsFor(fetchImpl, token, base, toFree);
283    result.seats.not_found = toFree.filter((e) => !seats.has(e));
284    const found = toFree.filter((e) => seats.has(e));
285    if (found.length) {
286      await cfCall(
287        fetchImpl,
288        token,
289        "PATCH",
290        `${base}/seats`,
291        "the seat release",
292        ACCESS_SYNC_PERMISSION.seats,
293        found.map((e) => ({ seat_uid: seats.get(e), access_seat: false, gateway_seat: false })),
294      );
295      result.seats.freed = found;
296    }
297  } catch (err) {
298    result.seats.failed = `the group was written, but the seats were not freed: ${errText(err)}`;
299  }
300  return result;
301}
302
303// The seat of each email, from the Zero Trust users list. The email filter is asked for and
304// the answer still matched exactly, because a filter the API ignores must not free the
305// wrong seat; the design could not confirm the filter from the docs.
306async function seatsFor(fetchImpl: FetchLike, token: string, base: string, emails: string[]): Promise<Map<string, string>> {
307  const out = new Map<string, string>();
308  for (const email of emails) {
309    for (let page = 1; ; page++) {
310      const u = new URL(`${base}/users`);
311      u.searchParams.set("email", email);
312      u.searchParams.set("page", String(page));
313      u.searchParams.set("per_page", String(USERS_PER_PAGE));
314      const env = await cfCall(fetchImpl, token, "GET", u.toString(), "the users read", ACCESS_SYNC_PERMISSION.users);
315      const rows = Array.isArray(env.result) ? env.result : [];
316      for (const row of rows) {
317        const r = row as { email?: unknown; seat_uid?: unknown };
318        if (normalizeEmail(r.email) === email && typeof r.seat_uid === "string" && r.seat_uid) out.set(email, r.seat_uid);
319      }
320      const pages = (env.result_info as { total_pages?: unknown } | undefined)?.total_pages;
321      const total = typeof pages === "number" && Number.isFinite(pages) ? pages : 1;
322      if (out.has(email) || page >= total) break;
323      if (page >= USER_PAGES) throw new Error(`the users list has more than ${USER_PAGES} pages of ${USERS_PER_PAGE} for ${email}`);
324    }
325  }
326  return out;
327}
328
329function errText(err: unknown): string {
330  return err instanceof Error ? err.message : String(err);
331}
332
333/** The token and account, or the words for what is missing. */
334function syncCredentials(env: Pick<Env, "CF_ACCESS_SYNC_TOKEN" | "CF_ACCOUNT_ID" | "R2_ACCOUNT_ID">): { ok: true; token: string; account: string } | { ok: false; reason: string } {
335  const token = env.CF_ACCESS_SYNC_TOKEN?.trim() ?? "";
336  const account = env.CF_ACCOUNT_ID?.trim() || env.R2_ACCOUNT_ID?.trim() || "";
337  const missing: string[] = [];
338  if (!token) missing.push("the Capsid Worker secret CF_ACCESS_SYNC_TOKEN is not set");
339  if (!account) missing.push("neither CF_ACCOUNT_ID nor R2_ACCOUNT_ID is set");
340  return missing.length ? { ok: false, reason: `${missing.join("; ")}, so nothing was called` } : { ok: true, token, account };
341}
342
343export interface SyncDeps {
344  fetch: FetchLike;
345  now: Date;
346  pinned: (db: D1Database, namespace: string) => Promise<PinnedGroup | null>;
347}
348
349const defaultDeps = (): SyncDeps => ({ fetch: (input, init) => fetch(input, init), now: new Date(), pinned: readPinnedGroup });
350
351/**
352 * POST /ops/access-sync. The order is the gate's: who, then what, then the rate, then the
353 * pin, then Cloudflare, so a refused caller spends nothing and reaches nothing.
354 */
355export async function handleAccessSync(request: Request, env: Env, deps: SyncDeps = defaultDeps()): Promise<Response> {
356  const caller = await resolveAgent(request, env);
357  if (!caller) return textResponse("unauthorized: the app's own agent key is required", 401, { "WWW-Authenticate": 'Bearer realm="capsid-operator"' });
358  const bounded = await readBoundedText(request, MAX_ACCESS_SYNC_BYTES);
359  if (!bounded.ok) return textResponse(`request too large: exceeds ${MAX_ACCESS_SYNC_BYTES} bytes`, 413);
360  let body: unknown;
361  try {
362    body = JSON.parse(bounded.text);
363  } catch {
364    return textResponse("the body must be JSON", 400);
365  }
366  const namespace = (body as { namespace?: unknown } | null)?.namespace;
367  if (typeof namespace !== "string" || namespace === "") return textResponse("namespace is required", 400);
368  const refusal = syncCallerRefusal(caller.agent, namespace);
369  if (refusal) return textResponse(refusal, 403);
370  const parsed = parseSyncBody(body);
371  if (!parsed.ok) return textResponse(parsed.refusal, 400);
372  const rate = await checkRate(env.APP_KV, caller.agent.actor, deps.now, ACCESS_SYNC_LIMIT);
373  if (!rate.allowed) {
374    return rate.window === "unavailable"
375      ? textResponse(`the sync rate limit could not be read, so the sync is refused: ${rate.detail}`, 503, { "Retry-After": "60" })
376      : textResponse(`at most ${rate.limit} syncs per ${rate.window} per key; try again later`, 429, { "Retry-After": rate.window === "hour" ? "3600" : "86400" });
377  }
378  const pinned = await deps.pinned(env.DB, namespace);
379  if (!pinned) return textResponse(`no Access group is pinned for ${namespace}; the seat adds its row to access_sync_groups`, 409);
380  const creds = syncCredentials(env);
381  if (!creds.ok) return textResponse(creds.reason, 503);
382
383  const result = await runSync(deps.fetch, creds.token, creds.account, pinned, parsed.value);
384  await auditStatement(env.DB, caller.agent.actor, ACCESS_SYNC_ACTION, namespace, null, {
385    group_id: pinned.group_id,
386    group_name: pinned.group_name,
387    ok: result.ok,
388    members: result.members,
389    added: result.added,
390    dropped: result.dropped,
391    seats: result.seats,
392    refusal: result.refusal,
393    cloudflare_status: result.cloudflare_status,
394    conflict: result.conflict,
395  }).run();
396  // 200 written; 409 the group is not the pinned one or holds a rule the sync would erase
397  // (the seat fixes the pin, a retry cannot help); 502 Cloudflare refused or could not be
398  // reached (the app shows Waiting for Cloudflare and retries).
399  return Response.json(result, { status: result.ok ? 200 : result.conflict ? 409 : 502, headers: { "Cache-Control": "no-store" } });
400}