@volter/twin-cloudflare 0.1.0

package/src/cloudflare-twin.ts

@@ -0,0 +1,714 @@
+// Cloudflare API v4 control-plane twin. The modeled slice is intentionally generic:
+// account/zone discovery, remotely managed Cloudflare Tunnel provisioning, tunnel
+// configuration/token retrieval, a bounded zone DNS-record control-plane slice, and the
+// Workers/R2/Hyperdrive/Queues provisioning surface (cloudflare-provisioning.ts). It never
+// opens a tunnel, resolves DNS, executes a Worker, stores an R2 object, dials an origin, or
+// contacts Cloudflare. All state is the @volter/world-core projection.
+//
+// Grounding (read 2026-08-21, provisioning slice re-read 2026-08-23): Cloudflare's official
+// api-schemas OpenAPI 4.0.0 (commit 2ac8369e9b63dccacee1a2284e95bb819f05b307) and official
+// cloudflare-typescript SDK (commit faaaf89ed8064a9fb54de538ec3e89487f1302b0; npm cloudflare@7.1.0).
+import { isIP } from 'node:net';
+import { resolveSubjectId } from '@volter/world-core';
+import {
+  CLOUDFLARE_RESOURCE_TYPES,
+  deterministicHex,
+  failure,
+  headers,
+  isResponse,
+  mint,
+  noRoute,
+  paginate,
+  parseBody,
+  readOnly,
+  row,
+  rows,
+  SERVICE,
+  scopeMissing,
+  success,
+  write,
+  callerEmail,
+  audit,
+  type CloudflareRequest,
+  type CloudflareResponse,
+  type CloudflareResourceType,
+  type Row,
+} from './cloudflare-common.ts';
+import { CLOUDFLARE_PROVISIONING_SURFACE, handleProvisioningRoute } from './cloudflare-provisioning.ts';
+
+export { CLOUDFLARE_RESOURCE_TYPES } from './cloudflare-common.ts';
+export type { CloudflareRequest, CloudflareResponse, CloudflareResourceType } from './cloudflare-common.ts';
+
+const DNS_TYPES = new Set([
+  'A', 'AAAA', 'CAA', 'CERT', 'CNAME', 'DNSKEY', 'DS', 'HTTPS', 'LOC', 'MX', 'NAPTR',
+  'NS', 'OPENPGPKEY', 'PTR', 'SMIMEA', 'SRV', 'SSHFP', 'SVCB', 'TLSA', 'TXT', 'URI',
+]);
+const PROXIABLE_TYPES = new Set(['A', 'AAAA', 'CNAME']);
+
+/** Tunnel configurations have no independent vendor id; Cloudflare addresses them by this pair. */
+export function cloudflareConfigurationID(accountID: string, tunnelID: string): string {
+  return `${accountID}:${tunnelID}`;
+}
+
+function accountView(value: Row): Record<string, unknown> {
+  return {
+    id: value.id,
+    name: value.name,
+    type: value.account_type ?? 'standard',
+    created_on: value.created_on,
+    settings: value.settings ?? { enforce_twofactor: false },
+  };
+}
+
+function zoneView(value: Row, root?: string): Record<string, unknown> {
+  const account = row('account', String(value.account_id), root);
+  return {
+    id: value.id,
+    name: value.name,
+    status: value.status ?? 'active',
+    paused: value.paused ?? false,
+    type: value.zone_type ?? 'full',
+    development_mode: value.development_mode ?? 0,
+    name_servers: value.name_servers ?? ['ada.ns.cloudflare.com', 'bob.ns.cloudflare.com'],
+    original_name_servers: value.original_name_servers ?? [],
+    original_registrar: value.original_registrar ?? null,
+    original_dnshost: value.original_dnshost ?? null,
+    modified_on: value.modified_on,
+    created_on: value.created_on,
+    activated_on: value.activated_on ?? value.created_on,
+    account: { id: value.account_id, name: account?.name ?? '' },
+    meta: value.meta ?? { step: 4, custom_certificate_quota: 0, page_rule_quota: 3, phishing_detected: false },
+    owner: { id: null, type: 'user', email: null },
+    tenant: { id: null, name: null },
+    tenant_unit: { id: null },
+    permissions: [],
+    plan: { id: '0feeeeeeeeeeeeeeeeeeeeeeeeeeeeee', name: 'Free Website', price: 0, currency: 'USD', frequency: '' },
+  };
+}
+
+function tunnelView(value: Row): Record<string, unknown> {
+  return {
+    id: value.id,
+    account_tag: value.account_id,
+    config_src: value.config_src ?? 'cloudflare',
+    connections: [],
+    conns_active_at: null,
+    conns_inactive_at: null,
+    created_at: value.created_at,
+    deleted_at: value.deleted_at ?? null,
+    metadata: value.metadata ?? {},
+    name: value.name,
+    remote_config: value.config_src !== 'local',
+    status: value.status ?? 'inactive',
+    tun_type: 'cfd_tunnel',
+  };
+}
+
+function configurationView(value: Row): Record<string, unknown> {
+  return {
+    account_id: value.account_id,
+    tunnel_id: value.tunnel_id,
+    source: 'cloudflare',
+    version: value.version ?? 1,
+    created_at: value.created_at,
+    config: value.config ?? { ingress: [] },
+  };
+}
+
+function dnsView(value: Row): Record<string, unknown> {
+  const recordType = String(value.record_type);
+  return {
+    id: value.id,
+    zone_id: value.zone_id,
+    zone_name: value.zone_name,
+    name: value.name,
+    type: recordType,
+    ...(typeof value.content === 'string' ? { content: value.content } : {}),
+    ...(value.data !== null && typeof value.data === 'object' && !Array.isArray(value.data) ? { data: value.data } : {}),
+    ...(typeof value.priority === 'number' ? { priority: value.priority } : {}),
+    ...(typeof value.private_routing === 'boolean' ? { private_routing: value.private_routing } : {}),
+    proxiable: PROXIABLE_TYPES.has(recordType),
+    proxied: value.proxied ?? false,
+    ttl: value.ttl ?? 1,
+    settings: value.settings ?? {},
+    meta: value.meta ?? {},
+    comment: value.comment ?? null,
+    tags: value.tags ?? [],
+    created_on: value.created_on,
+    modified_on: value.modified_on,
+  };
+}
+
+function validTunnelSecret(value: unknown): boolean {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4 !== 0) return false;
+  const decoded = Buffer.from(value, 'base64');
+  return decoded.length >= 32 && decoded.toString('base64') === value;
+}
+
+function validAuth(req: CloudflareRequest): boolean {
+  const h = headers(req.headers);
+  return /^Bearer\s+\S+$/i.test(h.authorization ?? '') || Boolean(h['x-auth-key'] && h['x-auth-email']);
+}
+
+// ── Who is calling, and the account audit log ───────────────────────────────────────────────────────────────────────
+// A user API token minted at POST /twin/users/{email}/tokens (Cloudflare mints them in its dashboard) names its user; a
+// write made with it is that user's in the account's audit log, as Cloudflare attributes an API token's changes to the
+// user who owns it. Any other token names no one, and its changes are logged with an empty actor.
+// GET /accounts/{id}/audit_logs: newest first unless direction=asc, bounded by since and before (ISO instants).
+function auditLogRoute(req: CloudflareRequest, method: string, url: URL, parts: string[]): CloudflareResponse | null {
+  if (method !== 'GET' || parts[0] !== 'accounts' || !parts[1] || parts[2] !== 'audit_logs' || parts.length !== 3) return null;
+  if (!row('account', parts[1], req.root)) return scopeMissing('account', parts[1]);
+  const since = url.searchParams.get('since'), before = url.searchParams.get('before');
+  let values = rows('audit_log', req.root).filter((x) => x.account_id === parts[1] && (!since || String(x.when) >= since) && (!before || String(x.when) < before))
+    .sort((a, b) => String(a.when).localeCompare(String(b.when)));
+  if (url.searchParams.get('direction') !== 'asc') values = values.reverse();
+  const page = paginate(values.map(({ id, when, action, actor, interface: via, resource, oldValue, newValue, metadata, owner }) => ({ id, when, action, actor, interface: via, resource, oldValue, newValue, metadata, owner })), url, 100, 1000);
+  return success(page.result, page.info);
+}
+
+async function bootstrap(req: CloudflareRequest, body: Record<string, unknown>): Promise<CloudflareResponse> {
+  const blocked = readOnly(req);
+  if (blocked) return blocked;
+  const observedAt = req.occurredAt ?? new Date().toISOString();
+  const accounts = Array.isArray(body.accounts) ? body.accounts : [];
+  const zones = Array.isArray(body.zones) ? body.zones : [];
+  for (const value of accounts) {
+    if (!value || typeof value !== 'object') return failure(400, 1004, 'Each bootstrap account must be an object');
+    const item = value as Record<string, unknown>;
+    if (typeof item.id !== 'string' || !/^[a-f0-9]{32}$/.test(item.id) || typeof item.name !== 'string') {
+      return failure(400, 1004, 'Bootstrap accounts require a 32-character lowercase hex id and name');
+    }
+    await write('account', item.id, 'account.observe', {
+      name: item.name,
+      account_type: item.type === 'enterprise' ? 'enterprise' : 'standard',
+      created_on: item.created_on ?? observedAt,
+      settings: item.settings ?? { enforce_twofactor: false },
+    }, req);
+  }
+  for (const value of zones) {
+    if (!value || typeof value !== 'object') return failure(400, 1004, 'Each bootstrap zone must be an object');
+    const item = value as Record<string, unknown>;
+    if (typeof item.id !== 'string' || !/^[a-f0-9]{32}$/.test(item.id) || typeof item.name !== 'string' || typeof item.account_id !== 'string') {
+      return failure(400, 1004, 'Bootstrap zones require id, name, and account_id');
+    }
+    if (!row('account', item.account_id, req.root)) return scopeMissing('account', item.account_id);
+    await write('zone', item.id, 'zone.observe', {
+      name: item.name.toLowerCase(),
+      account_id: item.account_id,
+      status: item.status ?? 'active',
+      paused: item.paused ?? false,
+      zone_type: item.type ?? 'full',
+      created_on: item.created_on ?? observedAt,
+      modified_on: item.modified_on ?? observedAt,
+      activated_on: item.activated_on ?? observedAt,
+      // the zone's name servers are Cloudflare's answer for it, so the TREE holds them and the view projects
+      // them — a refresh that reads this twin's own wire then observes exactly what the write stored
+      // (protocol 2 shape parity; they used to exist only in the view's default)
+      name_servers: item.name_servers ?? ['ada.ns.cloudflare.com', 'bob.ns.cloudflare.com'],
+      original_name_servers: item.original_name_servers ?? [],
+    }, req);
+  }
+  // Members with their user's two-factor state: the user's own record at Cloudflare, which no account API sets.
+  const members = Array.isArray(body.members) ? body.members : [];
+  for (const value of members) {
+    const item = (value ?? {}) as Record<string, unknown>;
+    if (typeof item.account_id !== 'string' || !row('account', item.account_id, req.root)) return failure(400, 1004, 'Bootstrap members require an existing account_id');
+    if (typeof item.email !== 'string' || !Array.isArray(item.roles)) return failure(400, 1004, 'Bootstrap members require an email and role names');
+    const roleIDs = (item.roles as unknown[]).map((name) => ROLES.find((r) => r.name === name)?.id);
+    if (!roleIDs.length || roleIDs.some((id) => !id)) return failure(400, 1004, `Bootstrap member roles must be among: ${ROLES.map((r) => r.name).join(', ')}`);
+    await write('account_member', mint('account_member', `${item.account_id}:${item.email}`, req.root), 'account_member.observe', { account_id: item.account_id, email: item.email, role_ids: roleIDs, status: item.status === 'pending' ? 'pending' : 'accepted', two_factor: item.two_factor === true }, req);
+  }
+  // A user's API tokens that already exist when the World starts (a token a person made before the story), as the minting
+  // door records one: {email, token}
+  const userTokens = Array.isArray(body.user_tokens) ? body.user_tokens : [];
+  for (const value of userTokens) {
+    const item = (value ?? {}) as Record<string, unknown>;
+    if (typeof item.email !== 'string' || typeof item.token !== 'string' || !item.token) return failure(400, 1004, 'Bootstrap user_tokens require an email and a token');
+    await write('user_token', item.token, 'user_token.observe', { token: item.token, email: item.email, created_on: req.occurredAt ?? new Date().toISOString() }, req);
+  }
+  return success({ accounts: accounts.length, zones: zones.length, members: members.length, user_tokens: userTokens.length });
+}
+
+function dnsValidation(body: Record<string, unknown>, zoneID: string, root?: string, ignoreID?: string): CloudflareResponse | null {
+  if (typeof body.name !== 'string' || !body.name.trim()) return failure(400, 1004, 'DNS Validation Error: name is required');
+  const type = typeof body.type === 'string' ? body.type.toUpperCase() : '';
+  if (!DNS_TYPES.has(type)) return failure(400, 1004, 'DNS Validation Error: invalid record type');
+  const hasContent = typeof body.content === 'string' && body.content.length > 0;
+  const hasData = body.data !== null && typeof body.data === 'object' && !Array.isArray(body.data);
+  if (body.content !== undefined && !hasContent) return failure(400, 1004, 'DNS Validation Error: content must be a nonempty string');
+  if (body.data !== undefined && !hasData) return failure(400, 1004, 'DNS Validation Error: data must be an object');
+  if (type === 'A' && (!hasContent || isIP(String(body.content)) !== 4)) {
+    return failure(400, 1004, 'DNS Validation Error: A content must be a valid IPv4 address');
+  }
+  if (type === 'AAAA' && (!hasContent || isIP(String(body.content)) !== 6)) {
+    return failure(400, 1004, 'DNS Validation Error: AAAA content must be a valid IPv6 address');
+  }
+  if (type === 'CAA' && hasData) {
+    const data = body.data as Record<string, unknown>;
+    if (data.flags !== undefined && (!Number.isInteger(data.flags) || Number(data.flags) < 0 || Number(data.flags) > 255)) {
+      return failure(400, 1004, 'DNS Validation Error: CAA data.flags must be an integer between 0 and 255');
+    }
+    if (data.tag !== undefined && typeof data.tag !== 'string') return failure(400, 1004, 'DNS Validation Error: CAA data.tag must be a string');
+    if (data.value !== undefined && typeof data.value !== 'string') return failure(400, 1004, 'DNS Validation Error: CAA data.value must be a string');
+  }
+  if (body.priority !== undefined && (!Number.isInteger(body.priority) || Number(body.priority) < 0 || Number(body.priority) > 65535)) {
+    return failure(400, 1004, 'DNS Validation Error: priority must be an integer between 0 and 65535');
+  }
+  if (body.private_routing !== undefined && typeof body.private_routing !== 'boolean') {
+    return failure(400, 1004, 'DNS Validation Error: private_routing must be a boolean');
+  }
+  const ttl = body.ttl ?? 1;
+  if (typeof ttl !== 'number' || (ttl !== 1 && (ttl < 60 || ttl > 86400))) return failure(400, 1004, 'DNS Validation Error: TTL must be 1 or between 60 and 86400');
+  const sameName = rows('dns_record', root).filter((item) => item.zone_id === zoneID && item.name === body.name && item.id !== ignoreID);
+  if ((type === 'CNAME' && sameName.length > 0) || (type !== 'CNAME' && sameName.some((item) => item.record_type === 'CNAME'))) {
+    return failure(400, 81053, 'An A, AAAA, or CNAME record with that host already exists.');
+  }
+  if ((type === 'NS' && sameName.length > 0) || (type !== 'NS' && sameName.some((item) => item.record_type === 'NS'))) {
+    return failure(400, 81053, 'An NS record cannot coexist with another record at that name.');
+  }
+  return null;
+}
+
+// ── Account members and zone security settings ─────────────────────────────────────────────────────────────────
+// The account's roles are Cloudflare's built-in ones (a fixed, deterministic set); a member holds role ids and has a
+// status, and its user's two-factor state is Cloudflare's own record of the person (the bootstrap seeds it: nothing in
+// the API lets an account set it). Zone settings are the two security settings modeled here, with Cloudflare's
+// defaults until changed.
+const ROLES = [
+  { name: 'Super Administrator - All Privileges', description: 'Can edit any Cloudflare setting, make purchases, update billing, and manage memberships.' },
+  { name: 'Administrator', description: 'Can access the full account, except for membership management and billing.' },
+  { name: 'Administrator Read Only', description: 'Can access the full account in read-only mode.' },
+  { name: 'Workers Admin', description: 'Can edit Workers, Workers routes and Workers KV, and deploy Workers.' },
+].map((r) => ({ ...r, id: deterministicHex(`cf-role:${r.name}`, 32), permissions: {} }));
+const ZONE_SETTINGS: Record<string, { default: string; values: string[] }> = {
+  min_tls_version: { default: '1.0', values: ['1.0', '1.1', '1.2', '1.3'] },
+  always_use_https: { default: 'off', values: ['on', 'off'] },
+};
+function memberView(value: Row): Record<string, unknown> {
+  return {
+    id: value.id, email: value.email, status: value.status ?? 'pending',
+    user: { id: value.user_id ?? null, email: value.email, first_name: null, last_name: null, two_factor_authentication_enabled: value.two_factor === true },
+    roles: ((value.role_ids ?? []) as string[]).map((id) => ROLES.find((r) => r.id === id)).filter(Boolean),
+  };
+}
+async function membersRoute(req: CloudflareRequest, method: string, url: URL, parts: string[]): Promise<CloudflareResponse | null> {
+  if (parts[0] !== 'accounts' || !parts[1] || (parts[2] !== 'members' && parts[2] !== 'roles')) return null;
+  const accountID = parts[1];
+  if (!row('account', accountID, req.root)) return scopeMissing('account', accountID);
+  if (parts[2] === 'roles' && parts.length === 3 && method === 'GET') { const page = paginate(ROLES, url, 20, 50); return success(page.result, page.info); }
+  const members = () => rows('account_member', req.root).filter((m) => m.account_id === accountID);
+  if (parts[2] === 'members' && parts.length === 3 && method === 'GET') {
+    let values = members();
+    const status = url.searchParams.get('status');
+    if (status) values = values.filter((m) => (m.status ?? 'pending') === status);
+    const page = paginate(values.map(memberView), url, 20, 50);
+    return success(page.result, page.info);
+  }
+  if (parts[2] === 'members' && parts.length === 3 && method === 'POST') {
+    const blocked = readOnly(req); if (blocked) return blocked;
+    const body = parseBody(req); if (isResponse(body)) return body;
+    if (typeof body.email !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(body.email)) return failure(400, 1001, 'A valid email is required');
+    const roleIDs = Array.isArray(body.roles) ? body.roles.map((r: unknown) => typeof r === 'string' ? r : (r as { id?: string })?.id) : [];
+    if (!roleIDs.length || roleIDs.some((id: unknown) => !ROLES.some((r) => r.id === id))) return failure(400, 1001, 'roles must name at least one role of the account');
+    if (members().some((m) => m.email === body.email)) return failure(400, 1001, 'That user is already a member of the account');
+    const id = mint('account_member', `${accountID}:${body.email}`, req.root);
+    await write('account_member', id, 'account_member.create', { account_id: accountID, email: body.email, role_ids: roleIDs, status: body.status === 'accepted' ? 'accepted' : 'pending', two_factor: false }, req);
+    await audit(req, accountID, { type: 'add', resource: { type: 'member', id }, newValue: { email: body.email, roles: roleIDs } });
+    return success(memberView(row('account_member', id, req.root)!));
+  }
+  const member = parts[3] ? members().find((m) => m.id === parts[3]) : undefined;
+  if (parts[2] === 'members' && parts.length === 4) {
+    if (!member) return failure(404, 1003, 'Member not found');
+    if (method === 'GET') return success(memberView(member));
+    if (method === 'DELETE') {
+      const blocked = readOnly(req); if (blocked) return blocked;
+      await write('account_member', member.id, 'account_member.delete', { deleted: true }, req);
+      await audit(req, accountID, { type: 'delete', resource: { type: 'member', id: String(member.id) }, oldValue: { email: member.email, roles: member.role_ids } });
+      return success({ id: member.id });
+    }
+  }
+  return null;
+}
+async function zoneSettingRoute(req: CloudflareRequest, method: string, parts: string[]): Promise<CloudflareResponse | null> {
+  if (parts[0] !== 'zones' || !parts[1] || parts[2] !== 'settings' || parts.length !== 4) return null;
+  const zone = row('zone', parts[1], req.root);
+  if (!zone) return scopeMissing('zone', parts[1]);
+  const def = ZONE_SETTINGS[parts[3]!];
+  if (!def) return null; // a real setting the twin does not model: the router's unmodeled-route answer, never a made-up refusal
+  const id = `${parts[1]}:${parts[3]}`;
+  const view = () => { const v = row('zone_setting', id, req.root); return { id: parts[3], value: v?.value ?? def.default, editable: true, modified_on: v?.modified_on ?? null }; };
+  if (method === 'GET') return success(view());
+  if (method === 'PATCH') {
+    const blocked = readOnly(req); if (blocked) return blocked;
+    const body = parseBody(req); if (isResponse(body)) return body;
+    if (typeof body.value !== 'string' || !def.values.includes(body.value)) return failure(400, 1007, `Invalid value for zone setting ${parts[3]}`);
+    const before = view().value;
+    await write('zone_setting', id, 'zone_setting.update', { zone_id: parts[1], setting: parts[3], value: body.value, modified_on: req.occurredAt ?? new Date().toISOString() }, req);
+    await audit(req, String(zone.account_id), { type: 'update', resource: { type: 'zone_setting', id: parts[3]! }, oldValue: before, newValue: body.value, metadata: { zone_id: parts[1], zone_name: zone.name, setting: parts[3] } });
+    return success(view());
+  }
+  return null;
+}
+
+/** Main protocol handler. Unknown/unmodeled routes fail loudly with a Cloudflare v4 envelope. */
+export async function handleCloudflareTwinRequest(req: CloudflareRequest): Promise<CloudflareResponse> {
+  const method = req.method.toUpperCase();
+  // The vendor default and world injector carry /client/v4; a public baseURL override may not.
+  // Both spellings reach the same router without modifying the SDK or its generated resources.
+  const wirePath = req.path.replace(/^\/client\/v4(?=\/|\?|$)/, '') || '/';
+  const url = new URL(wirePath, 'http://cloudflare.twin');
+  const parts = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+  // protocol 2: after a landing adopted Cloudflare's id for an account, a zone, a tunnel or a record, a caller on a
+  // branch may still address it by the local id — resolved through the alias map once, here at the boundary
+  if (parts[0] === 'accounts' && parts[1]) parts[1] = resolveSubjectId(SERVICE, 'account', parts[1], req.root);
+  if (parts[0] === 'zones' && parts[1]) parts[1] = resolveSubjectId(SERVICE, 'zone', parts[1], req.root);
+  if (parts[0] === 'accounts' && parts[2] === 'cfd_tunnel' && parts[3]) parts[3] = resolveSubjectId(SERVICE, 'cloudflare_tunnel', parts[3], req.root);
+  if (parts[0] === 'zones' && parts[2] === 'dns_records' && parts[3]) parts[3] = resolveSubjectId(SERVICE, 'dns_record', parts[3], req.root);
+
+  if (!validAuth(req)) return failure(403, 10000, 'Authentication error');
+
+  // POST /twin/users/{email}/tokens: a user API token, as a user mints one in the dashboard.
+  if (method === 'POST' && parts[0] === 'twin' && parts[1] === 'users' && parts[2] && parts[3] === 'tokens' && parts.length === 4) {
+    const blocked = readOnly(req); if (blocked) return blocked;
+    if (!/^[^@\s]+@[^@\s]+$/.test(parts[2])) return failure(400, 1001, 'A valid email is required');
+    const token = `cf-${deterministicHex(`token:${parts[2]}:${rows('user_token', req.root).length}`, 40)}`;
+    await write('user_token', token, 'user_token.create', { token, email: parts[2], created_on: req.occurredAt ?? new Date().toISOString() }, req);
+    // A user's token is logged in each account the user is a member of.
+    for (const m of rows('account_member', req.root).filter((x) => x.email === parts[2])) await audit({ ...req, headers: { authorization: `Bearer ${token}` } }, String(m.account_id), { type: 'create', resource: { type: 'token', id: token.slice(0, 12) }, newValue: { owner: parts[2] } });
+    return success({ token, email: parts[2] });
+  }
+  // DELETE /user/tokens/{id}: a user revokes one of their own API tokens (the id is the first 12 characters the audit
+  // log names). Logged in each account the user belongs to.
+  if (method === 'DELETE' && parts[0] === 'user' && parts[1] === 'tokens' && parts[2] && parts.length === 3) {
+    const blocked = readOnly(req); if (blocked) return blocked;
+    const email = callerEmail(req);
+    const token = rows('user_token', req.root).find((t) => String(t.token).slice(0, 12) === parts[2] && t.email === email);
+    if (!email || !token) return failure(404, 1003, 'Token not found');
+    // Logged before the delete: a token that revokes itself is still its user's while the entry is written.
+    for (const m of rows('account_member', req.root).filter((x) => x.email === email)) await audit(req, String(m.account_id), { type: 'delete', resource: { type: 'token', id: parts[2] }, oldValue: { owner: email } });
+    await write('user_token', String(token.token), 'user_token.delete', { deleted: true }, req);
+    return success({ id: parts[2] });
+  }
+  const logged = auditLogRoute(req, method, url, parts);
+  if (logged) return logged;
+
+  if (method === 'POST' && parts.join('/') === 'twin/bootstrap') {
+    const body = parseBody(req);
+    return isResponse(body) ? body : bootstrap(req, body);
+  }
+
+  const member = await membersRoute(req, method, url, parts);
+  if (member) return member;
+  const setting = await zoneSettingRoute(req, method, parts);
+  if (setting) return setting;
+
+  // Workers / R2 / Hyperdrive / Queues provisioning control plane.
+  const provisioned = await handleProvisioningRoute(req, method, url, parts);
+  if (provisioned) return provisioned;
+
+  if (parts[0] === 'accounts' && parts.length === 1 && method === 'GET') {
+    let values = rows('account', req.root).map(accountView);
+    const name = url.searchParams.get('name');
+    if (name) values = values.filter((item) => item.name === name);
+    const page = paginate(values, url, 20, 50);
+    return success(page.result, page.info);
+  }
+  if (parts[0] === 'accounts' && parts.length === 2 && method === 'GET') {
+    const value = row('account', parts[1]!, req.root);
+    return value ? success(accountView(value)) : scopeMissing('account', parts[1]!);
+  }
+
+  if (parts[0] === 'zones' && parts.length === 1 && method === 'GET') {
+    let values = rows('zone', req.root);
+    const accountID = url.searchParams.get('account.id');
+    const name = url.searchParams.get('name');
+    if (accountID) values = values.filter((item) => item.account_id === accountID);
+    if (name) values = values.filter((item) => item.name === name.toLowerCase());
+    const page = paginate(values.map((item) => zoneView(item, req.root)), url, 20, 50);
+    return success(page.result, page.info);
+  }
+  if (parts[0] === 'zones' && parts.length === 2 && method === 'GET') {
+    const value = row('zone', parts[1]!, req.root);
+    return value ? success(zoneView(value, req.root)) : scopeMissing('zone', parts[1]!);
+  }
+
+  if (parts[0] === 'accounts' && parts[2] === 'cfd_tunnel') {
+    const accountID = parts[1]!;
+    if (!row('account', accountID, req.root)) return scopeMissing('account', accountID);
+
+    if (parts.length === 3 && method === 'GET') {
+      let values = rows('cloudflare_tunnel', req.root, true).filter((item) => item.account_id === accountID);
+      const includeDeleted = url.searchParams.get('is_deleted');
+      if (includeDeleted === 'true') values = values.filter((item) => item.deleted === true);
+      if (includeDeleted === 'false') values = values.filter((item) => item.deleted !== true);
+      const name = url.searchParams.get('name');
+      const uuid = url.searchParams.get('uuid');
+      if (name) values = values.filter((item) => item.name === name);
+      if (uuid) values = values.filter((item) => item.id === uuid);
+      const page = paginate(values.map(tunnelView), url, 100, 1000);
+      return success(page.result, page.info);
+    }
+
+    if (parts.length === 3 && method === 'POST') {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      const body = parseBody(req);
+      if (isResponse(body)) return body;
+      if (typeof body.name !== 'string' || !body.name.trim()) return failure(400, 1004, 'name is required');
+      if (rows('cloudflare_tunnel', req.root).some((item) => item.account_id === accountID && item.name === body.name)) {
+        return failure(409, 1003, 'A tunnel with this name already exists');
+      }
+      const configSrc = body.config_src ?? 'cloudflare';
+      if (configSrc !== 'local' && configSrc !== 'cloudflare') return failure(400, 1004, 'config_src must be local or cloudflare');
+      if (body.tunnel_secret !== undefined) {
+        if (!validTunnelSecret(body.tunnel_secret)) return failure(400, 1004, 'tunnel_secret must be canonical base64 encoding of at least 32 bytes');
+      }
+      const id = mint('cloudflare_tunnel', `${accountID}:${body.name}`, req.root);
+      const createdAt = req.occurredAt ?? new Date().toISOString();
+      await write('cloudflare_tunnel', id, 'tunnel.create', {
+        account_id: accountID,
+        name: body.name,
+        config_src: configSrc,
+        tunnel_secret: body.tunnel_secret ?? null,
+        created_at: createdAt,
+        deleted_at: null,
+        metadata: {},
+        status: 'inactive',
+      }, req);
+      return success(tunnelView(row('cloudflare_tunnel', id, req.root)!));
+    }
+
+    const tunnelID = parts[3];
+    if (!tunnelID) return failure(404, 7000, 'No route for that URI');
+    const tunnel = row('cloudflare_tunnel', tunnelID, req.root, true);
+    if (!tunnel || tunnel.account_id !== accountID || tunnel.deleted === true) return scopeMissing('tunnel', tunnelID);
+
+    if (parts.length === 4 && method === 'GET') return success(tunnelView(tunnel));
+    if (parts.length === 4 && method === 'PATCH') {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      const body = parseBody(req);
+      if (isResponse(body)) return body;
+      if (body.name !== undefined && (typeof body.name !== 'string' || !body.name.trim())) return failure(400, 1004, 'name must not be empty');
+      if (typeof body.name === 'string' && rows('cloudflare_tunnel', req.root).some((item) =>
+        item.account_id === accountID && item.id !== tunnelID && item.name === body.name)) {
+        return failure(409, 1003, 'A tunnel with this name already exists');
+      }
+      if (body.tunnel_secret !== undefined && !validTunnelSecret(body.tunnel_secret)) {
+        return failure(400, 1004, 'tunnel_secret must be canonical base64 encoding of at least 32 bytes');
+      }
+      await write('cloudflare_tunnel', tunnelID, 'tunnel.update', {
+        account_id: accountID,
+        ...(body.name !== undefined ? { name: body.name } : {}),
+        ...(body.tunnel_secret !== undefined ? { tunnel_secret: body.tunnel_secret } : {}),
+      }, req);
+      return success(tunnelView(row('cloudflare_tunnel', tunnelID, req.root)!));
+    }
+    if (parts.length === 4 && method === 'DELETE') {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      const deletedAt = req.occurredAt ?? new Date().toISOString();
+      await write('cloudflare_tunnel', tunnelID, 'tunnel.delete', { account_id: accountID, deleted: true, deleted_at: deletedAt }, req);
+      return success(tunnelView(row('cloudflare_tunnel', tunnelID, req.root, true)!));
+    }
+    if (parts.length === 5 && parts[4] === 'token' && method === 'GET') {
+      const token = `twin.${Buffer.from(JSON.stringify({ a: accountID, t: tunnelID })).toString('base64url')}.${deterministicHex(`${accountID}:${tunnelID}:token`, 48)}`;
+      return success(token);
+    }
+    if (parts.length === 5 && parts[4] === 'configurations') {
+      if (tunnel.config_src !== 'cloudflare') return failure(400, 1004, 'Tunnel is not remotely managed');
+      const current = rows('tunnel_configuration', req.root).find((item) => item.tunnel_id === tunnelID && item.account_id === accountID);
+      if (method === 'GET') {
+        if (!current) return failure(404, 1001, 'Tunnel configuration not found');
+        return success(configurationView(current));
+      }
+      if (method === 'PUT') {
+        const blocked = readOnly(req);
+        if (blocked) return blocked;
+        const body = parseBody(req);
+        if (isResponse(body)) return body;
+        const config = body.config;
+        if (!config || typeof config !== 'object' || Array.isArray(config)) return failure(400, 1004, 'config is required');
+        const ingress = (config as Record<string, unknown>).ingress;
+        if (!Array.isArray(ingress) || ingress.length === 0) return failure(400, 1004, 'At least one ingress rule is required');
+        for (const rule of ingress) {
+          const value = rule as Record<string, unknown> | null;
+          if (!value || typeof value !== 'object' || typeof value.hostname !== 'string'
+            || !value.hostname || typeof value.service !== 'string' || !value.service) {
+            return failure(400, 1004, 'Each ingress rule requires nonempty hostname and service strings');
+          }
+        }
+        const id = current?.id ?? cloudflareConfigurationID(accountID, tunnelID);
+        await write('tunnel_configuration', id, 'tunnel_configuration.update', {
+          account_id: accountID,
+          tunnel_id: tunnelID,
+          source: 'cloudflare',
+          version: Number(current?.version ?? 0) + 1,
+          created_at: current?.created_at ?? (req.occurredAt ?? new Date().toISOString()),
+          config,
+        }, req);
+        return success(configurationView(row('tunnel_configuration', id, req.root)!));
+      }
+    }
+    return failure(404, 7000, 'No route for that URI');
+  }
+
+  if (parts[0] === 'zones' && parts[2] === 'dns_records') {
+    const zoneID = parts[1]!;
+    const zone = row('zone', zoneID, req.root);
+    if (!zone) return scopeMissing('zone', zoneID);
+    if (parts.length === 3 && method === 'GET') {
+      let values = rows('dns_record', req.root).filter((item) => item.zone_id === zoneID);
+      const type = url.searchParams.get('type');
+      const name = url.searchParams.get('name');
+      const content = url.searchParams.get('content');
+      if (type) values = values.filter((item) => item.record_type === type.toUpperCase());
+      if (name) values = values.filter((item) => item.name === name.toLowerCase());
+      if (content) values = values.filter((item) => item.content === content);
+      const page = paginate(values.map(dnsView), url, 100, 5_000_000);
+      return success(page.result, page.info);
+    }
+    if (parts.length === 3 && method === 'POST') {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      const body = parseBody(req);
+      if (isResponse(body)) return body;
+      if (typeof body.name === 'string') body.name = body.name.toLowerCase();
+      const invalid = dnsValidation(body, zoneID, req.root);
+      if (invalid) return invalid;
+      const id = mint('dns_record', `${zoneID}:${body.type}:${body.name}:${JSON.stringify(body.content ?? body.data)}`, req.root);
+      const at = req.occurredAt ?? new Date().toISOString();
+      await write('dns_record', id, 'dns_record.create', {
+        zone_id: zoneID,
+        zone_name: zone.name,
+        name: body.name,
+        record_type: String(body.type).toUpperCase(),
+        ...(body.content !== undefined ? { content: body.content } : {}),
+        ...(body.data !== undefined ? { data: body.data } : {}),
+        ...(body.priority !== undefined ? { priority: body.priority } : {}),
+        ...(body.private_routing !== undefined ? { private_routing: body.private_routing } : {}),
+        ttl: body.ttl ?? 1,
+        proxied: PROXIABLE_TYPES.has(String(body.type).toUpperCase()) ? body.proxied === true : false,
+        settings: body.settings ?? {},
+        meta: {},
+        comment: body.comment ?? null,
+        tags: body.tags ?? [],
+        created_on: at,
+        modified_on: at,
+      }, req);
+      return success(dnsView(row('dns_record', id, req.root)!));
+    }
+    const recordID = parts[3];
+    if (!recordID) return failure(404, 7000, 'No route for that URI');
+    // These are real collection subresources in Cloudflare's OpenAPI, but remain explicit
+    // manifest todos. Fail as an unmodeled route, never reinterpret their names as record IDs.
+    if (['batch', 'export', 'import', 'scan', 'usage'].includes(recordID)) return failure(404, 7000, 'No route for that URI');
+    const record = row('dns_record', recordID, req.root);
+    if (!record || record.zone_id !== zoneID) return failure(404, 81044, 'DNS Record not found');
+    if (parts.length === 4 && method === 'GET') return success(dnsView(record));
+    if (parts.length === 4 && (method === 'PUT' || method === 'PATCH')) {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      const body = parseBody(req);
+      if (isResponse(body)) return body;
+      if (method === 'PUT' && (body.name === undefined || body.type === undefined || body.ttl === undefined)) {
+        return failure(400, 1004, 'DNS Validation Error: PUT requires name, type, and ttl');
+      }
+      const merged: Record<string, unknown> = method === 'PUT' ? {
+        name: body.name,
+        type: body.type,
+        ...(body.content !== undefined ? { content: body.content } : {}),
+        ...(body.data !== undefined ? { data: body.data } : {}),
+        ...(body.priority !== undefined ? { priority: body.priority } : {}),
+        ...(body.private_routing !== undefined ? { private_routing: body.private_routing } : {}),
+        ttl: body.ttl,
+        proxied: body.proxied ?? false,
+      } : {
+        name: body.name ?? record.name,
+        type: body.type ?? record.record_type,
+        ...(body.content !== undefined ? { content: body.content } : typeof record.content === 'string' ? { content: record.content } : {}),
+        ...(body.data !== undefined ? { data: body.data } : record.data !== null && typeof record.data === 'object' && !Array.isArray(record.data) ? { data: record.data } : {}),
+        ...(body.priority !== undefined ? { priority: body.priority } : typeof record.priority === 'number' ? { priority: record.priority } : {}),
+        ...(body.private_routing !== undefined ? { private_routing: body.private_routing } : typeof record.private_routing === 'boolean' ? { private_routing: record.private_routing } : {}),
+        ttl: body.ttl ?? record.ttl,
+        proxied: body.proxied ?? record.proxied,
+      };
+      if (typeof merged.name === 'string') merged.name = merged.name.toLowerCase();
+      const invalid = dnsValidation(merged, zoneID, req.root, recordID);
+      if (invalid) return invalid;
+      const at = req.occurredAt ?? new Date().toISOString();
+      await write('dns_record', recordID, method === 'PUT' ? 'dns_record.replace' : 'dns_record.update', {
+        zone_id: zoneID,
+        name: merged.name,
+        record_type: String(merged.type).toUpperCase(),
+        content: merged.content ?? null,
+        data: merged.data ?? null,
+        priority: merged.priority ?? null,
+        private_routing: merged.private_routing ?? null,
+        ttl: merged.ttl,
+        proxied: PROXIABLE_TYPES.has(String(merged.type).toUpperCase()) ? merged.proxied === true : false,
+        ...(method === 'PUT' ? {
+          settings: body.settings ?? {},
+          comment: body.comment ?? null,
+          tags: body.tags ?? [],
+        } : {
+          ...(body.settings !== undefined ? { settings: body.settings } : {}),
+          ...(body.comment !== undefined ? { comment: body.comment } : {}),
+          ...(body.tags !== undefined ? { tags: body.tags } : {}),
+        }),
+        modified_on: at,
+      }, req);
+      return success(dnsView(row('dns_record', recordID, req.root)!));
+    }
+    if (parts.length === 4 && method === 'DELETE') {
+      const blocked = readOnly(req);
+      if (blocked) return blocked;
+      await write('dns_record', recordID, 'dns_record.delete', { zone_id: zoneID, deleted: true }, req);
+      return success({ id: recordID });
+    }
+  }
+
+  return noRoute();
+}
+
+export const CLOUDFLARE_CORE_SURFACE = [
+  'POST /twin/bootstrap',
+  'POST /twin/users/{email}/tokens',
+  'DELETE /user/tokens/{token_id}',
+  'GET /accounts/{account_id}/audit_logs',
+  'GET /accounts',
+  'GET /accounts/{account_id}',
+  'GET /zones',
+  'GET /zones/{zone_id}',
+  'GET /accounts/{account_id}/cfd_tunnel',
+  'POST /accounts/{account_id}/cfd_tunnel',
+  'GET /accounts/{account_id}/cfd_tunnel/{tunnel_id}',
+  'PATCH /accounts/{account_id}/cfd_tunnel/{tunnel_id}',
+  'DELETE /accounts/{account_id}/cfd_tunnel/{tunnel_id}',
+  'GET /accounts/{account_id}/cfd_tunnel/{tunnel_id}/token',
+  'GET /accounts/{account_id}/cfd_tunnel/{tunnel_id}/configurations',
+  'PUT /accounts/{account_id}/cfd_tunnel/{tunnel_id}/configurations',
+  'GET /zones/{zone_id}/dns_records',
+  'POST /zones/{zone_id}/dns_records',
+  'GET /zones/{zone_id}/dns_records/{dns_record_id}',
+  'PUT /zones/{zone_id}/dns_records/{dns_record_id}',
+  'PATCH /zones/{zone_id}/dns_records/{dns_record_id}',
+  'DELETE /zones/{zone_id}/dns_records/{dns_record_id}',
+  'GET /accounts/{account_id}/roles',
+  'GET /accounts/{account_id}/members',
+  'POST /accounts/{account_id}/members',
+  'GET /accounts/{account_id}/members/{member_id}',
+  'DELETE /accounts/{account_id}/members/{member_id}',
+  'GET /zones/{zone_id}/settings/{setting_id}',
+  'PATCH /zones/{zone_id}/settings/{setting_id}',
+] as const;
+
+export const CLOUDFLARE_ROUTER_SURFACE = [...CLOUDFLARE_CORE_SURFACE, ...CLOUDFLARE_PROVISIONING_SURFACE] as const;
+
+export function cloudflareTwinSnapshot(root?: string): { resourceTypes: readonly string[]; implementedEndpoints: readonly string[]; counts: Record<string, number> } {
+  return {
+    resourceTypes: CLOUDFLARE_RESOURCE_TYPES,
+    implementedEndpoints: CLOUDFLARE_ROUTER_SURFACE,
+    counts: Object.fromEntries(CLOUDFLARE_RESOURCE_TYPES.map((type) => [type, rows(type, root).length])),
+  };
+}