@volter/twin-cloudflare 0.1.0

package/src/cloudflare-r2.ts

@@ -0,0 +1,173 @@
+// R2's account-side state, shared by the control plane (cloudflare-provisioning.ts), the dashboard (screens/dashboard.tsx)
+// and the S3-compatible lane (../r2/): the R2 API tokens a person makes on the dashboard, which are the lane's
+// credentials, and the custom domains connected to a bucket, which are where the bucket is public.
+//
+// R2 API TOKENS (https://developers.cloudflare.com/r2/api/tokens/): "You can generate an API token to serve as the Access
+// Key for usage with existing S3-compatible SDKs"; a token is an Account API token ("Only users with the Super
+// Administrator role can view or create them. These tokens remain valid until manually revoked.") or a User API token
+// ("tied to your individual Cloudflare user"). Its permission is one of four, and "If you select the Object Read and
+// Write or Object Read permissions, you can scope your token to a set of buckets". Its S3 credentials: "Access Key ID: The
+// id of the API token. Secret Access Key: The SHA-256 hash of the API token value." A token's secret is kept here as
+// bookkeeping (`_r2_api_token`, never on any wire) so the lane can tell who signed a request.
+//
+// CUSTOM DOMAINS (https://developers.cloudflare.com/r2/buckets/public-buckets/): a domain of a zone in the bucket's
+// account is connected to the bucket; "The status takes a few minutes to change from Initializing to Active". Where the
+// documentation stops: "a few minutes" is five here, the move stamped at the moment it fell due.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+
+const SERVICE = 'cloudflare';
+type Row = Record<string, unknown> & { id: string; type: string };
+const sha256 = (s: string): string => createHash('sha256').update(s).digest('hex');
+const all = (type: string, root?: string, withDeleted = false): Row[] =>
+  (projectResources(SERVICE, root) as unknown as Row[]).filter((r) => r.type === type && (withDeleted || r.deleted !== true));
+const put = (type: string, id: string, operation: string, fields: Record<string, unknown>, root: string | undefined, occurredAt: string): Promise<unknown> =>
+  applyTwinWrite(SERVICE, { operation, subjectType: type, subjectId: id, fields, occurredAt, actor: { kind: 'agent' } }, root);
+
+/** The S3 API's endpoint suffix: "The API is available via the https://<ACCOUNT_ID>.r2.cloudflarestorage.com endpoint"
+ *  (https://developers.cloudflare.com/r2/api/s3/api/). */
+export const R2_ENDPOINT_SUFFIX = '.r2.cloudflarestorage.com';
+
+// ── API tokens ──────────────────────────────────────────────────────────────────────────────────
+
+export type R2Permission = 'admin-rw' | 'admin-ro' | 'object-rw' | 'object-ro';
+/** The four permissions, in the tokens page's words. */
+export const R2_PERMISSIONS: ReadonlyArray<{ value: R2Permission; label: string; description: string }> = [
+  { value: 'admin-rw', label: 'Admin Read & Write', description: 'Allows the ability to create, list, and delete buckets, edit bucket configuration, read, write, and list objects, and read and write to data catalog tables and associated metadata.' },
+  { value: 'admin-ro', label: 'Admin Read only', description: 'Allows the ability to list buckets and view bucket configuration, read and list objects, and read from the data catalog tables and associated metadata.' },
+  { value: 'object-rw', label: 'Object Read & Write', description: 'Allows the ability to read, write, and list objects in specific buckets.' },
+  { value: 'object-ro', label: 'Object Read only', description: 'Allows the ability to read and list objects in specific buckets.' },
+];
+
+export type R2Token = Row & { account_id: string; name: string; kind: 'account' | 'user'; owner: string; permission: R2Permission; buckets: '*' | string[]; access_key_id: string; secret_access_key: string; revoked?: boolean };
+
+export function r2Tokens(accountId: string, root?: string): R2Token[] {
+  return all('_r2_api_token', root).filter((t) => t.account_id === accountId && t.revoked !== true) as R2Token[];
+}
+
+/** A token's value, id and S3 credentials, made as the dashboard makes them. The value and the id are drawn from the
+ *  account, the name and how many tokens the World holds, so a World mints the same ones every run. */
+export async function createR2Token(input: { accountId: string; name: string; kind: 'account' | 'user'; owner: string; permission: R2Permission; buckets: '*' | string[] }, root: string | undefined, occurredAt: string): Promise<{ token: R2Token; value: string }> {
+  const n = all('_r2_api_token', root, true).length + 1;
+  const seed = `r2-token:${input.accountId}:${input.name}:${n}`;
+  const value = createHash('sha256').update(seed).digest('base64url').slice(0, 40);
+  const id = sha256(`${seed}:id`).slice(0, 32);
+  await put('_r2_api_token', id, 'r2_api_token.create', {
+    account_id: input.accountId, name: input.name, kind: input.kind, owner: input.owner, permission: input.permission, buckets: input.buckets,
+    access_key_id: id, secret_access_key: sha256(value), created_on: occurredAt, revoked: false,
+  }, root, occurredAt);
+  return { token: all('_r2_api_token', root).find((t) => t.id === id) as R2Token, value };
+}
+
+export async function revokeR2Token(id: string, root: string | undefined, occurredAt: string): Promise<void> {
+  await put('_r2_api_token', id, 'r2_api_token.revoke', { revoked: true }, root, occurredAt);
+}
+
+/** The live token whose Access Key ID this is, in this account. */
+export function r2Credential(accountId: string, accessKeyId: string, root?: string): R2Token | undefined {
+  return r2Tokens(accountId, root).find((t) => t.access_key_id === accessKeyId);
+}
+
+/** What an operation needs of a token: a bucket's objects read or written, a bucket's configuration read or edited, or
+ *  the account's buckets listed, made or deleted. */
+export type R2Need = { object: 'read' | 'write'; bucket: string } | { admin: 'read' | 'write' };
+
+/** Whether the token's permission, as the tokens page states it, allows the need. */
+export function r2Allows(token: R2Token, need: R2Need): boolean {
+  if ('admin' in need) return token.permission === 'admin-rw' || (token.permission === 'admin-ro' && need.admin === 'read');
+  if (token.permission === 'admin-rw') return true;
+  if (token.permission === 'admin-ro') return need.object === 'read';
+  const inScope = token.buckets === '*' || token.buckets.includes(need.bucket);
+  return inScope && (token.permission === 'object-rw' || need.object === 'read');
+}
+
+// ── Temporary credentials ───────────────────────────────────────────────────────────────────────
+// https://developers.cloudflare.com/r2/api/s3/temporary-credentials/: "short-lived, scoped S3 credentials derived from an
+// existing R2 API token ... they include a session token and expire automatically", "bound to exactly one bucket", to a
+// permission (object-read-only, object-read-write, admin-read-only, admin-read-write) and optionally to prefixes and
+// objects; "A temporary credential cannot exceed the permissions of its parent token", and "If you revoke the parent API
+// token, all temporary credentials derived from it stop working immediately". Minted by the Temporary Credentials API,
+// POST /accounts/{account_id}/r2/temp-access-credentials (cloudflare-provisioning.ts).
+
+export type R2TempCredential = Row & { account_id: string; bucket: string; parent: string; permission: R2Permission; prefixes: string[]; objects: string[]; access_key_id: string; secret_access_key: string; session_token: string; expires_at: string };
+export const TEMP_PERMISSIONS: Record<string, R2Permission> = { 'object-read-only': 'object-ro', 'object-read-write': 'object-rw', 'admin-read-only': 'admin-ro', 'admin-read-write': 'admin-rw' };
+
+/** Whether a parent token's grant covers a temporary credential's permission on a bucket. */
+export function r2ParentCovers(parent: R2Token, permission: R2Permission, bucket: string): boolean {
+  if (!(parent.buckets === '*' || parent.buckets.includes(bucket))) return false;
+  if (parent.permission === 'admin-rw') return true;
+  if (parent.permission === 'admin-ro') return permission === 'admin-ro' || permission === 'object-ro';
+  if (parent.permission === 'object-rw') return permission === 'object-rw' || permission === 'object-ro';
+  return permission === 'object-ro';
+}
+
+export async function createR2TempCredential(input: { accountId: string; bucket: string; parent: R2Token; permission: R2Permission; ttlSeconds: number; prefixes: string[]; objects: string[] }, root: string | undefined, occurredAt: string): Promise<R2TempCredential> {
+  const n = all('_r2_temp_credential', root, true).length + 1;
+  const seed = `r2-temp:${input.accountId}:${input.bucket}:${input.parent.access_key_id}:${n}`;
+  const id = sha256(`${seed}:id`).slice(0, 32);
+  const session = createHash('sha256').update(`${seed}:session`).digest('base64url');
+  await put('_r2_temp_credential', id, 'r2_temp_credential.create', {
+    account_id: input.accountId, bucket: input.bucket, parent: input.parent.access_key_id, permission: input.permission, prefixes: input.prefixes, objects: input.objects,
+    access_key_id: id, secret_access_key: sha256(`${seed}:secret`), session_token: session, expires_at: new Date(Date.parse(occurredAt) + input.ttlSeconds * 1000).toISOString(),
+  }, root, occurredAt);
+  return all('_r2_temp_credential', root).find((c) => c.id === id) as R2TempCredential;
+}
+
+/** The temporary credential an Access Key ID and a session token name in this account, while its parent is live. */
+export function r2TempCredential(accountId: string, accessKeyId: string, sessionToken: string, root?: string): { credential: R2TempCredential; parent: R2Token } | undefined {
+  const credential = all('_r2_temp_credential', root).find((c) => c.account_id === accountId && c.access_key_id === accessKeyId && c.session_token === sessionToken) as R2TempCredential | undefined;
+  const parent = credential ? r2Credential(accountId, credential.parent, root) : undefined;
+  return credential && parent ? { credential, parent } : undefined;
+}
+
+/** Who a Cloudflare API bearer is for R2's REST routes: an R2 API token by its value (its Secret Access Key is the value's
+ *  SHA-256), or a user API token of a member of the account. */
+export function r2BearerToken(accountId: string, bearer: string, root?: string): R2Token | undefined {
+  const secret = sha256(bearer);
+  return r2Tokens(accountId, root).find((t) => t.secret_access_key === secret);
+}
+
+// ── Custom domains ──────────────────────────────────────────────────────────────────────────────
+
+const ACTIVE_AFTER_MS = 5 * 60_000;
+export type R2CustomDomain = Row & { account_id: string; bucket: string; domain: string; enabled: boolean; zone_id: string; zone_name: string; min_tls: string; ciphers?: string[]; ownership: string; ssl: string; connected_at: string };
+export const r2DomainId = (accountId: string, bucket: string, domain: string): string => `${accountId}:${bucket}:${domain}`;
+
+export function r2CustomDomains(root?: string): R2CustomDomain[] {
+  return all('r2_custom_domain', root) as R2CustomDomain[];
+}
+
+export async function connectR2CustomDomain(input: { accountId: string; bucket: string; domain: string; enabled: boolean; zoneId: string; zoneName: string; minTLS?: string; ciphers?: string[] }, root: string | undefined, occurredAt: string): Promise<R2CustomDomain> {
+  const id = r2DomainId(input.accountId, input.bucket, input.domain);
+  await put('r2_custom_domain', id, 'r2_custom_domain.create', {
+    account_id: input.accountId, bucket: input.bucket, domain: input.domain, enabled: input.enabled, zone_id: input.zoneId, zone_name: input.zoneName,
+    min_tls: input.minTLS ?? '1.0', ...(input.ciphers ? { ciphers: input.ciphers } : {}), ownership: 'pending', ssl: 'initializing', connected_at: occurredAt, deleted: false,
+  }, root, occurredAt);
+  return r2CustomDomains(root).find((d) => d.id === id)!;
+}
+
+export async function updateR2CustomDomain(id: string, fields: { enabled?: boolean; minTLS?: string; ciphers?: string[] }, root: string | undefined, occurredAt: string): Promise<void> {
+  await put('r2_custom_domain', id, 'r2_custom_domain.update', {
+    ...(fields.enabled !== undefined ? { enabled: fields.enabled } : {}), ...(fields.minTLS !== undefined ? { min_tls: fields.minTLS } : {}), ...(fields.ciphers !== undefined ? { ciphers: fields.ciphers } : {}),
+  }, root, occurredAt);
+}
+
+export async function removeR2CustomDomain(id: string, root: string | undefined, occurredAt: string): Promise<void> {
+  await put('r2_custom_domain', id, 'r2_custom_domain.delete', { deleted: true }, root, occurredAt);
+}
+
+/** Cloudflare's own move: a connected domain turns Active once its minutes have passed, stamped when it fell due. Run
+ *  before anything that reads a domain answers. */
+export async function catchUpR2CustomDomains(root: string | undefined, now: string): Promise<void> {
+  const at = Date.parse(now);
+  for (const d of r2CustomDomains(root)) {
+    const due = Date.parse(d.connected_at) + ACTIVE_AFTER_MS;
+    if (d.ownership !== 'active' && due <= at) await put('r2_custom_domain', d.id, 'r2_custom_domain.activate', { ownership: 'active', ssl: 'active' }, root, new Date(due).toISOString());
+  }
+}
+
+/** The bucket a host serves publicly: a custom domain connected to it, Active and enabled. */
+export function r2PublicDomain(host: string, root?: string): R2CustomDomain | undefined {
+  const h = host.toLowerCase();
+  return r2CustomDomains(root).find((d) => d.domain === h && d.enabled && d.ownership === 'active');
+}

