@volter/twin-cloudflare 0.1.0

package/dist/src/cloudflare-worker-assets.d.ts

@@ -0,0 +1,25 @@
+import { type CloudflareRequest, type CloudflareResponse } from './cloudflare-common.js';
+export declare const ASSET_BUCKET_SIZE = 10;
+type Body = Record<string, unknown>;
+type ManifestEntry = {
+    hash: string;
+    size: number;
+};
+/** POST /accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session */
+export declare function createAssetsUploadSession(req: CloudflareRequest, accountID: string, scriptName: string, body: Body): Promise<CloudflareResponse>;
+type Part = {
+    name: string;
+    filename?: string;
+    contentType?: string;
+    data: string;
+};
+/** POST /accounts/{account_id}/workers/assets/upload — authenticated by the session's upload jwt. */
+export declare function uploadAssets(req: CloudflareRequest, accountID: string, url: URL, parseParts: (body: string, boundary: string) => Part[] | null): Promise<CloudflareResponse>;
+export type RedeemedAssets = {
+    session_id: string;
+    manifest: Record<string, ManifestEntry>;
+};
+/** Redeem a script upload's `metadata.assets.jwt`: a completion token this twin issued for this
+ *  account and Worker, whose session's every hash is held. */
+export declare function redeemAssetsCompletion(req: CloudflareRequest, accountID: string, scriptName: string, jwt: unknown): RedeemedAssets | CloudflareResponse;
+export {};

package/dist/src/cloudflare-worker-assets.js

