@volter/twin-tunnel 0.1.37 → 1.0.1

package/dist/src/cli.js

@@ -1,59 +1,21 @@
 #!/usr/bin/env node
-import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-tunnel: serve the tunnel twin.
 import { hasFlag, optionValue } from '@volter/world-core/args';
-import { createTunnelTwinServer, parseTunnelLoopbackOrigin } from "./tunnel-server.js";
-const [command, ...args] = process.argv.slice(2);
-const rawPort = optionValue(args, '--port');
-const port = rawPort === undefined ? undefined : Number(rawPort);
-if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535)) {
-    process.stderr.write(`world-tunnel: --port must be an integer 0-65535 (got ${JSON.stringify(rawPort)})\n`);
-    process.exit(2);
-}
-const root = optionValue(args, '--root') || undefined;
-if (command === 'serve') {
-    const server = createTunnelTwinServer({
-        ...(port ? { port } : {}),
-        ...(root ? { root } : {}),
-        readOnly: hasFlag(args, '--read-only'),
-        requireTid: hasFlag(args, '--require-tid'),
-    });
-    process.stdout.write(`tunnel twin listening on ${server.url}\n`);
-    process.stdout.write(`Volter SDK host=${server.url}; Cloudflare quick service=${server.url}\n`);
-    await keepProcessAlive();
-}
-else if (command === 'quick' || command === 'tunnel') {
-    const origin = optionValue(args, '--url');
-    if (!origin) {
-        process.stderr.write('world-tunnel quick requires --url http://127.0.0.1:<port>\n');
-        process.exit(2);
-    }
-    try {
-        parseTunnelLoopbackOrigin(origin);
-    }
-    catch (error) {
-        process.stderr.write(`world-tunnel quick: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(2);
-    }
-    const server = createTunnelTwinServer({ ...(port ? { port } : {}), ...(root ? { root } : {}) });
-    const allocation = await fetch(`${server.url}/tunnel`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
-    const body = await allocation.json();
-    if (!allocation.ok || !body.success || !body.result)
-        throw new Error('quick-tunnel allocation failed');
-    server.registerQuickOrigin(body.result.id, origin);
-    // The world runtime discovers the first URL in stdout. This is deliberately a loopback URL:
-    // the twin proves the control plane and genuine HTTP forwarding, not Cloudflare edge/DNS/TLS.
-    process.stdout.write(`VOLTER_SHARE_URL=${server.url}\n`);
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createTunnelTwinServer } from "./server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = optionValue(rest, '--database') || undefined;
+// the World's scenario file, for a model vendor's turns
+const scenarioPath = optionValue(rest, '--scenario') || undefined;
+if (cmd === 'serve' || cmd === undefined) {
+    const s = await createTunnelTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });
+    process.stdout.write(`tunnel twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
     await keepProcessAlive();
 }
-else if (command === 'conformance') {
-    // Dev-only and lazy: the runtime entrypoint does not pull conformance into normal serve/share.
-    const { checkTunnelConformance } = await import("./tunnel-conformance.js");
-    const report = await checkTunnelConformance({ ...(root ? { root } : {}) });
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    if (!report.ok)
-        process.exitCode = 1;
-}
 else {
-    process.stdout.write('Usage: world-tunnel serve|conformance [--port N] [--root DIR] [--read-only] [--require-tid]\n');
-    process.stdout.write('       world-tunnel quick --url http://127.0.0.1:<port> [--port N] [--root DIR]\n');
+    process.stdout.write('Usage: world-tunnel serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\n');
 }

package/dist/src/fetch.d.ts

@@ -0,0 +1,2 @@
+import { type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+export declare function createTunnelFetch(options?: PackFetchOptions): DerivedFetch;

package/dist/src/fetch.js

@@ -0,0 +1,19 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { around } from "./semantics/around.js";
+import * as sockets from "./semantics/sockets.js";
+import * as doors from "./semantics/doors.js";
+import { tunnelSemantics } from "./semantics/index.js";
+export function createTunnelFetch(options = {}) {
+    return createPackFetch({
+        manifest,
+        surface: surface,
+        handlers: tunnelSemantics,
+        doors,
+        around,
+        sockets,
+    }, options);
+}

package/dist/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.json","format":"openapi","version":"2","resources":[],"operations":[{"id":"getStatus","method":"get","path":"/api/status","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"}]}

package/dist/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"_account":{"actions":[],"states":{},"embeds":{}},"_tunnel":{"actions":[],"states":{},"embeds":{}}}}

package/dist/src/index.d.ts

@@ -1,7 +1,5 @@
-export { createTunnelTwinFetch, createTunnelTwinHandler, createTunnelTwinServer } from './tunnel-server.js';
-export { handleTunnelRelayMessage, handleTunnelTwinRequest } from './tunnel-twin.js';
-export { liveTunnelExecute, mapTunnelRelay, pullTunnelRelay, syncTunnelFromReal } from './tunnel-connector.js';
-export { TunnelBudget, TunnelBudgetError, TUNNEL_RATE_BUDGET, TUNNEL_BUDGET_CEILING, TUNNEL_BUDGET_WINDOW_MS, TUNNEL_CALL_WEIGHTS, } from './tunnel-budget.js';
-export type { RelayControlMessage, RelaySession, TunnelRequest, TunnelResponse } from './tunnel-twin.js';
-import type { TwinPack } from '@volter/world-core';
-export declare const pack: TwinPack;
+import { manifest } from './manifest.js';
+export { createTunnelFetch } from './fetch.js';
+export { createTunnelTwinServer } from './server.js';
+export { manifest };
+export declare const pack: import("@volter/world-core").PackDescriptor;

package/dist/src/index.js

@@ -1,42 +1,9 @@
-export { createTunnelTwinFetch, createTunnelTwinHandler, createTunnelTwinServer } from "./tunnel-server.js";
-export { handleTunnelRelayMessage, handleTunnelTwinRequest } from "./tunnel-twin.js";
-export { liveTunnelExecute, mapTunnelRelay, pullTunnelRelay, syncTunnelFromReal } from "./tunnel-connector.js";
-export { TunnelBudget, TunnelBudgetError, TUNNEL_RATE_BUDGET, TUNNEL_BUDGET_CEILING, TUNNEL_BUDGET_WINDOW_MS, TUNNEL_CALL_WEIGHTS, } from "./tunnel-budget.js";
-import { TUNNEL_RATE_BUDGET as RATE_BUDGET } from "./tunnel-budget.js";
-export const pack = {
-    vendor: 'tunnel',
-    // The SAME object tunnel-budget.ts declares at module load — one source of truth, so
-    // registering the pack and importing the connector can never arm two different ceilings.
-    rateBudget: RATE_BUDGET,
-    // The CONTROL plane is HTTP/REST (POST /tunnel, GET /api/status). The relay's control link is a
-    // WebSocket and its data path is real loopback HTTP — neither is a raw line protocol, so this is
-    // not the `raw-tcp` class; the split is described in the README and spec-sources.json.
-    transport: 'rest',
-    archetype: 'proxy',
-    bin: 'world-tunnel',
-    // The subject types the twin stores: `quick_tunnel`/`relay_tunnel` written by tunnel-twin.ts,
-    // and `relay` folded by the connector's status pull (mapTunnelRelay).
-    resources: ['quick_tunnel', 'relay_tunnel', 'relay'],
-    specSource: 'No single first-party machine-readable spec spans this combined pack. The Cloudflare Quick Tunnel ' +
-        'half is pinned to first-party cloudflared commit 733bfb939963e150dcf5c4faddb1603f744fbc98 (POST ' +
-        '/tunnel and its {success,result,errors} envelope) plus Cloudflare\'s own Quick Tunnels docs; the ' +
-        'owned Volter relay half is pinned to volter-ai/volter-tunnel commit ' +
-        'a5abc6287384429d32cde200d8ecd042814e6619 (@volter/tunnel 2.0.5, @volter/tunnel-core\'s 15 control ' +
-        'frames). See spec-sources.json.',
-    description: 'Cloudflare Quick Tunnel control-plane and owned Volter relay twin — POST /tunnel allocation and the ' +
-        '@volter/tunnel WebSocket control protocol, with a genuine loopback HTTP data path (no Cloudflare ' +
-        'edge, DNS, TLS or SLA claimed).',
-    // INTERCEPTION RULING — hostsNone, the pack's own home for it: no injector entry by design:
-    // native cloudflared is an external binary, while @volter/tunnel opens a configurable
-    // WebSocket control channel and the CLI reads TUNNEL_SERVER_URL. Worlds wire that app-read
-    // endpoint directly; claiming api.trycloudflare.com in the Node injector would not redirect
-    // cloudflared and would falsely imply the Cloudflare edge data plane was twinned.
-    hostsNone: "no injector entry by design: native cloudflared is an external binary, while @volter/tunnel opens a configurable WebSocket control channel and the CLI reads TUNNEL_SERVER_URL. Worlds wire that app-read endpoint directly; claiming api.trycloudflare.com in the Node injector would not redirect cloudflared and would falsely imply the Cloudflare edge data plane was twinned",
-    // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
-    // 2026-08-31).
-    adoption: {
-        // Internal Volter tunnel; the client is `@volter/tunnel` and there is no Python distribution.
-        pypi: [],
-        sdks: ['@volter/tunnel'], envStems: ['TUNNEL', 'VOLTERTUNNEL'],
-    },
-};
+// @volter/twin-tunnel — the tunnel twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface (architecture, "The real-system adapters").
+import { packOf, registerPack } from '@volter/world-core';
+import { manifest } from "./manifest.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+export { createTunnelFetch } from "./fetch.js";
+export { createTunnelTwinServer } from "./server.js";
+export { manifest };
+export const pack = registerPack(packOf(manifest, surface));

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,49 @@
+export const manifest = {
+    vendor: 'tunnel',
+    service: 'tunnel',
+    body: { json: 'always' },
+    unmodeled: ['getStatus'],
+    vendorBacked: { none: 'The served wire forwards HTTP over a live control socket; account and reservation rows are World bookkeeping, with no served vendor resource API to perform or refresh.' },
+    // source: spec:/x-reference/relay "crypto.randomUUID().slice(0, 8)"
+    ids: { template: '{letters:8}' },
+    time: 'iso',
+    error: '{message}',
+    readOnly: { status: 403, message: 'This twin was started read-only; writes are refused.' },
+    // The unserved HTTP operations use the pack gap; the served socket refuses in protocol frames.
+    notFound: { status: 404, message: 'Not Found' },
+    gap: { status: 404, message: 'Not Found' },
+    list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+    deleted: {},
+    resources: {
+        _account: { idPrefix: '' },
+        // a tunnel id an account holds (one minted when a client names none)
+        _tunnel: { idPrefix: '' },
+    },
+    // source: spec:/x-reference/protocol "for the messages exchanged over the control WebSocket between a client and the"
+    sockets: [
+        { id: 'control', path: '/ws', note: "a client's control channel: register, then answer each request the relay sends", source: 'https://github.com/volter-ai/volter-tunnel/blob/main/packages/core/src/protocol.ts' },
+    ],
+    doors: [
+        { id: 'accounts', method: 'POST', path: '/_twin/accounts', note: '{ slug }: an account on the relay and its token (the World application\'s TUNNEL_SECRET)' },
+    ],
+    discovery: {
+        twinOf: "Volter's tunnel relay (volter-tunnel) as Volter Harness's remote access uses it: a client's control socket, and every request to its tunnel answered through it",
+        stores: 'accounts and their tokens (by their SHA-256), and the tunnel ids they hold',
+        identity: "the account's token in the control channel's register frame",
+    },
+    descriptor: {
+        protocol: '3',
+        transport: 'rest',
+        archetype: 'proxy',
+        bin: 'world-tunnel',
+        resources: [],
+        specSource: 'written from volter-ai/volter-tunnel (spec/SOURCE.md)',
+        description: "Tunnel relay twin — a client's control socket (register, then each public request sent down it and answered by the frames it sends back), as Volter Harness's remote access shares a local server.",
+        // source: spec:/x-reference/protocol "Shared secret or api/login token authenticating the client."
+        adoption: { sdks: ['@volter/tunnel'], envStems: ['TUNNEL', 'VOLTERTUNNEL'] },
+        // source: spec:/x-reference/domain "voltertest.xyz"
+        hosts: [{ host: 'voltertest.xyz' }, { suffix: '.voltertest.xyz' }, { host: 'www.voltertest.xyz', exclude: true }, { host: 'twins.voltertest.xyz', exclude: true }],
+        credentialDoor: { path: '/_twin/accounts', body: { slug: 'world' }, fill: { TUNNEL_SECRET: 'token', TUNNEL_SERVER_URL: 'server', SUPERCODE_TUNNEL_SERVER_URL: 'server' } },
+        endpointEnvNone: 'the relay URL is the credential door\'s (TUNNEL_SERVER_URL, SUPERCODE_TUNNEL_SERVER_URL), the World claiming voltertest.xyz',
+    },
+};

package/dist/src/semantics/around.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response>;

package/dist/src/semantics/around.js

@@ -0,0 +1,72 @@
+import { b64encode, cors, DOMAIN, holder, requests, RESERVED } from "./shared.js";
+const text = (status, body) => new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+// World transport metadata belongs to the World; preserve the application's own x-volter-* headers.
+const INTERNAL = new Set(['x-volter-token', 'x-volter-pass', 'x-volter-read-only', 'x-volter-twin-original-host', 'x-volter-scenario-decision', 'x-volter-path-prefix-params', 'x-volter-lane']);
+/** The tunnel a request is for: its host's label, or `?__tunnel=` on a direct host (the relay's local testing). */
+function tunnelOf(request) {
+    const url = new URL(request.url);
+    const host = (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host).toLowerCase().replace(/:\d+$/, '');
+    const label = host.endsWith(`.${DOMAIN}`) ? host.slice(0, -DOMAIN.length - 1) : undefined;
+    if (label && !label.includes('.') && !RESERVED.has(label))
+        return label;
+    // source: spec:/x-reference/routing "host.endsWith('.workers.dev')"
+    const direct = host.endsWith('.workers.dev') || host === 'localhost' || host === '127.0.0.1' || host === '0.0.0.0';
+    return direct ? url.searchParams.get('__tunnel') ?? undefined : undefined;
+}
+export async function around(ctx, next) {
+    const request = ctx.call.request;
+    const id = tunnelOf(request);
+    if (!id)
+        return next();
+    // source: spec:/x-reference/auth "The relay answers preflight itself"
+    if (request.method === 'OPTIONS')
+        return new Response(null, { status: 204, headers: cors(request) });
+    const client = holder(ctx, id);
+    // source: spec:/x-reference/relay "Tunnel not connected"
+    if (!client)
+        return text(502, 'Tunnel not connected');
+    const url = new URL(request.url);
+    // source: spec:/x-reference/auth "u.searchParams.delete('__volter_token');"
+    url.searchParams.delete('__tunnel');
+    url.searchParams.delete('__volter_token');
+    const body = request.method === 'GET' || request.method === 'HEAD' ? null : new Uint8Array(await request.arrayBuffer());
+    // source: spec:/x-reference/relay "bodyBytes.length > 750_000"
+    if (body && body.length > 750_000)
+        return text(413, 'Request body too large to tunnel (limit ~750KB)');
+    const headers = Object.fromEntries([...request.headers].filter(([k]) => !INTERNAL.has(k.toLowerCase())));
+    // The injector preserves the visitor's vendor Host in the same metadata used by kernel host routing.
+    headers.host = request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host;
+    // source: spec:/x-reference/relay "Never trust a visitor-supplied"
+    delete headers['x-forwarded-for'];
+    headers['x-forwarded-for'] = request.headers.get('cf-connecting-ip') || '0.0.0.0';
+    // source: spec:/x-reference/auth "Strip the __volter_auth cookie"
+    if (headers.cookie) {
+        const cookie = headers.cookie.split(';').filter((pair) => pair.trim().split('=')[0] !== '__volter_auth').join(';').trim();
+        if (cookie)
+            headers.cookie = cookie;
+        else
+            delete headers.cookie;
+    }
+    // the relay's correlation key for this request on this client's socket: the socket's own count, not World state (a
+    // request the relay forwards is no subject of the World)
+    const reqId = `${id}-${(client.state.requests = Number(client.state.requests ?? 0) + 1)}`;
+    // Register the wait before sending so a synchronous client can answer the frame.
+    requests(client).set(reqId, request);
+    const answered = client.expect(reqId, 30_000);
+    // source: spec:/x-reference/protocol "An inbound HTTP request to forward to the local server."
+    client.send({ type: 'request', reqId, method: request.method, path: `${url.pathname}${url.search}`, headers, body: body?.length ? b64encode(body) : null });
+    try {
+        return (await answered);
+    }
+    catch {
+        // source: spec:/x-reference/relay "Tunnel disconnected"
+        return !ctx.sockets('control').includes(client) ? text(502, String(client.state.disconnectReason ?? 'Tunnel disconnected')) : timeout();
+    }
+    finally {
+        requests(client).delete(reqId);
+    }
+}
+// source: spec:/x-reference/relay "Tunnel timeout"
+function timeout() {
+    return text(504, 'Tunnel timeout');
+}

package/dist/src/semantics/doors.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+/** An account by its slug (answered again for the same slug) and its token, drawn from the World's secret. */
+export declare function accounts(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/doors.js

@@ -0,0 +1,18 @@
+import { ACCOUNT, sha256 } from "./shared.js";
+/** An account by its slug (answered again for the same slug) and its token, drawn from the World's secret. */
+export async function accounts(ctx) {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {});
+    const slug = String(b.slug ?? '');
+    // source: spec:/x-reference/credentials "const SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;"
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/.test(slug))
+        return Response.json({ message: 'slug must be lowercase letters, digits and dashes' }, { status: 400 });
+    let account = ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.slug === slug);
+    // Where the documentation stops: a token's form is the relay's own; the twin's is `vt_` and 40 letters and digits
+    const tokenOf = async (id) => `vt_${ctx.crypto.base62From(await ctx.secret(`tunnel-token:${id}`), 40)}`;
+    if (!account) {
+        const id = ctx.mint(ACCOUNT);
+        await ctx.record(ACCOUNT, { slug, token_sha256: sha256(ctx, await tokenOf(id)) }, id);
+        account = ctx.row(ACCOUNT, id);
+    }
+    return Response.json({ slug, token: await tokenOf(String(account.id)), server: `https://voltertest.xyz` }, { status: 201 });
+}