package/src/cloudflare-server.ts

@@ -0,0 +1,109 @@
+// Cloudflare twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createCloudflareTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it, so the standalone (R1) and hosted lanes execute
+// identical serving bytes. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): the handler's `raw` replies (a Worker script download, a
+// bodiless 204) are served verbatim rather than JSON-encoded — openai-server.ts is the reference
+// for that lane.
+import { serveHttp } from '@volter/world-core';
+import { handleCloudflareTwinRequest } from './cloudflare-twin.ts';
+import { R2_ENDPOINT_SUFFIX, r2CustomDomains } from './cloudflare-r2.ts';
+import { DASHBOARD_HOST, dashboardDoors } from './screens/dashboard.tsx';
+import { createR2LaneFetch } from '../r2/src/fetch.ts';
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+import { createHash } from 'node:crypto';
+
+/** Options every Cloudflare-twin HTTP surface needs, independent of who owns the socket. */
+export interface CloudflareTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** the R2 lane's fetch (../r2/src/fetch.ts), when the caller has one already */
+  lane?: (request: Request) => Promise<Response>;
+}
+
+// Every answer carries Cloudflare's own headers for when and which request it was: Date on the World's clock and a cf-ray
+// (16 hex digits and a colo), derived from the instant, the request and a counter.
+let served = 0;
+function stamped(res: Response, request: Request): Response {
+  const at = worldNow();
+  const headers = new Headers(res.headers);
+  headers.set('date', new Date(at).toUTCString());
+  if (!headers.has('cf-ray')) headers.set('cf-ray', `${createHash('sha256').update(`${at}:${request.method}:${request.url}:${served++}`).digest('hex').slice(0, 16)}-SJC`);
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+
+export function createCloudflareTwinFetch(options: CloudflareTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const inner = cloudflareTwinFetchUnstamped(options);
+  return async (request: Request) => stamped(await inner(request), request);
+}
+// The hosts one pack answers: the API v4 control plane (api.cloudflare.com), the dashboard (dash.cloudflare.com: sign-in, R2's
+// API tokens, a bucket's custom domains; screens/dashboard.tsx), R2's S3 endpoint (`<ACCOUNT_ID>.r2.cloudflarestorage.com`)
+// and a custom domain connected to an R2 bucket, both the R2 lane's (../r2/). The host is the vendor host the World's
+// injector names in x-volter-twin-original-host, else the request's Host.
+function hostOf(request: Request): string {
+  return (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host).split(':')[0]!.toLowerCase();
+}
+function cloudflareTwinFetchUnstamped(options: CloudflareTwinFetchOptions): (request: Request) => Promise<Response> {
+  const lane = options.lane ?? createR2LaneFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}) });
+  return async function cloudflareTwinFetch(request: Request): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+      const host = hostOf(request);
+      if (host === DASHBOARD_HOST) {
+        return (await dashboardDoors(request, options.root, worldNow())) ?? new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+      }
+      if (host.endsWith(R2_ENDPOINT_SUFFIX) || r2CustomDomains(options.root).some((d) => d.domain === host)) return await lane(request);
+      // GET /twin/hosts — the custom domains connected to R2 buckets, which the World routes here as DNS routes them to
+      // Cloudflare (the descriptor's hostsClaimed); the same list the dispatch above answers on
+      if (request.method === 'GET' && url.pathname === '/twin/hosts') {
+        return Response.json({ hosts: [...new Set(r2CustomDomains(options.root).map((d) => d.domain))].sort() });
+      }
+      // GET /twin — the discovery manifest (education inside the twin).
+      if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+        return Response.json(statefulTwinManifest({ vendor: 'cloudflare', twinOf: 'the Cloudflare API v4 control plane', stores: 'accounts, zones, and remotely-managed Tunnel configurations/tokens' }));
+      }
+      const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : '';
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+      const result = await handleCloudflareTwinRequest({
+        method: request.method,
+        path: `${url.pathname}${url.search}`,
+        body,
+        headers,
+        readOnly: options.readOnly ?? false,
+        occurredAt: worldNow(),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+      });
+      if (result.raw) {
+        // Non-JSON responses (Worker script download; 204 subdomain delete has no body).
+        return new Response(result.body === null || result.body === undefined ? null : String(result.body), {
+          status: result.status,
+          headers: result.headers ?? {},
+        });
+      }
+      return new Response(JSON.stringify(result.body), {
+        status: result.status,
+        headers: { 'content-type': 'application/json', ...(result.headers ?? {}) },
+      });
+    } catch (error) {
+      return Response.json({
+        success: false,
+        errors: [{ code: 1000, message: error instanceof Error ? error.message : 'Internal error' }],
+        messages: [],
+        result: null,
+      }, { status: 500 });
+    }
+  };
+}
+
+export async function createCloudflareTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; url: string; stop: () => void }> {
+  const server = await serveHttp({
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createCloudflareTwinFetch(options),
+  });
+  const port = server.port ?? options.port ?? 0;
+  return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}