@@ -0,0 +1,192 @@
+// Workers static-assets upload: the three-step contract every assets deploy drives
+// (wrangler's syncAssets, the official SDK's `workers.scripts.assets.upload` +
+// `workers.assets.upload`):
+//
+//   1. POST /accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session
+//      body {manifest: {"/path": {hash, size}}} → {jwt, buckets: [[hash, …], …]} — the buckets
+//      name only the hashes this account does not already hold; with nothing to upload the
+//      returned jwt is already the completion token.
+//   2. POST /accounts/{account_id}/workers/assets/upload?base64=true, authenticated by the
+//      session jwt (not the API token), multipart parts named by hash carrying base64 content →
+//      {jwt} once every hash of the session is held (the completion token), {} before that.
+//   3. The script upload's metadata.assets.jwt redeems the completion token; the script then
+//      records the session's manifest and the assets config (cloudflare-provisioning.ts).
+//
+// The twin RECORDS, never serves: an uploaded asset becomes a `worker_asset` row (hash, size,
+// content type) — the bytes are decoded to check their size against the manifest and then
+// dropped, because no Cloudflare read endpoint returns asset bytes. The manifest hash is
+// wrangler's blake3 over base64 content + extension; the twin does not recompute blake3 (no
+// such primitive in the runtime), so it verifies each part's decoded SIZE against the manifest
+// and trusts the declared hash. Bucket size (at most ASSET_BUCKET_SIZE hashes) is a twin
+// convention: the pinned OpenAPI types `buckets` but does not pin how the vendor partitions.
+//
+// Tokens are compact HS256 JWTs signed with a fixed twin key: clients decode the payload
+// (wrangler reads `wrangler_single_asset_uploads` from it; the twin never sets it, so the bulk
+// multipart path is the one driven) and the twin verifies the signature, purpose, account,
+// and expiry on redemption.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { failure, headers as lowerHeaders, isResponse, mint, row, rows, success, write, } from "./cloudflare-common.js";
+const TOKEN_KEY = 'volter-cloudflare-twin:workers-assets';
+const TOKEN_TTL_SECONDS = 3600;
+export const ASSET_BUCKET_SIZE = 10;
+const ASSET_HASH = /^[0-9a-f]{32}$/;
+function b64url(value) {
+    return Buffer.from(value).toString('base64url');
+}
+function sign(input) {
+    return createHmac('sha256', TOKEN_KEY).update(input).digest('base64url');
+}
+function issueToken(claims) {
+    const head = `${b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))}.${b64url(JSON.stringify(claims))}`;
+    return `${head}.${sign(head)}`;
+}
+/** Verify a token's signature and shape; null when it is not one this twin issued. */
+function readToken(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3)
+        return null;
+    const expected = Buffer.from(sign(`${segments[0]}.${segments[1]}`));
+    const given = Buffer.from(segments[2]);
+    if (expected.length !== given.length || !timingSafeEqual(expected, given))
+        return null;
+    try {
+        const claims = JSON.parse(Buffer.from(segments[1], 'base64url').toString('utf8'));
+        if ((claims.purpose !== 'upload' && claims.purpose !== 'completion') || typeof claims.session_id !== 'string')
+            return null;
+        return claims;
+    }
+    catch {
+        return null;
+    }
+}
+function epochSeconds(req) {
+    return Math.floor(Date.parse(req.occurredAt ?? new Date().toISOString()) / 1000);
+}
+function assetID(accountID, hash) {
+    return `${accountID}:${hash}`;
+}
+function heldHashes(accountID, root) {
+    return new Set(rows('worker_asset', root).filter((item) => item.account_id === accountID).map((item) => String(item.hash)));
+}
+function sessionComplete(session, root) {
+    const held = heldHashes(String(session.account_id), root);
+    return (Array.isArray(session.pending) ? session.pending : []).every((hash) => held.has(hash));
+}
+function completionToken(session, req) {
+    const iat = epochSeconds(req);
+    return issueToken({
+        purpose: 'completion', account_id: String(session.account_id), script_name: String(session.script_name),
+        session_id: session.id, iat, exp: iat + TOKEN_TTL_SECONDS,
+    });
+}
+function validManifest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return failure(400, 1004, 'manifest is required and must be an object of path → {hash, size}');
+    const manifest = {};
+    // Stored in path order: a client builds its manifest concurrently (wrangler's insertion order
+    // varies run to run), and the same assets must record — and fingerprint — the same way.
+    for (const [path, entry] of Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        if (!path.startsWith('/'))
+            return failure(400, 1004, `manifest path "${path}" must start with "/"`);
+        const item = entry;
+        if (!item || typeof item !== 'object' || typeof item.hash !== 'string' || !ASSET_HASH.test(item.hash)) {
+            return failure(400, 1004, `manifest entry "${path}" requires a 32-character hex hash`);
+        }
+        if (!Number.isInteger(item.size) || Number(item.size) < 0)
+            return failure(400, 1004, `manifest entry "${path}" requires a non-negative integer size`);
+        manifest[path] = { hash: item.hash, size: Number(item.size) };
+    }
+    return manifest;
+}
+/** POST /accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session */
+export async function createAssetsUploadSession(req, accountID, scriptName, body) {
+    const entries = validManifest(body.manifest);
+    if (isResponse(entries))
+        return entries;
+    const held = heldHashes(accountID, req.root);
+    const pending = [...new Set(Object.values(entries).map((entry) => entry.hash))].filter((hash) => !held.has(hash)).sort();
+    const buckets = [];
+    for (let index = 0; index < pending.length; index += ASSET_BUCKET_SIZE)
+        buckets.push(pending.slice(index, index + ASSET_BUCKET_SIZE));
+    const at = req.occurredAt ?? new Date().toISOString();
+    const id = mint('worker_asset_upload_session', `${accountID}:${scriptName}:${JSON.stringify(entries)}`, req.root);
+    await write('worker_asset_upload_session', id, 'worker_asset_upload_session.create', {
+        account_id: accountID, script_name: scriptName, manifest: entries, pending, created_on: at, deleted: false,
+    }, req);
+    const session = row('worker_asset_upload_session', id, req.root);
+    const iat = epochSeconds(req);
+    const jwt = pending.length === 0
+        ? completionToken(session, req)
+        : issueToken({ purpose: 'upload', account_id: accountID, script_name: scriptName, session_id: id, iat, exp: iat + TOKEN_TTL_SECONDS });
+    return success({ jwt, buckets });
+}
+/** POST /accounts/{account_id}/workers/assets/upload — authenticated by the session's upload jwt. */
+export async function uploadAssets(req, accountID, url, parseParts) {
+    const h = lowerHeaders(req.headers);
+    const bearer = /^Bearer\s+(\S+)$/i.exec(h.authorization ?? '')?.[1] ?? '';
+    const claims = readToken(bearer);
+    if (!claims || claims.purpose !== 'upload' || claims.account_id !== accountID) {
+        return failure(401, 10000, 'Authentication error: the asset upload requires the upload session token');
+    }
+    if (claims.exp < epochSeconds(req))
+        return failure(401, 10000, 'Authentication error: the asset upload session token has expired');
+    const session = row('worker_asset_upload_session', claims.session_id, req.root);
+    if (!session || session.account_id !== accountID)
+        return failure(401, 10000, 'Authentication error: unknown asset upload session');
+    const boundary = /boundary\s*=\s*(?:"([^"]+)"|([^\s;]+))/i.exec(h['content-type'] ?? '');
+    const parts = boundary ? parseParts(req.body ?? '', boundary[1] ?? boundary[2]) : null;
+    if (!parts || parts.length === 0)
+        return failure(400, 1004, 'Asset upload requires a multipart/form-data body with one part per asset hash');
+    const base64 = url.searchParams.get('base64') === 'true';
+    const manifest = session.manifest;
+    const sizeOf = new Map(Object.values(manifest).map((entry) => [entry.hash, entry.size]));
+    const pending = new Set(Array.isArray(session.pending) ? session.pending : []);
+    const accepted = [];
+    for (const part of parts) {
+        if (!pending.has(part.name))
+            return failure(400, 1004, `Asset "${part.name}" is not part of this upload session`);
+        let size;
+        if (base64) {
+            const compact = part.data.replace(/\s+/g, '');
+            if (!/^[A-Za-z0-9+/]*={0,2}$/.test(compact) || compact.length % 4 !== 0)
+                return failure(400, 1004, `Asset "${part.name}" is not valid base64`);
+            size = Buffer.from(compact, 'base64').length;
+        }
+        else {
+            size = Buffer.byteLength(part.data, 'utf8');
+        }
+        if (size !== sizeOf.get(part.name)) {
+            return failure(400, 1004, `Asset "${part.name}" is ${size} bytes but the session manifest declares ${sizeOf.get(part.name)}`);
+        }
+        // wrangler sends "application/null" to mean "serve with no Content-Type".
+        const contentType = part.contentType && part.contentType !== 'application/null' ? part.contentType : null;
+        accepted.push({ hash: part.name, size, contentType });
+    }
+    const at = req.occurredAt ?? new Date().toISOString();
+    for (const asset of accepted) {
+        if (row('worker_asset', assetID(accountID, asset.hash), req.root))
+            continue; // content-addressed: already held
+        await write('worker_asset', assetID(accountID, asset.hash), 'worker_asset.upload', {
+            account_id: accountID, hash: asset.hash, size: asset.size, content_type: asset.contentType, uploaded_on: at, deleted: false,
+        }, req);
+    }
+    return success(sessionComplete(session, req.root) ? { jwt: completionToken(session, req) } : {});
+}
+/** Redeem a script upload's `metadata.assets.jwt`: a completion token this twin issued for this
+ *  account and Worker, whose session's every hash is held. */
+export function redeemAssetsCompletion(req, accountID, scriptName, jwt) {
+    if (typeof jwt !== 'string' || !jwt)
+        return failure(400, 1004, 'metadata.assets.jwt is required');
+    const claims = readToken(jwt);
+    if (!claims || claims.purpose !== 'completion' || claims.account_id !== accountID) {
+        return failure(400, 1004, 'metadata.assets.jwt is not a completion token for this account');
+    }
+    if (claims.script_name !== scriptName)
+        return failure(400, 1004, `metadata.assets.jwt was issued for Worker "${claims.script_name}", not "${scriptName}"`);
+    if (claims.exp < epochSeconds(req))
+        return failure(400, 1004, 'metadata.assets.jwt has expired; start a new asset upload session');
+    const session = row('worker_asset_upload_session', claims.session_id, req.root);
+    if (!session || !sessionComplete(session, req.root))
+        return failure(400, 1004, 'metadata.assets.jwt names an asset upload session whose assets are not all uploaded');
+    return { session_id: session.id, manifest: session.manifest };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { handleCloudflareTwinRequest, cloudflareTwinSnapshot, CLOUDFLARE_RESOURCE_TYPES, CLOUDFLARE_ROUTER_SURFACE, cloudflareConfigurationID, } from './cloudflare-twin.js';
+export type { CloudflareRequest, CloudflareResponse, CloudflareResourceType } from './cloudflare-twin.js';
+export { createCloudflareTwinFetch, createCloudflareTwinServer, type CloudflareTwinFetchOptions } from './cloudflare-server.js';
+export { liveCloudflareExecute, mapCloudflareAccount, mapCloudflareZone, mapCloudflareTunnel, mapCloudflareConfiguration, mapCloudflareDnsRecord, pullCloudflareState, syncCloudflareFromReal, cloudflareRequestForAction, performCloudflareAction, cloudflareExecuteOver, syncCloudflareFromRemote, } from './cloudflare-connector.js';
+export type { CloudflareExecute, LiveCloudflareOptions } from './cloudflare-connector.js';
+export { CLOUDFLARE_BUDGET_CEILING, CLOUDFLARE_BUDGET_MAX_RETRY_AFTER_S, CLOUDFLARE_BUDGET_WINDOW_MS, CLOUDFLARE_CALL_WEIGHTS, CLOUDFLARE_RATE_BUDGET, CloudflareBudget, CloudflareBudgetError, cloudflareBudgetPath, cloudflareCallWeight, } from './cloudflare-budget.js';
+export type { CloudflareBudgetErrorKind, CloudflareBudgetOptions, CloudflareBudgetReservation, CloudflareBudgetSnapshot, } from './cloudflare-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,69 @@
+export { handleCloudflareTwinRequest, cloudflareTwinSnapshot, CLOUDFLARE_RESOURCE_TYPES, CLOUDFLARE_ROUTER_SURFACE, cloudflareConfigurationID, } from "./cloudflare-twin.js";
+export { createCloudflareTwinFetch, createCloudflareTwinServer } from "./cloudflare-server.js";
+export { liveCloudflareExecute, mapCloudflareAccount, mapCloudflareZone, mapCloudflareTunnel, mapCloudflareConfiguration, mapCloudflareDnsRecord, pullCloudflareState, syncCloudflareFromReal, cloudflareRequestForAction, performCloudflareAction, cloudflareExecuteOver, syncCloudflareFromRemote, } from "./cloudflare-connector.js";
+export { CLOUDFLARE_BUDGET_CEILING, CLOUDFLARE_BUDGET_MAX_RETRY_AFTER_S, CLOUDFLARE_BUDGET_WINDOW_MS, CLOUDFLARE_CALL_WEIGHTS, CLOUDFLARE_RATE_BUDGET, CloudflareBudget, CloudflareBudgetError, cloudflareBudgetPath, cloudflareCallWeight, } from "./cloudflare-budget.js";
+import { hosts as r2Hosts } from "../r2/src/manifest.js";
+import { CLOUDFLARE_RATE_BUDGET } from "./cloudflare-budget.js";
+import { registerPack, referenceField } from '@volter/world-core';
+import { performCloudflareAction as perform, syncCloudflareFromRemote as refresh } from "./cloudflare-connector.js";
+export const pack = {
+    vendor: 'cloudflare',
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real state
+    // system: perform one entry against Cloudflare's API v4, refresh the root from it. Moved 2026-09-08.
+    protocol: '2',
+    refresh: { every: '5m', onDemand: { atMost: '30s' } }, // the v4 control plane has no webhooks: polled, or on demand
+    stateSystem: { perform, refresh },
+    // the round trip: an account and a zone the twin is told about (its bootstrap door — Cloudflare's own accounts
+    // are never created through the API), then a TXT record in that zone. TXT is the repeatable one: A/AAAA/CNAME
+    // and NS refuse a second record at the same name, exactly as Cloudflare does, so they could not run twice.
+    roundTrip: [
+        { method: 'POST', path: '/twin/bootstrap', body: { accounts: [{ id: 'a0000000000000000000000000000001', name: 'round trip' }], zones: [{ id: 'b0000000000000000000000000000001', name: 'round.trip.test', account_id: 'a0000000000000000000000000000001' }] }, headers: { authorization: 'Bearer round-trip' } },
+        { method: 'POST', path: '/zones/b0000000000000000000000000000001/dns_records', body: { type: 'TXT', name: 'round.trip.test', content: 'round trip' }, headers: { authorization: 'Bearer round-trip' } },
+    ],
+    // rule 5: a record names its zone, a zone and a tunnel name their account, a configuration names its tunnel —
+    // when the head adopts Cloudflare's id for the parent, the kernel resolves the child's field first
+    referenceTrip: { method: 'POST', path: '/zones/{{id}}/dns_records', body: { type: 'TXT', name: 'round.trip.test', content: 'a second record on the round trip' }, headers: { authorization: 'Bearer round-trip' } },
+    references: [
+        referenceField('dns_record', 'zone_id', 'zone'),
+        referenceField('zone', 'account_id', 'account'),
+        referenceField('cloudflare_tunnel', 'account_id', 'account'),
+        referenceField('tunnel_configuration', 'tunnel_id', 'cloudflare_tunnel'),
+    ],
+    parityOrigin: 'http://twin',
+    // the twin refreshed from its own wire stores what its write handler stored, key for key (gate: zero diffs)
+    shapeParity: 'held',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-cloudflare',
+    resources: [
+        'account', 'zone', 'cloudflare_tunnel', 'tunnel_configuration', 'dns_record',
+        'worker_script', 'worker_route', 'worker_domain', 'workers_subdomain', 'durable_object_namespace',
+        'r2_bucket', 'r2_custom_domain', 'hyperdrive_config', 'queue', 'queue_consumer', 'worker_version', 'worker_asset', 'worker_asset_upload_session',
+    ],
+    specSource: 'Cloudflare official api-schemas OpenAPI 4.0.0 at 2ac8369e9b63dccacee1a2284e95bb819f05b307 and official cloudflare-typescript SDK at faaaf89ed8064a9fb54de538ec3e89487f1302b0 (npm cloudflare@7.1.0), read 2026-08-21; provisioning slice re-read from the same pinned sources 2026-08-23.',
+    description: 'Cloudflare API v4 control-plane twin for account and zone discovery, remotely-managed Cloudflare Tunnel lifecycle/configuration/token retrieval, zone DNS-record CRUD, and the Workers deploy plane: Worker script upload (recorded + fingerprinted, never executed), cron triggers, workers.dev subdomains, zone routes, custom domains, Durable Object namespace records, R2 bucket control plane, Hyperdrive configs, and Queues with consumers. No tunnel execution, edge routing, TLS, DNS resolution, Worker execution, object storage, or origin dialing. Kernel-backed.',
+    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31). The API v4 control plane only: the website/dashboard and customer
+    // origins are deliberately unclaimed — this pack models api.cloudflare.com/client/v4.
+    adoption: {
+        // Cloudflare's official Python library - same name as the npm client.
+        pypi: ['cloudflare'], tools: [{ package: 'wrangler', usage: 'deployment' }],
+        // aws4fetch, a SigV4 signer over fetch, is the pack's by its use: Cloudflare documents it as an R2 client
+        // (https://developers.cloudflare.com/r2/examples/aws/aws4fetch/), and the one app measured with it, Dub, stores in
+        // R2 through it (apps/web/lib/storage.ts); an app signing AWS's S3 with it is declared at init
+        sdks: ['cloudflare', 'aws4fetch'], envStems: ['CLOUDFLARE'],
+    },
+    // the API v4 control plane; the dashboard's sign-in, R2 API tokens and bucket settings (screens/dashboard.tsx); and R2's
+    // S3-compatible endpoint, `<ACCOUNT_ID>.r2.cloudflarestorage.com` and its virtual-hosted form (the R2 lane, ../r2/). A
+    // custom domain an R2 bucket is connected to is the operator's to claim for a World.
+    hosts: [{ host: 'api.cloudflare.com' }, { host: 'dash.cloudflare.com', pathPattern: '^/(login|_twin/users/|[0-9a-f]{32}/r2/|$)' }, ...r2Hosts],
+    // a custom domain connected to an R2 bucket resolves to Cloudflare: connecting it will "add the new record to the DNS
+    // table", and removing it "also removes the CNAME record" (https://developers.cloudflare.com/r2/buckets/public-buckets/,
+    // Custom domains), so the World
+    // routes each the twin has connected (cloudflare-server.ts, GET /twin/hosts)
+    hostsClaimed: { door: '/twin/hosts', note: 'the custom domains connected to R2 buckets' },
+    browserRouting: { apiPathPrefix: '/client/v4/', loaderHost: 'https://api.cloudflare.com' },
+    rateBudget: CLOUDFLARE_RATE_BUDGET,
+};
+// registered at import: the kernel learns the pack's state system and its references (protocol 2)
+registerPack(pack);