package/dist/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const tunnelSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1 @@
+export const tunnelSemantics = {};

package/dist/src/semantics/shared.d.ts

@@ -0,0 +1,22 @@
+import type { HandlerContext, SocketSession } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+export type { HandlerContext };
+export declare const ACCOUNT = "_account";
+export declare const TUNNEL = "_tunnel";
+export declare const DOMAIN = "voltertest.xyz";
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export declare const RESERVED: Set<string>;
+export declare const sha256: (ctx: Pick<HandlerContext, "crypto">, v: string) => string;
+export declare const tunnelUrl: (id: string) => string;
+/** The registered control session holding a tunnel, if a client holds it now. */
+export declare const holder: (ctx: Pick<HandlerContext, "sockets">, id: string) => SocketSession | undefined;
+export declare const b64encode: (bytes: Uint8Array) => string;
+export declare const b64decode: (text: string) => Uint8Array<ArrayBuffer>;
+export declare function cors(request: Request): Record<string, string>;
+/** Request metadata lasts only until the local client starts its reply, on that live connection. */
+export declare function requests(s: SocketSession): Map<string, Request>;
+export declare function responseHeaders(downstream: Headers, request: Request): Headers;
+export declare function bufferedBody(text: unknown): Uint8Array<ArrayBuffer> | null | undefined;
+/** A provisional connection claim prevents two initial registrants passing the live-session decision. */
+export declare function claimant(ctx: Pick<HandlerContext, 'sockets'>, id: string): SocketSession | undefined;