package/dist/src/screens/dashboard.d.ts

@@ -0,0 +1,3 @@
+export declare const DASHBOARD_HOST = "dash.cloudflare.com";
+/** The dashboard's doors at dash.cloudflare.com, and the World's door there; undefined for any other request. */
+export declare function dashboardDoors(request: Request, root: string | undefined, occurredAt: string): Promise<Response | undefined>;

package/dist/src/screens/dashboard.js

@@ -0,0 +1,265 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// CLOUDFLARE'S DASHBOARD DOORS — the sign-in, R2's API tokens page and a bucket's custom domains, at dash.cloudflare.com
+// (docs/contributing/architecture.md, "Screens"). R2's S3 credentials can only be made on the R2 API tokens page ("Under
+// the Account Details section, select Manage next to API Tokens", https://developers.cloudflare.com/r2/api/tokens/), and a
+// bucket is connected to a custom domain on its settings page ("Select Settings. Under Custom Domains, select Add. Enter
+// the domain name you want to connect to and select Continue.", https://developers.cloudflare.com/r2/buckets/public-buckets/).
+// A page asks who is signed in first.
+//
+// THE SIGN-IN is Cloudflare's email and password one ("Email and password: Enter your email address and password.",
+// https://developers.cloudflare.com/fundamentals/user-profiles/login/); a session cookie names the person to every page
+// after. A person reaches an account's pages as a member of it (the pack's `account_member` rows).
+//
+// THE TOKENS PAGE lists the account's tokens and makes one as the page describes: "Create Account API token" or "Create
+// User API token" ("Only users with the Super Administrator role can view or create" Account API tokens), a permission of
+// the four, and for the two object permissions a set of buckets. Create shows the token's value, its Access Key ID and its
+// Secret Access Key once ("You will not be able to access your Secret Access Key again after this step"). Each token's row
+// can revoke it; a revoked token no longer signs anything for the S3 API (cloudflare-r2.ts).
+//
+// THE BUCKET'S SETTINGS list its custom domains; Add connects a domain of one of the account's zones, which the control
+// plane's attach operation does (cloudflare-provisioning.ts), and Remove disconnects it.
+//
+// Where Cloudflare's documentation stops and the twin decides: a person is what the World gives them
+// (`POST /_twin/users/:email` {password}, standing in for Cloudflare's sign-up, as vercel's door does); the session cookie is
+// named `cf_twin_session`; the pages' paths (`/{account}/r2/overview`, `/{account}/r2/api-tokens`,
+// `/{account}/r2/default/buckets/{bucket}/settings`) follow the dashboard links the docs give (`?to=/:account/r2/overview`);
+// a token's buckets are typed as names separated by commas, where Cloudflare's form offers a list to pick from; tokens have
+// no TTL (Cloudflare's form offers one); connecting a domain skips the review of the DNS record it adds, and adds none;
+// a page's address answers 405 to any method but GET (Cloudflare documents no answer for one).
+// Built from @volter/world-ui's pieces under Cloudflare's orange-and-white skin; nothing of Cloudflare's page is copied.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { deterministicHex } from "../cloudflare-common.js";
+import { cookieOf, flowPage, Portal, PORTAL_CSS, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+import { catchUpR2CustomDomains, connectR2CustomDomain, createR2Token, R2_PERMISSIONS, r2CustomDomains, r2Tokens, removeR2CustomDomain, revokeR2Token, } from "../cloudflare-r2.js";
+export const DASHBOARD_HOST = 'dash.cloudflare.com';
+const SERVICE = 'cloudflare';
+const COOKIE = 'cf_twin_session';
+const SUPER_ADMIN = 'Super Administrator - All Privileges';
+const ADMINS = new Set([SUPER_ADMIN, 'Administrator']);
+const SKIN = `
+body { background: #ffffff; color: #1d1f20; }
+.sign-in-mark { background: #f38020; border-radius: 50%; }
+.sign-in-error { background: #fdecea; border-color: #f5c2c0; color: #1d1f20; }
+.sign-in-box { background: #ffffff; border-color: #d9d9d9; }
+.sign-in-submit { background: #0051c3; border-color: #0051c3; color: #ffffff; }
+.portal-side { background: #f2f2f2; border-right: 1px solid #d9d9d9; }
+.portal-notice { background: #fff7e6; border: 1px solid #f38020; font-family: ui-monospace, monospace; word-break: break-all; }
+.portal-primary { background: #0051c3; border-color: #0051c3; color: #ffffff; }
+`;
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const rowsOf = (type, root) => projectResources(SERVICE, root).filter((r) => r.type === type && r.deleted !== true);
+const record = (type, id, fields, root, occurredAt) => applyTwinWrite(SERVICE, { operation: `${type.slice(1)}.write`, subjectType: type, subjectId: id, fields, occurredAt, actor: { kind: 'agent' } }, root);
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+const nextOf = (raw) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+const redirect = (location) => new Response(null, { status: 302, headers: { location } });
+const toLogin = (path) => redirect(`/login?next=${encodeURIComponent(path)}`);
+function signInPage(next, error, status = 200) {
+    return flowPage({
+        title: 'Log in | Cloudflare',
+        css: [SIGN_IN_CSS, SKIN],
+        status,
+        body: (_jsx(SignIn, { heading: "Log in to Cloudflare", action: "/login", fields: { next }, account: { name: 'email', label: 'Email' }, password: { name: 'password', label: 'Password' }, submit: "Log in", ...(error ? { error } : {}) })),
+    });
+}
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+function signedIn(request, root) {
+    const token = cookieOf(request, COOKIE);
+    const session = token ? rowsOf('_web_session', root).find((s) => s.token === token) : undefined;
+    return session ? rowsOf('_person', root).find((p) => p.email === session.email) : undefined;
+}
+/** The person's roles in an account, by name; none when they are not an accepted member. */
+function rolesIn(person, accountId, root) {
+    const member = rowsOf('account_member', root).find((m) => m.account_id === accountId && m.email === person.email && m.status !== 'pending');
+    if (!member)
+        return [];
+    return (member.role_ids ?? []).map((id) => ROLE_NAMES.find((n) => deterministicHex(`cf-role:${n}`, 32) === id) ?? id);
+}
+// the account's built-in roles (cloudflare-twin.ts ROLES), whose ids the pack derives from their names
+const ROLE_NAMES = [SUPER_ADMIN, 'Administrator', 'Administrator Read Only', 'Workers Admin'];
+function accountName(accountId, root) {
+    return String(rowsOf('account', root).find((a) => a.id === accountId)?.name ?? accountId);
+}
+function homePage(person, root) {
+    const accounts = rowsOf('account_member', root).filter((m) => m.email === person.email && m.status !== 'pending').map((m) => String(m.account_id));
+    return flowPage({
+        title: 'Account Home | Cloudflare',
+        css: [PORTAL_CSS, SKIN],
+        body: (_jsx(Portal, { merchant: String(person.email), sections: [{ heading: 'Accounts', empty: 'You are not a member of any account.', items: accounts.map((id) => ({ title: accountName(id, root), detail: id, actions: [{ label: 'R2 Object Storage', action: `/${id}/r2/overview`, method: 'get' }] })) }] })),
+    });
+}
+function overviewPage(person, accountId, root) {
+    const buckets = rowsOf('r2_bucket', root).filter((b) => b.account_id === accountId).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    return flowPage({
+        title: 'R2 Object Storage | Cloudflare',
+        css: [PORTAL_CSS, SKIN],
+        body: (_jsx(Portal, { merchant: `${accountName(accountId, root)} · R2 Object Storage`, back: { href: `/${accountId}/r2/api-tokens`, label: 'Manage API Tokens' }, sections: [{ heading: 'Buckets', empty: 'No buckets yet.', items: buckets.map((b) => ({ title: String(b.name), detail: `Created ${String(b.creation_date).slice(0, 10)}`, actions: [{ label: 'Settings', action: `/${accountId}/r2/default/buckets/${String(b.name)}/settings`, method: 'get' }] })) }] })),
+    });
+}
+function tokensPage(person, accountId, root, notice, status = 200) {
+    const superAdmin = rolesIn(person, accountId, root).includes(SUPER_ADMIN);
+    const visible = r2Tokens(accountId, root).filter((t) => (t.kind === 'account' ? superAdmin : t.owner === person.email));
+    const label = (p) => R2_PERMISSIONS.find((x) => x.value === p)?.label ?? p;
+    const fields = [
+        { id: 'name', label: 'Token name' },
+        { id: 'permission', label: 'Permissions', options: R2_PERMISSIONS.map((p) => ({ value: p.value, label: p.label })) },
+        { id: 'buckets', label: 'Specify bucket(s)', placeholder: 'All buckets in this account (or bucket names, separated by commas)' },
+    ];
+    return flowPage({
+        title: 'R2 API Tokens | Cloudflare',
+        css: [PORTAL_CSS, SKIN],
+        status,
+        body: (_jsx(Portal, { merchant: `${accountName(accountId, root)} · R2 API Tokens`, back: { href: `/${accountId}/r2/overview`, label: 'R2 Object Storage' }, ...(notice ? { notice } : {}), sections: [{
+                    heading: 'API Tokens',
+                    empty: 'No API tokens yet.',
+                    items: visible.map((t) => ({
+                        title: String(t.name),
+                        badge: t.kind === 'account' ? 'Account' : 'User',
+                        detail: `${label(t.permission)} · ${t.buckets === '*' ? 'All buckets' : t.buckets.join(', ')}`,
+                        note: `Access Key ID ${t.access_key_id}`,
+                        actions: [{ label: 'Revoke', action: `/${accountId}/r2/api-tokens/revoke`, fields: { token: t.id }, tone: 'danger' }],
+                    })),
+                }], forms: [
+                ...(superAdmin ? [{ heading: 'Create Account API token', action: `/${accountId}/r2/api-tokens?kind=account`, fields, submit: { label: 'Create Account API Token' } }] : []),
+                { heading: 'Create User API token', action: `/${accountId}/r2/api-tokens?kind=user`, fields, submit: { label: 'Create User API Token' } },
+            ] })),
+    });
+}
+function bucketSettingsPage(person, accountId, bucket, root, notice, status = 200) {
+    const domains = r2CustomDomains(root).filter((d) => d.account_id === accountId && d.bucket === bucket);
+    const base = `/${accountId}/r2/default/buckets/${bucket}/settings`;
+    return flowPage({
+        title: `${bucket} Settings | R2 | Cloudflare`,
+        css: [PORTAL_CSS, SKIN],
+        status,
+        body: (_jsx(Portal, { merchant: `${accountName(accountId, root)} · ${bucket}`, back: { href: `/${accountId}/r2/overview`, label: 'R2 Object Storage' }, ...(notice ? { notice } : {}), sections: [{
+                    heading: 'Custom Domains',
+                    empty: 'No custom domains connected.',
+                    items: domains.map((d) => ({
+                        title: d.domain,
+                        badge: d.ownership === 'active' ? 'Active' : 'Initializing',
+                        detail: `Access to Bucket: ${d.enabled ? 'Allowed' : 'Not allowed'}`,
+                        note: `Minimum TLS ${d.min_tls}`,
+                        actions: [{ label: 'Remove domain', action: `${base}/custom-domains/remove`, fields: { domain: d.domain }, tone: 'danger' }],
+                    })),
+                }], forms: [{ heading: 'Add Custom Domain', action: `${base}/custom-domains`, fields: [{ id: 'domain', label: 'Domain' }], submit: { label: 'Connect Domain' } }] })),
+    });
+}
+/** The dashboard's doors at dash.cloudflare.com, and the World's door there; undefined for any other request. */
+export async function dashboardDoors(request, root, occurredAt) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    await catchUpR2CustomDomains(root, occurredAt);
+    // POST /_twin/users/:email {password}: the World's stand-in for Cloudflare's sign-up of a person; the accounts they
+    // belong to are the account's members (the pack's bootstrap door)
+    const signup = /^\/_twin\/users\/([^/]+)$/.exec(path);
+    if (signup && request.method === 'POST') {
+        const email = decodeURIComponent(signup[1]).toLowerCase();
+        let body = {};
+        try {
+            body = JSON.parse(await request.text());
+        }
+        catch { /* refused below */ }
+        if (!/^[^@\s]+@[^@\s]+$/.test(email) || typeof body.password !== 'string' || !body.password)
+            return Response.json({ error: 'an email and a password are required' }, { status: 400 });
+        await record('_person', email, { email, password_sha256: hex(body.password) }, root, occurredAt);
+        return Response.json({ email }, { status: 201 });
+    }
+    if (path === '/login' && request.method === 'GET')
+        return signInPage(nextOf(url.searchParams.get('next')));
+    if (path === '/login' && request.method === 'POST') {
+        const f = await formOf(request);
+        const email = (f.email ?? '').trim().toLowerCase();
+        const next = nextOf(f.next);
+        const person = rowsOf('_person', root).find((p) => p.email === email);
+        if (!person || person.password_sha256 !== hex(f.password ?? ''))
+            return signInPage(next, 'Incorrect email address or password', 401);
+        const token = hex(`session:${email}:${occurredAt}:${rowsOf('_web_session', root).length + 1}`).slice(0, 48);
+        await record('_web_session', token, { token, email }, root, occurredAt);
+        const headers = new Headers({ location: next });
+        headers.append('set-cookie', `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`);
+        return new Response(null, { status: 302, headers });
+    }
+    const person = signedIn(request, root);
+    if (path === '/')
+        return person ? homePage(person, root) : toLogin('/');
+    const page = /^\/([0-9a-f]{32})\/r2\/(overview|api-tokens(?:\/revoke)?|default\/buckets\/([^/]+)\/settings(?:\/custom-domains(?:\/remove)?)?)$/.exec(path);
+    if (!page)
+        return undefined;
+    if (!person)
+        return toLogin(path);
+    const accountId = page[1];
+    const roles = rolesIn(person, accountId, root);
+    if (!roles.length)
+        return flowPage({ title: 'Access denied | Cloudflare', css: [PORTAL_CSS, SKIN], status: 403, body: _jsx(Portal, { merchant: String(person.email), back: { href: '/', label: 'Account Home' }, notice: "You do not have access to this account.", sections: [] }) });
+    const where = page[2];
+    // a page is opened with GET. The twin's own answer, which Cloudflare does not document: any other method on a page's
+    // address answers 405 Method Not Allowed
+    const notAllowed = () => new Response('Method Not Allowed', { status: 405, headers: { 'content-type': 'text/plain', allow: 'GET' } });
+    if (where === 'overview')
+        return request.method === 'GET' ? overviewPage(person, accountId, root) : notAllowed();
+    if (where === 'api-tokens' && request.method === 'GET')
+        return tokensPage(person, accountId, root);
+    if (where === 'api-tokens' && request.method === 'POST') {
+        const f = await formOf(request);
+        const kind = url.searchParams.get('kind') === 'account' ? 'account' : 'user';
+        if (kind === 'account' && !roles.includes(SUPER_ADMIN))
+            return tokensPage(person, accountId, root, 'Only users with the Super Administrator role can create Account API tokens.', 403);
+        const name = (f.name ?? '').trim();
+        if (!name)
+            return tokensPage(person, accountId, root, 'A token needs a name.', 422);
+        const permission = R2_PERMISSIONS.find((p) => p.value === f.permission)?.value;
+        if (!permission)
+            return tokensPage(person, accountId, root, 'Choose a permission.', 422);
+        const names = (f.buckets ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        const known = new Set(rowsOf('r2_bucket', root).filter((b) => b.account_id === accountId).map((b) => String(b.name)));
+        const unknown = names.filter((n) => !known.has(n));
+        if (unknown.length)
+            return tokensPage(person, accountId, root, `No bucket named ${unknown.join(', ')} in this account.`, 422);
+        // only the object permissions are scoped to buckets ("If you select the Object Read and Write or Object Read
+        // permissions, you can scope your token to a set of buckets")
+        const buckets = permission.startsWith('object') && names.length ? names : '*';
+        const { token, value } = await createR2Token({ accountId, name, kind, owner: String(person.email), permission, buckets }, root, occurredAt);
+        return tokensPage(person, accountId, root, `Token ${name} created. Token value: ${value} · Access Key ID: ${token.access_key_id} · Secret Access Key: ${token.secret_access_key} — copy these now: you will not be able to see the Secret Access Key again.`);
+    }
+    if (where === 'api-tokens/revoke' && request.method === 'POST') {
+        const f = await formOf(request);
+        const token = r2Tokens(accountId, root).find((t) => t.id === f.token && (t.kind === 'account' ? roles.includes(SUPER_ADMIN) : t.owner === person.email));
+        if (!token)
+            return tokensPage(person, accountId, root, 'Choose a token you can revoke.', 422);
+        await revokeR2Token(token.id, root, occurredAt);
+        return tokensPage(person, accountId, root, `Token ${token.name} revoked.`);
+    }
+    const bucket = page[3] ? decodeURIComponent(page[3]) : undefined;
+    if (!bucket)
+        return undefined;
+    if (!rowsOf('r2_bucket', root).some((b) => b.account_id === accountId && b.name === bucket))
+        return flowPage({ title: 'Not found | Cloudflare', css: [PORTAL_CSS, SKIN], status: 404, body: _jsx(Portal, { merchant: accountName(accountId, root), back: { href: `/${accountId}/r2/overview`, label: 'R2 Object Storage' }, notice: `There is no bucket named ${bucket}.`, sections: [] }) });
+    const settings = `/${accountId}/r2/default/buckets/${bucket}/settings`;
+    if (where.endsWith('/settings'))
+        return request.method === 'GET' ? bucketSettingsPage(person, accountId, bucket, root) : notAllowed();
+    if (!roles.some((r) => ADMINS.has(r)))
+        return bucketSettingsPage(person, accountId, bucket, root, 'Your role cannot change this bucket\'s settings.', 403);
+    if (where.endsWith('/custom-domains') && request.method === 'POST') {
+        const domain = ((await formOf(request)).domain ?? '').trim().toLowerCase();
+        // "The domain being used must have been added as a zone in the same account as the R2 bucket."
+        const zone = rowsOf('zone', root).filter((z) => z.account_id === accountId).find((z) => domain === z.name || domain.endsWith(`.${String(z.name)}`));
+        if (!zone)
+            return bucketSettingsPage(person, accountId, bucket, root, `${domain || 'That domain'} is not in a zone of this account. Add the domain to Cloudflare first.`, 422);
+        if (r2CustomDomains(root).some((d) => d.domain === domain))
+            return bucketSettingsPage(person, accountId, bucket, root, `${domain} is already connected to a bucket.`, 409);
+        await connectR2CustomDomain({ accountId, bucket, domain, enabled: true, zoneId: String(zone.id), zoneName: String(zone.name) }, root, occurredAt);
+        return redirect(settings);
+    }
+    if (where.endsWith('/custom-domains/remove') && request.method === 'POST') {
+        const domain = ((await formOf(request)).domain ?? '').trim().toLowerCase();
+        const d = r2CustomDomains(root).find((x) => x.account_id === accountId && x.bucket === bucket && x.domain === domain);
+        if (!d)
+            return bucketSettingsPage(person, accountId, bucket, root, `${domain} is not connected to this bucket.`, 422);
+        await removeR2CustomDomain(d.id, root, occurredAt);
+        return redirect(settings);
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@volter/twin-cloudflare",
+  "version": "0.1.0",
+  "description": "Local Cloudflare API twin for accounts, zones, Cloudflare Tunnels, tunnel configurations and zone DNS records, built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/cloudflare"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/cloudflare#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-cloudflare": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@volter/world-ui": "0.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "cloudflare": "7.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}