package/dist/src/semantics/shared.js

@@ -0,0 +1,73 @@
+export const ACCOUNT = '_account';
+export const TUNNEL = '_tunnel';
+// source: spec:/x-reference/domain "voltertest.xyz"
+export const DOMAIN = 'voltertest.xyz';
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export const RESERVED = new Set(['www', 'twins']);
+export const sha256 = (ctx, v) => ctx.crypto.digest('sha256', v);
+export const tunnelUrl = (id) => `https://${id}.${DOMAIN}`;
+/** The registered control session holding a tunnel, if a client holds it now. */
+export const holder = (ctx, id) => ctx.sockets('control').find((s) => s.state.registered === true && s.state.tunnelId === id);
+export const b64encode = (bytes) => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+export const b64decode = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+// source: spec:/x-reference/auth "The relay answers preflight itself"
+export function cors(request) {
+    const origin = request.headers.get('origin');
+    return origin ? {
+        'access-control-allow-origin': origin,
+        'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+        'access-control-allow-headers': request.headers.get('access-control-request-headers') || 'Content-Type, Authorization, X-Sandbox-Id',
+        'access-control-allow-credentials': 'true',
+    } : {};
+}
+/** Request metadata lasts only until the local client starts its reply, on that live connection. */
+export function requests(s) {
+    return (s.state.pendingRequests ??= new Map());
+}
+// source: spec:/x-reference/auth "Build the downstream response headers: drop hop-by-hop + downstream CORS"
+export function responseHeaders(downstream, request) {
+    const headers = new Headers(downstream);
+    for (const key of ['transfer-encoding', 'connection', 'access-control-allow-origin', 'access-control-allow-methods', 'access-control-allow-headers', 'access-control-allow-credentials', 'x-frame-options'])
+        headers.delete(key);
+    // source: spec:/x-reference/auth "strip CSP frame-ancestors / X-Frame-Options"
+    for (const key of ['content-security-policy', 'content-security-policy-report-only']) {
+        const value = headers.get(key);
+        if (value) {
+            const kept = value.split(';').filter((d) => !d.trim().startsWith('frame-ancestors')).join(';').trim();
+            if (kept)
+                headers.set(key, kept);
+            else
+                headers.delete(key);
+        }
+    }
+    // source: spec:/x-reference/auth "only a downstream response that clearly says"
+    const cache = (headers.get('cache-control') ?? '').toLowerCase();
+    const publicCache = /(?:^|,)\s*public(?:\s|,|$)/.test(cache) && !/(?:^|,)\s*(?:private|no-store|no-cache)(?:\s|,|=|$)/.test(cache);
+    const path = new URL(request.url).pathname;
+    if (!publicCache || path === '/api' || path.startsWith('/api/')) {
+        headers.set('cache-control', 'private, no-store, max-age=0');
+        headers.set('cloudflare-cdn-cache-control', 'no-store');
+        headers.set('cdn-cache-control', 'no-store');
+        const vary = new Set((headers.get('vary') ?? '').split(',').map((v) => v.trim()).filter(Boolean));
+        vary.add('Cookie');
+        vary.add('Authorization');
+        headers.set('vary', [...vary].join(', '));
+    }
+    for (const [key, value] of Object.entries(cors(request)))
+        headers.set(key, value);
+    return headers;
+}
+// source: spec:/x-reference/relay "Malformed tunnel response"
+export function bufferedBody(text) {
+    try {
+        return text ? b64decode(String(text)) : null;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A provisional connection claim prevents two initial registrants passing the live-session decision. */
+export function claimant(ctx, id) {
+    return ctx.sockets('control').find((s) => s.state.superseded !== true && (s.state.registered === true || s.state.registering === true) && s.state.tunnelId === id);
+}

package/dist/src/semantics/sockets.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext, SocketEngine } from '@volter/world-core';
+export declare const control: SocketEngine<HandlerContext>;

package/dist/src/semantics/sockets.js

@@ -0,0 +1,161 @@
+import { ACCOUNT, b64decode, bufferedBody, claimant, requests, responseHeaders, sha256, TUNNEL, tunnelUrl } from "./shared.js";
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const streams = (s) => (s.state.streams ??= new Map());
+const headersOf = (v) => { const h = new Headers(); for (const [k, x] of Object.entries(obj(v)))
+    h.set(k, String(x)); return h; };
+/** A rejected registration: the error frame, then the close (protocol.ts `ErrorMsg`; tunnel-do's rejection). */
+function reject(s, message, code, reason) {
+    s.send({ type: 'error', message });
+    s.close(code, reason);
+}
+async function register(s, msg, ctx) {
+    const token = typeof msg.secret === 'string' ? msg.secret : '';
+    const account = token ? ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.token_sha256 === sha256(ctx, token)) : undefined;
+    // source: spec:/x-reference/relay "Invalid tunnel secret"
+    if (!account)
+        return reject(s, 'Invalid tunnel secret', 4003, 'Invalid tunnel secret');
+    // the control URL's ?id= names the tunnel (the routing relay's authority), else the register frame's, else one minted
+    // This id names a stored reservation: mint it, then record the reservation with its owner below. ctx.issue is for
+    // issued ids whose subjects the vendor does not store; its empty row would look like another account's reservation.
+    // source: spec:/x-reference/relay "Prefer the ?id= captured at accept (authoritative"
+    const id = String(s.state.tunnelId || msg.tunnelId || ctx.mint(TUNNEL));
+    const held = ctx.row(TUNNEL, id);
+    // source: spec:/x-reference/relay "Tunnel ID reserved"
+    if (held && held._owner !== account.id)
+        return reject(s, `Tunnel ID '${id}' is reserved by another account.`, 4002, 'Tunnel ID reserved');
+    const live = claimant(ctx, id);
+    if (live && live !== s) {
+        // source: spec:/x-reference/relay "Pass { replace: true } to take over."
+        if (msg.replace !== true)
+            return reject(s, `Tunnel ID '${id}' is already in use by another client. Pass { replace: true } to take over.`, 4002, 'Tunnel ID already in use');
+        // source: spec:/x-reference/relay "Tunnel replaced"
+        live.state.superseded = true;
+        live.state.disconnectReason = 'Tunnel replaced';
+        live.state.registered = false;
+        // source: spec:/x-reference/relay "Replaced by new client"
+        live.close(4001, 'Replaced by new client');
+    }
+    Object.assign(s.state, { registering: true, tunnelId: id, account: account.id });
+    try {
+        if (!held)
+            await ctx.record(TUNNEL, { _owner: account.id, reservedAt: ctx.occurredAt }, id);
+    }
+    finally {
+        s.state.registering = false;
+    }
+    if (s.state.superseded === true || !ctx.sockets('control').includes(s))
+        return;
+    Object.assign(s.state, { registered: true, tunnelId: id, account: account.id, authRequired: msg.authRequired !== false });
+    // source: spec:/x-reference/protocol "Acknowledges a successful registration; carries the public URL + usage."
+    s.send({ type: 'registered', tunnelId: id, url: tunnelUrl(id) });
+}
+export const control = {
+    open(s, ctx) {
+        s.state.tunnelId = new URL(ctx.call.request.url).searchParams.get('id') ?? '';
+    },
+    async message(s, data, ctx) {
+        let msg;
+        try {
+            msg = obj(JSON.parse(data));
+        }
+        catch {
+            return;
+        }
+        if (msg.type === 'register')
+            return register(s, msg, ctx);
+        if (s.state.registered !== true)
+            return;
+        const reqId = String(msg.reqId ?? '');
+        const request = requests(s).get(reqId);
+        // source: spec:/x-reference/protocol "A complete (buffered) response"
+        if (msg.type === 'response') {
+            if (!request)
+                return;
+            const headers = responseHeaders(headersOf(msg.headers), request);
+            const body = bufferedBody(msg.body);
+            // source: spec:/x-reference/relay "Malformed tunnel response"
+            if (body === undefined)
+                s.fulfil(reqId, new Response('Malformed tunnel response', { status: 502, headers }));
+            else
+                s.fulfil(reqId, new Response(request.method === 'HEAD' ? null : body, { status: Number(msg.status || 200), headers }));
+            // source: spec:/x-reference/protocol "Start of a streamed response"
+        }
+        else if (msg.type === 'response-start') {
+            if (!request)
+                return;
+            const status = Number(msg.status || 200);
+            const headers = responseHeaders(headersOf(msg.headers), request);
+            // source: spec:/x-reference/relay "HEAD is bodyless by contract too."
+            if (request.method === 'HEAD' || status === 204 || status === 205 || status === 304) {
+                s.fulfil(reqId, new Response(null, { status, headers }));
+            }
+            else {
+                const body = new ReadableStream({ start: (c) => { streams(s).set(reqId, c); }, cancel: () => cancelStream(s, reqId) });
+                armStreamIdle(s, reqId, ctx);
+                s.fulfil(reqId, new Response(body, { status, headers }));
+            }
+            // source: spec:/x-reference/protocol "One streamed response body chunk."
+        }
+        else if (msg.type === 'response-chunk') {
+            const stream = streams(s).get(reqId);
+            if (stream) {
+                try {
+                    stream.enqueue(b64decode(String(msg.data ?? '')));
+                    s.fulfil(`idle:${reqId}`, null);
+                    armStreamIdle(s, reqId, ctx);
+                }
+                catch {
+                    streams(s).delete(reqId);
+                    s.fulfil(`idle:${reqId}`, null);
+                }
+            }
+            // source: spec:/x-reference/protocol "End of a streamed response."
+        }
+        else if (msg.type === 'response-end') {
+            const stream = streams(s).get(reqId);
+            streams(s).delete(reqId);
+            s.fulfil(`idle:${reqId}`, null);
+            if (stream) {
+                try {
+                    stream.close();
+                }
+                catch { /* already closed */ }
+            }
+        }
+    },
+    close(s) {
+        s.state.registered = false;
+        s.state.closed = true;
+        for (const c of streams(s).values()) {
+            try {
+                c.error(new Error('Tunnel closed'));
+            }
+            catch { /* already ended */ }
+        }
+        streams(s).clear();
+    },
+};
+// source: spec:/x-reference/relay "Idle watchdog for a streaming response"
+function armStreamIdle(s, reqId, ctx) {
+    // source: spec:/x-reference/relay "120000"
+    void s.expect(`idle:${reqId}`, 120_000).catch(() => { if (ctx.sockets('control').includes(s))
+        expireStream(s, reqId); });
+}
+// source: spec:/x-reference/relay "stream idle timeout"
+function expireStream(s, reqId) {
+    const stream = streams(s).get(reqId);
+    if (!stream)
+        return;
+    streams(s).delete(reqId);
+    try {
+        stream.error(new Error('stream idle timeout'));
+    }
+    catch { /* already closed */ }
+    s.send({ type: 'request-abort', reqId });
+}
+// source: spec:/x-reference/protocol "The relay asks the client to abort an in-flight request."
+function cancelStream(s, reqId) {
+    streams(s).delete(reqId);
+    s.fulfil(`idle:${reqId}`, null);
+    s.send({ type: 'request-abort', reqId });
+}

package/dist/src/semantics/states.d.ts

@@ -0,0 +1 @@
+export declare const states: {};

package/dist/src/semantics/states.js

@@ -0,0 +1,3 @@
+// The relay's state rulings (architecture, "State"): a tunnel id is held by the account that registered it first; a
+// session's registration is the connection's, never World state.
+export const states = {};

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createTunnelTwinServer(options?: PackFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;