@volter/twin-tunnel 0.1.0

package/dist/src/tunnel-server.js

@@ -0,0 +1,1197 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { isIP } from 'node:net';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { getActiveWorldStore, withFileLock, withWorldStore, worldNow, worldPaths, statefulTwinManifest, TWIN_PREFIX_HEADER, twinPublicBase } from '@volter/world-core';
+import { handleTunnelTwinRequest, markTunnelDisconnected, persistTunnelRelayRegistration, prepareTunnelRelayRegistration, reduceTunnelWsFrame, revertTunnelRelayRegistration, } from "./tunnel-twin.js";
+/**
+ * Is a bridge's control socket still able to receive?
+ *
+ * `ServerWebSocket.send` returns 0 on a closed socket rather than throwing, so every
+ * `try { owner.send(...) } catch` around it was dead code (§9). Liveness is a STATE to read,
+ * not an exception to wait for.
+ */
+function ownerAlive(visitor) {
+    return visitor.owner.readyState === 1 && !visitor.owner.data.closed;
+}
+/** How much a visitor may send before its local socket is ready, so a pre-`ws-ready` frame is
+ *  queued rather than dropped — and a visitor that floods before the bridge exists is refused. */
+const VISITOR_PREREADY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_JWT_SECRET = 'twin-local-jwt-secret';
+const RELAY_CLAIM_STALE_MS = 60_000;
+const RELAY_CLAIM_HEARTBEAT_MS = 5_000;
+function relayClaimPath(root, tunnelId) {
+    return join(worldPaths('tunnel', root).dir, 'relay-claims', `${tunnelId}.json`);
+}
+function readRelayClaim(path) {
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null)
+        return undefined;
+    let claim;
+    try {
+        claim = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Relay ownership claim is corrupt: ${path}`);
+    }
+    if (!claim || typeof claim !== 'object' || typeof claim.token !== 'string'
+        || typeof claim.serverId !== 'string' || typeof claim.socketId !== 'string'
+        || !Number.isInteger(claim.pid) || claim.pid <= 0 || typeof claim.hostname !== 'string'
+        || typeof claim.claimedAt !== 'string'
+        || (claim.heartbeatAt !== undefined && typeof claim.heartbeatAt !== 'string')
+        || !['reserving', 'active'].includes(claim.state)) {
+        throw new Error(`Relay ownership claim is malformed: ${path}`);
+    }
+    return claim;
+}
+/**
+ * A claim is alive while its own HEARTBEAT is fresh — one rule, every host.
+ *
+ * The relay writes that heartbeat itself: at reservation (connect), on its control traffic, and
+ * on the idle keepalive; `markTunnelDisconnected` records the other end of the same fact. So
+ * liveness is STATE this twin already holds, readable from any process sharing the root, and the
+ * serve path never asks the operating system who is running. A `ps`/`kill(pid, 0)` probe answers
+ * only about THIS box — it is silent about a relay owning the id from another host, unavailable
+ * on a serverless shell (runtime contract R12b), and in any case only ever a faster negative:
+ * a process that has stopped writing its heartbeat is reclaimed here within one stale window,
+ * whether it exited, hung, or had its pid handed to somebody else.
+ *
+ * Bounded in BOTH directions, so a host with a corrupt/far-future clock cannot reserve an id
+ * indefinitely, while one stale window still tolerates ordinary skew on a shared filesystem.
+ * The stamp is a WORLD instant, so it is compared against the world clock — mixing `Date.now()`
+ * in would call every claim in a clock-set world instantly stale.
+ */
+function relayClaimAlive(claim) {
+    const heartbeatAt = Date.parse(claim.heartbeatAt ?? claim.claimedAt);
+    if (!Number.isFinite(heartbeatAt))
+        return false;
+    const heartbeatAge = Date.parse(worldNow()) - heartbeatAt;
+    return heartbeatAge >= -RELAY_CLAIM_STALE_MS && heartbeatAge <= RELAY_CLAIM_STALE_MS;
+}
+/** Reserve the durable ownership slot before the registration action is appended. The small
+ * sidecar is a live-process coordination record, not projected vendor state. Its own lock makes
+ * the read/decision/write atomic across relay processes sharing one root; the `reserving` state
+ * keeps a second process out while the first process is awaiting injected/real persistence. */
+function reserveRelayClaim(input) {
+    const path = relayClaimPath(input.root, input.tunnelId);
+    return withFileLock(`${path}.lock`, () => {
+        const store = getActiveWorldStore();
+        let existing = readRelayClaim(path);
+        if (existing && !relayClaimAlive(existing)) {
+            store.remove(path);
+            existing = undefined;
+        }
+        // A reservation in flight can never be stolen. An active owner can be replaced only by the
+        // same server instance, which is the process that can actually make its old socket inert.
+        // Cross-process replacement without an IPC/data-plane handoff would create two live owners.
+        if (existing && (existing.state === 'reserving' || !input.replace || existing.serverId !== input.serverId)) {
+            return { ok: false };
+        }
+        const now = worldNow();
+        const claim = {
+            tunnelId: input.tunnelId,
+            token: input.token,
+            serverId: input.serverId,
+            socketId: input.socketId,
+            pid: process.pid,
+            hostname: hostname(),
+            state: 'reserving',
+            claimedAt: now,
+            heartbeatAt: now,
+        };
+        store.writeAtomic(path, `${JSON.stringify(claim)}\n`);
+        return { ok: true, ...(existing ? { previous: existing } : {}) };
+    });
+}
+function refreshRelayClaim(root, tunnelId, token) {
+    const path = relayClaimPath(root, tunnelId);
+    withFileLock(`${path}.lock`, () => {
+        const claim = readRelayClaim(path);
+        if (claim?.token === token) {
+            getActiveWorldStore().writeAtomic(path, `${JSON.stringify({ ...claim, heartbeatAt: worldNow() })}\n`);
+        }
+    });
+}
+function activateRelayClaim(root, tunnelId, token) {
+    const path = relayClaimPath(root, tunnelId);
+    withFileLock(`${path}.lock`, () => {
+        const claim = readRelayClaim(path);
+        if (!claim || claim.token !== token || claim.state !== 'reserving') {
+            throw new Error(`Relay ownership reservation was lost before commit: ${tunnelId}`);
+        }
+        getActiveWorldStore().writeAtomic(path, `${JSON.stringify({ ...claim, state: 'active' })}\n`);
+    });
+}
+function restoreRelayClaim(root, tunnelId, token, previous) {
+    const path = relayClaimPath(root, tunnelId);
+    withFileLock(`${path}.lock`, () => {
+        const claim = readRelayClaim(path);
+        if (!claim || claim.token !== token)
+            return;
+        if (previous)
+            getActiveWorldStore().writeAtomic(path, `${JSON.stringify(previous)}\n`);
+        else
+            getActiveWorldStore().remove(path);
+    });
+}
+function releaseRelayClaim(root, tunnelId, token) {
+    const path = relayClaimPath(root, tunnelId);
+    withFileLock(`${path}.lock`, () => {
+        if (readRelayClaim(path)?.token === token)
+            getActiveWorldStore().remove(path);
+    });
+}
+function b64url(value) {
+    return Buffer.from(value).toString('base64url');
+}
+export function createTunnelTwinJwt(payload, secret = DEFAULT_JWT_SECRET) {
+    const header = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+    const body = b64url(JSON.stringify(payload));
+    const signature = createHmac('sha256', secret).update(`${header}.${body}`).digest('base64url');
+    return `${header}.${body}.${signature}`;
+}
+function constantEqual(a, b) {
+    const aa = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return aa.length === bb.length && timingSafeEqual(aa, bb);
+}
+function verifyJwt(token, secret, tunnelId, requireTid) {
+    try {
+        const [header, body, signature, extra] = token.split('.');
+        if (!header || !body || !signature || extra !== undefined)
+            return false;
+        const parsedHeader = JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+        if (parsedHeader.alg !== 'HS256')
+            return false;
+        const expected = createHmac('sha256', secret).update(`${header}.${body}`).digest('base64url');
+        if (!constantEqual(signature, expected))
+            return false;
+        const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            return false;
+        const now = Math.floor(Date.now() / 1000);
+        if (payload.exp !== undefined && (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)))
+            return false;
+        if (payload.nbf !== undefined && (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf)))
+            return false;
+        if (typeof payload.exp === 'number' && payload.exp <= now)
+            return false;
+        if (typeof payload.nbf === 'number' && payload.nbf > now)
+            return false;
+        // Exact owned default: a string tid, when present, binds the token to that tunnel. A missing
+        // (or non-string) tid is shared SSO unless the operator explicitly enables REQUIRE_TID mode.
+        const tid = typeof payload.tid === 'string' ? payload.tid : undefined;
+        if (tid !== undefined)
+            return tid === tunnelId;
+        return !requireTid;
+    }
+    catch {
+        return false;
+    }
+}
+function jsonError(status, error) {
+    return Response.json({ error }, { status, headers: { 'cache-control': 'no-store' } });
+}
+function headersObject(headers) {
+    const out = {};
+    headers.forEach((value, key) => { out[key] = value; });
+    return out;
+}
+function corsHeaders(request) {
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return {};
+    return {
+        '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',
+    };
+}
+function responseHeaders(raw = {}, request, forwardedPath = '/', setCookie) {
+    const out = new Headers();
+    for (const [key, value] of Object.entries(raw)) {
+        const k = key.toLowerCase();
+        if (/^(connection|transfer-encoding|content-length|keep-alive|upgrade|x-frame-options)$/i.test(k))
+            continue;
+        if (/^access-control-allow-/i.test(k))
+            continue;
+        if (k === 'content-security-policy' || k === 'content-security-policy-report-only') {
+            const values = Array.isArray(value) ? value : [value];
+            for (const item of values) {
+                const cleaned = item.split(';').filter((part) => !part.trim().toLowerCase().startsWith('frame-ancestors')).join(';').trim();
+                if (cleaned)
+                    out.append(k, cleaned);
+            }
+            continue;
+        }
+        if (Array.isArray(value))
+            for (const item of value)
+                out.append(k, item);
+        else
+            out.set(k, value);
+    }
+    if (request)
+        for (const [key, value] of Object.entries(corsHeaders(request)))
+            out.set(key, value);
+    const cacheControl = (out.get('cache-control') ?? '').toLowerCase();
+    const explicitlyPublic = /(?:^|,)\s*public(?:\s|,|$)/.test(cacheControl)
+        && !/(?:^|,)\s*(?:private|no-store|no-cache)(?:\s|,|=|$)/.test(cacheControl);
+    const pathname = new URL(forwardedPath, 'http://twin.local').pathname;
+    if (!explicitlyPublic || pathname === '/api' || pathname.startsWith('/api/')) {
+        out.set('cache-control', 'private, no-store, max-age=0');
+        out.set('cloudflare-cdn-cache-control', 'no-store');
+        out.set('cdn-cache-control', 'no-store');
+        const vary = new Set((out.get('vary') ?? '').split(',').map((value) => value.trim()).filter(Boolean));
+        vary.add('Cookie');
+        vary.add('Authorization');
+        out.set('vary', [...vary].join(', '));
+    }
+    if (setCookie)
+        out.append('set-cookie', setCookie);
+    return out;
+}
+function validResponseStatus(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 200 && value <= 599;
+}
+function validResponseHeaders(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    try {
+        for (const [key, raw] of Object.entries(value)) {
+            if (!key || (typeof raw !== 'string' && !(Array.isArray(raw) && raw.every((item) => typeof item === 'string'))))
+                return false;
+            for (const item of Array.isArray(raw) ? raw : [raw])
+                new Headers([[key, item]]);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeBase64(value) {
+    if (typeof value !== 'string' || value.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value))
+        return undefined;
+    const bytes = Buffer.from(value, 'base64');
+    if (bytes.toString('base64').replace(/=+$/, '') !== value.replace(/=+$/, ''))
+        return undefined;
+    return bytes;
+}
+// This listener multiplexes an app origin with a deliberately small control plane. Keep known
+// provider-management namespaces out of the app fallback so an unsupported Cloudflare/owned
+// management call fails locally, while arbitrary product routes (including /api/*) still reach
+// the configured application.
+export function tunnelControlPathIsReserved(pathname) {
+    const maxPathLength = 8_192;
+    const maxDecodePasses = 8;
+    if (pathname.length > maxPathLength)
+        return true;
+    let path = pathname;
+    try {
+        // Decode repeatedly so an encoded separator cannot hide a management namespace, then
+        // normalize repeated slash/backslash separators and dot segments. This normalized value is
+        // used only for the control-plane decision; ordinary application requests retain their
+        // original path when forwarded below. Inputs that do not reach a fixed point inside the
+        // bounded work budget fail closed rather than becoming an origin-routing bypass.
+        let stable = false;
+        for (let i = 0; i < maxDecodePasses; i++) {
+            const decoded = decodeURIComponent(path);
+            if (decoded.length > maxPathLength)
+                return true;
+            if (decoded === path) {
+                stable = true;
+                break;
+            }
+            path = decoded;
+        }
+        if (!stable && decodeURIComponent(path) !== path)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const segments = [];
+    for (const segment of path.replaceAll('\\', '/').split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..')
+            segments.pop();
+        else
+            segments.push(segment);
+    }
+    path = `/${segments.join('/')}`;
+    return path === '/'
+        || /^\/(?:tunnel|api\/status|ws|__volter_auth|__volter_inspect|__volter_replay|__twin|docs)(?:\/|$)/.test(path)
+        || /^\/(?:accounts|zones|memberships|user|client\/v4|me|admin|signup|report|waitlist)(?:\/|$)/.test(path);
+}
+function canonicalDottedIpv4(host) {
+    const parts = host.split('.');
+    return parts.length === 4 && parts.every((part) => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255);
+}
+export function parseTunnelLoopbackOrigin(origin) {
+    const raw = /^https?:\/\/(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?\/?$/i.exec(origin);
+    if (!raw)
+        throw new Error('quick origin must use strict http(s) origin syntax');
+    const rawHost = raw[1];
+    const rawPort = raw[2];
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        throw new Error('quick origin must be a valid http(s) URL');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol))
+        throw new Error('quick origin must use http: or https:');
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    // Validate the raw numeric authority against WHATWG's normalized host. Otherwise forms such as
+    // 127.1, 0177.0.0.1, or 127.0.0.1. normalize into an apparently canonical loopback address.
+    if (!rawHost.startsWith('[') && isIP(hostname) === 4
+        && (!canonicalDottedIpv4(rawHost) || rawHost !== hostname)) {
+        throw new Error('quick origin IPv4 host must use canonical dotted-decimal syntax');
+    }
+    if (rawPort && rawPort.length > 1 && rawPort.startsWith('0')) {
+        throw new Error('quick origin port must use canonical decimal syntax');
+    }
+    const loopback = hostname === 'localhost' || hostname === '::1'
+        || (isIP(hostname) === 4 && hostname.split('.')[0] === '127');
+    if (!loopback)
+        throw new Error('quick origin must be loopback');
+    if (parsed.username || parsed.password)
+        throw new Error('quick origin must not contain credentials');
+    if (parsed.pathname !== '/' || parsed.search || parsed.hash)
+        throw new Error('quick origin must be an origin without path, query, or fragment');
+    return parsed;
+}
+function quickOriginTarget(origin, pathname, search) {
+    const target = new URL(origin);
+    // Assign components onto the already-approved origin. `new URL(pathname, origin)` is unsafe
+    // here because a path beginning `//host/` is a scheme-relative URL that replaces the host.
+    target.pathname = pathname || '/';
+    target.search = search;
+    target.hash = '';
+    return target;
+}
+function tokenFromRequest(request, url) {
+    const authorization = request.headers.get('authorization');
+    if (authorization?.startsWith('Bearer '))
+        return { token: authorization.slice(7), source: 'header' };
+    const query = url.searchParams.get('__volter_token');
+    if (query)
+        return { token: query, source: 'query' };
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === '__volter_auth')
+            return { token: rest.join('='), source: 'cookie' };
+    }
+    return {};
+}
+function forwardedPath(path, search) {
+    const url = new URL(`${path}${search}`, 'http://twin.local');
+    url.searchParams.delete('__volter_token');
+    url.searchParams.delete('__tunnel');
+    return url.pathname + (url.searchParams.size ? `?${url.searchParams}` : '');
+}
+function forwardedHeaders(request) {
+    const out = headersObject(request.headers);
+    const cookie = out.cookie?.split(';').filter((part) => part.trim().split('=')[0] !== '__volter_auth').join(';').trim();
+    if (cookie)
+        out.cookie = cookie;
+    else
+        delete out.cookie;
+    delete out['x-forwarded-for'];
+    out['x-forwarded-for'] = '0.0.0.0';
+    return out;
+}
+/**
+ * THE RELAY, host-neutral: a fetch that may answer an upgrade, and the socket handlers. The loopback
+ * server below runs it under `Bun.serve`; a hosted World runs it with `WebSocketPair`
+ * (createTunnelTwinFetch), since a Worker answers WebSocket upgrades as it answers HTTP.
+ */
+export function createTunnelTwinHandler(options = {}) {
+    // The relay's state is the World's it was created in. A socket's frames and the heartbeat run
+    // outside any request, so they re-enter that World's store themselves (a hosted World's store is
+    // scoped to the request that reached it).
+    const store = getActiveWorldStore();
+    const scoped = (fn) => withWorldStore(store, fn);
+    const controls = new Map();
+    /** Live bridged browser sockets, by the `connId` the owned protocol correlates on. */
+    const visitors = new Map();
+    const claimTokens = new Map();
+    const reservationTokens = new Map();
+    const registrationTurns = new Map();
+    const allocatedQuickIds = new Set();
+    const quickOrigins = new Map();
+    const pending = new Map();
+    const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
+    const requireTid = options.requireTid === true;
+    const serverId = randomUUID();
+    let baseUrl = '';
+    // THE HEARTBEAT — the relay writing its own liveness, which is the only thing that keeps its
+    // claim alive (relayClaimAlive). Throttled to the keepalive interval so a streamed response
+    // cannot take the claim lock once per chunk.
+    const lastHeartbeat = new Map();
+    const beatRelayClaim = (tunnelId) => {
+        if (!tunnelId)
+            return;
+        const token = claimTokens.get(tunnelId) ?? reservationTokens.get(tunnelId);
+        if (!token) {
+            lastHeartbeat.delete(tunnelId);
+            return;
+        }
+        const now = Date.parse(worldNow());
+        const previous = lastHeartbeat.get(tunnelId);
+        if (previous !== undefined && Number.isFinite(now) && Math.abs(now - previous) < RELAY_CLAIM_HEARTBEAT_MS)
+            return;
+        lastHeartbeat.set(tunnelId, now);
+        try {
+            refreshRelayClaim(options.root, tunnelId, token);
+        }
+        catch { /* a missed stamp only shortens this claim's freshness; the next frame or tick retries */ }
+    };
+    // The idle keepalive: a connected relay with no traffic must not look dead. Control frames beat
+    // the claim too (below), so the claim stays fresh wherever a long-lived timer does not run.
+    const claimHeartbeat = setInterval(() => scoped(() => {
+        for (const [tunnelId] of [...claimTokens, ...reservationTokens])
+            beatRelayClaim(tunnelId);
+    }), RELAY_CLAIM_HEARTBEAT_MS);
+    claimHeartbeat.unref?.();
+    const withRegistrationTurn = async (tunnelId, task) => {
+        const previous = registrationTurns.get(tunnelId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        registrationTurns.set(tunnelId, current);
+        await previous;
+        try {
+            return await task();
+        }
+        finally {
+            release();
+            if (registrationTurns.get(tunnelId) === current)
+                registrationTurns.delete(tunnelId);
+        }
+    };
+    const disconnectRegistration = (tunnelId, registrationId, occurredAt = worldNow()) => withRegistrationTurn(tunnelId, () => markTunnelDisconnected(tunnelId, options.root, occurredAt, registrationId));
+    const pendingId = (item) => [...pending].find(([, value]) => value === item)?.[0];
+    /**
+     * End a request that cannot complete: the visitor gets a stable JSON error and the client is
+     * told to stop producing.
+     *
+     * A status is ALWAYS available here, which is the whole point of buffering to `response-end`
+     * (see the `response-start` branch below): the head is never committed, so there is no state
+     * in which this has to fall back to truncating a response the visitor would read as complete.
+     */
+    const failPending = (item, status, error) => {
+        clearTimeout(item.timer);
+        const reqId = pendingId(item);
+        if (reqId) {
+            pending.delete(reqId);
+            // `request-abort` is the vendor's frame for "stop producing this one" and the client
+            // destroys its local request on it. It is sent from the ONE place a request ends badly —
+            // timeout, visitor hang-up, malformed frame, owner disconnect — so every such ending stops
+            // the client rather than leaving it producing into a request the relay has forgotten.
+            // Looking the id up BEFORE deleting is also what makes this idempotent: a second call for
+            // the same item finds no id and sends nothing.
+            try {
+                item.owner.send(JSON.stringify({ type: 'request-abort', reqId }));
+            }
+            catch { /* disconnected */ }
+        }
+        if (!item.resolved) {
+            item.resolved = true;
+            item.resolve(jsonError(status, error));
+        }
+    };
+    const failSocketPending = (owner, error) => {
+        for (const item of [...pending.values()])
+            if (item.owner === owner)
+                failPending(item, 502, error);
+    };
+    const armTimeout = (reqId, item) => {
+        clearTimeout(item.timer);
+        item.timer = setTimeout(() => {
+            if (pending.get(reqId) !== item)
+                return;
+            failPending(item, 504, 'Tunnel request timed out');
+        }, options.requestTimeoutMs ?? 15_000);
+    };
+    const relay = {
+        async fetch(request, bunServer) {
+            try {
+                const url = new URL(request.url);
+                // GET /twin — the discovery manifest (education inside the twin).
+                if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+                    return Response.json(statefulTwinManifest({ vendor: 'tunnel', twinOf: 'the Volter tunnel surfaces (Cloudflare quick tunnels + volter-tunnel)', stores: 'allocated tunnels and their public hostnames' }));
+                }
+                if (url.pathname === '/ws') {
+                    const upgraded = bunServer.upgrade(request, {
+                        data: {
+                            kind: 'control', socketId: randomUUID(), authoritativeId: url.searchParams.get('id') || undefined, session: {}, closed: false,
+                            // mounted under a World's path, the relay is reached there, not at its own origin
+                            publicBase: request.headers.get(TWIN_PREFIX_HEADER) ? twinPublicBase(request) : baseUrl,
+                        },
+                    });
+                    return upgraded ? undefined : jsonError(426, 'expected websocket');
+                }
+                if (url.pathname === '/__volter_auth') {
+                    const tunnelId = url.searchParams.get('__tunnel') ?? '';
+                    const token = url.searchParams.get('__volter_token') ?? '';
+                    if (!tunnelId || !token)
+                        return jsonError(400, 'Missing token or tunnel parameter');
+                    if (!controls.has(tunnelId))
+                        return jsonError(502, 'Tunnel not connected');
+                    if (!jwtSecret || !verifyJwt(token, jwtSecret, tunnelId, requireTid))
+                        return jsonError(401, 'Invalid token');
+                    return Response.json({ ok: true }, { headers: {
+                            'cache-control': 'no-store',
+                            'set-cookie': `__volter_auth=${token}; HttpOnly; SameSite=Lax; Path=/__twin/tunnels/${encodeURIComponent(tunnelId)}/; Max-Age=3600`,
+                        } });
+                }
+                const relay = /^\/__twin\/tunnels\/([^/]+)(\/.*)?$/.exec(url.pathname);
+                if (relay) {
+                    const tunnelId = decodeURIComponent(relay[1]);
+                    const socket = controls.get(tunnelId);
+                    if (!socket || !socket.data.session.registered || socket.data.session.superseded)
+                        return jsonError(502, 'Tunnel not connected');
+                    if (request.method === 'OPTIONS')
+                        return new Response(null, { status: 204, headers: corsHeaders(request) });
+                    const session = socket.data.session;
+                    if (session.basicAuth) {
+                        const authorization = request.headers.get('authorization') ?? '';
+                        const expected = `Basic ${Buffer.from(`${session.basicAuth.user}:${session.basicAuth.pass}`).toString('base64')}`;
+                        if (!constantEqual(authorization, expected)) {
+                            return Response.json({ error: 'Authentication required' }, {
+                                status: 401, headers: { ...corsHeaders(request), 'www-authenticate': 'Basic realm="volter-tunnel"' },
+                            });
+                        }
+                    }
+                    let setCookie;
+                    if (session.authRequired) {
+                        const auth = tokenFromRequest(request, url);
+                        if (!auth.token || !jwtSecret || !verifyJwt(auth.token, jwtSecret, tunnelId, requireTid)) {
+                            return Response.json({ error: 'Authentication required' }, { status: 401, headers: corsHeaders(request) });
+                        }
+                        if (auth.source === 'query') {
+                            setCookie = `__volter_auth=${auth.token}; HttpOnly; SameSite=Lax; Path=/__twin/tunnels/${encodeURIComponent(tunnelId)}/; Max-Age=3600`;
+                        }
+                    }
+                    // A browser WebSocket through the tunnel. It passes the SAME Basic/JWT gates above
+                    // before any bridge exists — an upgrade that skipped them would be an unauthenticated
+                    // hole beside an authenticated door. The `ws-upgrade` frame is sent from `open`, once
+                    // there is a real socket to bridge; the client answers `ws-ready` or `ws-error`.
+                    if ((request.headers.get('upgrade') ?? '').toLowerCase() === 'websocket') {
+                        const connId = randomUUID();
+                        // THE SUBPROTOCOL IS NOT ECHOED HERE, AND MUST NOT BE: `server.upgrade` already
+                        // answers with the browser's FIRST offer (measured — a bare upgrade of a
+                        // `Sec-WebSocket-Protocol: vite-hmr, graphql-ws` handshake returns
+                        // `Sec-WebSocket-Protocol: vite-hmr`). This lane added a redundant echo of its own
+                        // on the strength of a §9 finding that turned out to be wrong about the runtime,
+                        // and removed it again once measured; the OBSERVABLE contract is pinned instead, on
+                        // the raw 101 bytes, by `tunnel.volter.websocket.upgrade` — so the day the runtime
+                        // stops doing it, the verify says so rather than a duplicate silently covering.
+                        //
+                        // FIRST-OFFER-WINS IS NOT NEGOTIATION, and the protocol cannot make it one. The 101
+                        // goes out before `ws-ready` exists, so the relay commits to a subprotocol before
+                        // the client has dialled the local server — which may pick a DIFFERENT one from the
+                        // full list the `ws-upgrade` frame forwards. None of the vendor's fifteen
+                        // discriminators can carry that choice back (`ws-ready` carries only `connId`), so a
+                        // multi-offer mismatch is a structural gap, not an unfinished one:
+                        // `tunnel.volter.websocket.subprotocol_negotiation`.
+                        const upgradeHeaders = {
+                            // A query-token upgrade gets the same cookie the HTTP path hands back, so the
+                            // page's SUBSEQUENT requests are authenticated without re-carrying the token.
+                            // This one IS the relay's, and is pinned on the raw 101 by the auth-gate verify.
+                            ...(setCookie ? { 'set-cookie': setCookie } : {}),
+                        };
+                        const upgraded = bunServer.upgrade(request, {
+                            ...(Object.keys(upgradeHeaders).length > 0 ? { headers: upgradeHeaders } : {}),
+                            data: {
+                                kind: 'visitor', socketId: randomUUID(), session: {}, closed: false,
+                                visitor: {
+                                    connId, tunnelId, owner: socket,
+                                    path: forwardedPath(relay[2] || '/', url.search),
+                                    headers: forwardedHeaders(request),
+                                    ready: false, queue: [], queuedBytes: 0, closeRelayed: false,
+                                },
+                            },
+                        });
+                        return upgraded ? undefined : jsonError(426, 'expected websocket');
+                    }
+                    const reqId = randomUUID();
+                    const path = forwardedPath(relay[2] || '/', url.search);
+                    const body = request.method === 'GET' || request.method === 'HEAD' ? null : Buffer.from(await request.arrayBuffer()).toString('base64');
+                    const response = new Promise((resolve) => {
+                        const item = {
+                            resolve, timer: setTimeout(() => { }, 0), owner: socket, tunnelId, path, request,
+                            ...(setCookie ? { setCookie } : {}), resolved: false,
+                        };
+                        pending.set(reqId, item);
+                        armTimeout(reqId, item);
+                        // The visitor hung up. `failPending` sends the `request-abort` (one place, so the
+                        // frame cannot be sent twice or forgotten on one of the four ending paths).
+                        request.signal.addEventListener('abort', () => {
+                            if (pending.get(reqId) !== item)
+                                return;
+                            failPending(item, 499, 'Visitor disconnected');
+                        }, { once: true });
+                    });
+                    try {
+                        socket.send(JSON.stringify({ type: 'request', reqId, method: request.method, path, headers: forwardedHeaders(request), body }));
+                    }
+                    catch {
+                        const item = pending.get(reqId);
+                        if (item)
+                            failPending(item, 502, 'Tunnel send failed');
+                    }
+                    return response;
+                }
+                const quick = /^\/__twin\/quick\/([^/]+)(\/.*)?$/.exec(url.pathname);
+                if (quick) {
+                    const id = decodeURIComponent(quick[1]);
+                    const origin = quickOrigins.get(id);
+                    if (!origin)
+                        return jsonError(502, 'Quick tunnel not connected');
+                    const target = quickOriginTarget(origin, quick[2] || '/', url.search);
+                    const init = { method: request.method, headers: request.headers, redirect: 'manual' };
+                    if (request.method !== 'GET' && request.method !== 'HEAD')
+                        init.body = await request.arrayBuffer();
+                    try {
+                        return await fetch(target, init);
+                    }
+                    catch {
+                        return jsonError(502, 'Quick tunnel origin unavailable');
+                    }
+                }
+                if (quickOrigins.size === 1 && !tunnelControlPathIsReserved(url.pathname)) {
+                    const origin = quickOrigins.values().next().value;
+                    const target = quickOriginTarget(origin, url.pathname, url.search);
+                    const init = { method: request.method, headers: request.headers, redirect: 'manual' };
+                    if (request.method !== 'GET' && request.method !== 'HEAD')
+                        init.body = await request.arrayBuffer();
+                    try {
+                        return await fetch(target, init);
+                    }
+                    catch {
+                        return jsonError(502, 'Quick tunnel origin unavailable');
+                    }
+                }
+                const body = request.method === 'GET' || request.method === 'HEAD' ? '' : await request.text();
+                const out = await handleTunnelTwinRequest({
+                    method: request.method, path: url.pathname + url.search, body, headers: headersObject(request.headers),
+                    root: options.root, readOnly: options.readOnly, occurredAt: worldNow(), liveTunnels: controls.size,
+                });
+                if (request.method === 'POST' && url.pathname === '/tunnel' && out.status === 200) {
+                    const id = out.body.result?.id;
+                    if (typeof id === 'string')
+                        allocatedQuickIds.add(id);
+                }
+                return new Response(out.body === null ? null : JSON.stringify(out.body), { status: out.status, headers: out.headers });
+            }
+            catch {
+                return jsonError(500, 'Tunnel twin request failed');
+            }
+        },
+        websocket: {
+            open(ws) {
+                if (ws.data.kind !== 'visitor')
+                    return;
+                const visitor = ws.data.visitor;
+                // THE OWNER MUST STILL BE THERE. Bun runs `open` AFTER the fetch handler returns, so a
+                // control socket that died in that window has already run its own sweep — and this
+                // visitor was not in `visitors` yet for the sweep to find. §9 found the orphan that
+                // leaves: registered against a dead owner, in the map, reachable by no cleanup.
+                // `ServerWebSocket.send` RETURNS 0 on a closed socket rather than throwing, so the
+                // try/catch this used to rely on was dead code and could never have caught it.
+                if (!ownerAlive(visitor)) {
+                    ws.close(1011, 'Tunnel disconnected');
+                    return;
+                }
+                visitors.set(visitor.connId, ws);
+                // `ws-upgrade` is the relay→client frame the vendor defines for exactly this: connId,
+                // the tunnelled path, and the browser's headers (the client re-stamps host/origin and
+                // strips the hop-by-hop handshake headers itself before dialling the local server).
+                visitor.owner.send(JSON.stringify({ type: 'ws-upgrade', connId: visitor.connId, path: visitor.path, headers: visitor.headers }));
+            },
+            async message(ws, raw) {
+                // A VISITOR frame is payload, not protocol: it is relayed verbatim and never parsed as a
+                // control message. Branching first is what keeps a browser from reaching the registration
+                // reducer by sending `{"type":"register"}` over its bridged socket.
+                if (ws.data.kind === 'visitor') {
+                    const visitor = ws.data.visitor;
+                    const binary = typeof raw !== 'string';
+                    const bytes = typeof raw === 'string' ? Buffer.from(raw, 'utf8') : Buffer.from(raw);
+                    if (!visitor.ready) {
+                        // Frames a browser sends between its own upgrade and the client's `ws-ready` are real
+                        // application data (a client library often speaks first). Queue them, bounded — the
+                        // alternative is dropping the first message of every connection.
+                        visitor.queuedBytes += bytes.byteLength;
+                        if (visitor.queuedBytes > VISITOR_PREREADY_LIMIT_BYTES) {
+                            visitors.delete(visitor.connId);
+                            ws.close(1011, 'Tunnel bridge not ready');
+                            return;
+                        }
+                        visitor.queue.push({ data: new Uint8Array(bytes), binary });
+                        return;
+                    }
+                    // A frame with nowhere to go must CLOSE the browser, not vanish into a dead owner —
+                    // silently black-holing it is the shape the pre-ready queue exists to prevent, one
+                    // step later. Checked, not caught: `send` does not throw.
+                    if (!ownerAlive(visitor)) {
+                        visitors.delete(visitor.connId);
+                        ws.close(1011, 'Tunnel disconnected');
+                        return;
+                    }
+                    visitor.owner.send(JSON.stringify({ type: 'ws-message', connId: visitor.connId, data: bytes.toString('base64'), binary }));
+                    return;
+                }
+                let message;
+                try {
+                    message = JSON.parse(typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf8'));
+                }
+                catch {
+                    ws.send(JSON.stringify({ type: 'error', fatal: true, message: 'invalid JSON' }));
+                    return;
+                }
+                // A frame from this relay IS the evidence it is alive — record it as state before doing
+                // anything with the frame. (A `register` frame has no claim yet; it stamps its own at
+                // reservation.)
+                beatRelayClaim(ws.data.session.tunnelId);
+                try {
+                    if (message.type === 'register') {
+                        const prepared = prepareTunnelRelayRegistration({
+                            message, session: ws.data.session, authoritativeId: ws.data.authoritativeId,
+                            publicBaseUrl: ws.data.publicBase ?? baseUrl, readOnly: options.readOnly,
+                        });
+                        // Authentication and the complete frame schema are checked before we inspect, close,
+                        // or transfer any live owner. A rejected replace:true frame is therefore inert.
+                        if (!('persistence' in prepared)) {
+                            if (prepared.outbound)
+                                ws.send(JSON.stringify(prepared.outbound));
+                            return;
+                        }
+                        const candidate = prepared;
+                        const requested = candidate.registration.tunnelId;
+                        await withRegistrationTurn(requested, async () => {
+                            // Re-check only after entering the per-id turn. A contender that arrived while the
+                            // winner awaited persistence must be refused BEFORE any action append.
+                            const existing = controls.get(requested);
+                            if (existing && existing !== ws && message.replace !== true) {
+                                ws.send(JSON.stringify({ type: 'error', message: `Tunnel ID '${requested}' is already in use by another client. Pass { replace: true } to take over.` }));
+                                ws.close(4002, 'Tunnel ID already in use');
+                                return;
+                            }
+                            if (existing === ws && ws.data.session.registered && !ws.data.session.superseded) {
+                                if (candidate.outbound)
+                                    ws.send(JSON.stringify(candidate.outbound));
+                                return;
+                            }
+                            const claimToken = randomUUID();
+                            const reservation = reserveRelayClaim({
+                                root: options.root,
+                                tunnelId: requested,
+                                token: claimToken,
+                                serverId,
+                                socketId: ws.data.socketId,
+                                replace: message.replace === true,
+                            });
+                            if (!reservation.ok) {
+                                ws.send(JSON.stringify({ type: 'error', message: `Tunnel ID '${requested}' is already in use by another client. Pass { replace: true } to take over.` }));
+                                ws.close(4002, 'Tunnel ID already in use');
+                                return;
+                            }
+                            reservationTokens.set(requested, claimToken);
+                            try {
+                                // The transient claim is already exclusive across both sockets and processes.
+                                // Only its winner may append relay.register; a storage failure restores the prior
+                                // claim and leaves every live mapping/session untouched.
+                                await (options.persistRegistration ?? persistTunnelRelayRegistration)(candidate, {
+                                    root: options.root,
+                                    occurredAt: worldNow(),
+                                    registrationId: claimToken,
+                                });
+                                if (ws.data.closed) {
+                                    reservationTokens.delete(requested);
+                                    // The socket vanished after its action append but before it could own traffic.
+                                    // Suppress that exact generation before restoring the previous claim; otherwise
+                                    // its registration_id would hide the prior owner's later conditional disconnect.
+                                    revertTunnelRelayRegistration(requested, claimToken, {
+                                        root: options.root,
+                                        occurredAt: worldNow(),
+                                    });
+                                    restoreRelayClaim(options.root, requested, claimToken, reservation.previous);
+                                    if (!controls.has(requested)) {
+                                        if (reservation.previous) {
+                                            await markTunnelDisconnected(requested, options.root, worldNow(), reservation.previous.token);
+                                        }
+                                    }
+                                    return;
+                                }
+                                activateRelayClaim(options.root, requested, claimToken);
+                                reservationTokens.delete(requested);
+                            }
+                            catch (error) {
+                                reservationTokens.delete(requested);
+                                let revertError;
+                                try {
+                                    revertTunnelRelayRegistration(requested, claimToken, {
+                                        root: options.root,
+                                        occurredAt: worldNow(),
+                                    });
+                                }
+                                catch (candidate) {
+                                    revertError = candidate;
+                                }
+                                restoreRelayClaim(options.root, requested, claimToken, reservation.previous);
+                                if (revertError) {
+                                    throw new Error(`Registration persistence failed and its durable action could not be reverted: ${revertError instanceof Error ? revertError.message : String(revertError)}`, { cause: error });
+                                }
+                                throw error;
+                            }
+                            const previous = controls.get(requested);
+                            const oldAliases = [...controls.entries()]
+                                .filter(([id, owner]) => owner === ws && id !== requested)
+                                .map(([id]) => id);
+                            ws.data.session = candidate.session;
+                            controls.set(requested, ws);
+                            claimTokens.set(requested, claimToken);
+                            if (oldAliases.length > 0) {
+                                failSocketPending(ws, 'Tunnel identity changed');
+                                for (const id of oldAliases) {
+                                    const oldToken = claimTokens.get(id);
+                                    controls.delete(id);
+                                    claimTokens.delete(id);
+                                    if (oldToken)
+                                        void disconnectRegistration(id, oldToken).catch(() => { });
+                                    if (oldToken)
+                                        releaseRelayClaim(options.root, id, oldToken);
+                                }
+                            }
+                            if (previous && previous !== ws) {
+                                previous.data.session.registered = false;
+                                previous.data.session.superseded = true;
+                                failSocketPending(previous, 'Tunnel replaced');
+                                previous.close(4001, 'Replaced by new client');
+                            }
+                            if (candidate.outbound)
+                                ws.send(JSON.stringify(candidate.outbound));
+                        });
+                        return;
+                    }
+                    if (!ws.data.session.registered || ws.data.session.superseded) {
+                        ws.send(JSON.stringify({ type: 'error', fatal: true, message: 'control socket is not the registered tunnel owner' }));
+                        return;
+                    }
+                    // ── the WebSocket half of the protocol, correlated on connId ──────────────────
+                    //
+                    // The DECISION is `reduceTunnelWsFrame`'s, in tunnel-twin.ts — a mutation seam, so the
+                    // bridge's verifies are killed at the frame and not merely at registration (§9). This
+                    // adapter supplies the one thing the reducer cannot know (who owns the connId) and
+                    // then APPLIES the decision to real sockets.
+                    if (message.type === 'ws-ready' || message.type === 'ws-error' || message.type === 'ws-message' || message.type === 'ws-close') {
+                        const rawConnId = message.connId;
+                        const connId = typeof rawConnId === 'string' ? rawConnId : '';
+                        const visitorSocket = connId ? visitors.get(connId) : undefined;
+                        const visitor = visitorSocket?.data.visitor;
+                        const ownership = !visitorSocket || !visitor ? 'unknown' : visitor.owner === ws ? 'self' : 'other';
+                        const decision = reduceTunnelWsFrame({ message, ownership });
+                        if (decision.kind === 'ignore')
+                            return;
+                        if (decision.kind === 'error') {
+                            ws.send(JSON.stringify({ type: 'error', message: decision.message }));
+                            return;
+                        }
+                        // Past `ignore`, ownership was 'self', so both are present.
+                        if (!visitorSocket || !visitor)
+                            return;
+                        if (decision.kind === 'ready') {
+                            visitor.ready = true;
+                            // Everything the browser said while the local socket was still dialling, in order.
+                            // `ws` is the socket this very frame arrived on, so it is open by construction —
+                            // the `catch { break }` that used to guard this loop was unreachable and would
+                            // have dropped the remaining frames silently if it ever had run.
+                            for (const frame of visitor.queue.splice(0)) {
+                                ws.send(JSON.stringify({ type: 'ws-message', connId, data: Buffer.from(frame.data).toString('base64'), binary: frame.binary }));
+                            }
+                            visitor.queuedBytes = 0;
+                            return;
+                        }
+                        if (decision.kind === 'deliver') {
+                            // `binary` decides the frame type on the wire, so a text protocol stays text.
+                            visitorSocket.send(decision.binary ? decision.data : Buffer.from(decision.data).toString('utf8'));
+                            return;
+                        }
+                        // `close` — ws-error and ws-close both END the bridge, already accounted for on the
+                        // client's side, so the visitor's own close handler must not echo one back.
+                        visitor.closeRelayed = true;
+                        visitors.delete(connId);
+                        visitorSocket.close(decision.code, decision.reason);
+                        return;
+                    }
+                    if (!('reqId' in message))
+                        return;
+                    const reqId = String(message.reqId);
+                    const item = pending.get(reqId);
+                    if (!item || item.owner !== ws || controls.get(item.tunnelId) !== ws) {
+                        ws.send(JSON.stringify({ type: 'error', message: 'response correlation is not owned by this control socket' }));
+                        return;
+                    }
+                    if (message.type === 'response') {
+                        if (item.stream || item.resolved) {
+                            failPending(item, 502, 'Complete response arrived after response start');
+                            ws.send(JSON.stringify({ type: 'error', message: 'complete response arrived after response start' }));
+                            return;
+                        }
+                        const body = decodeBase64(message.body);
+                        if (!validResponseStatus(message.status) || !validResponseHeaders(message.headers) || body === undefined) {
+                            failPending(item, 502, 'Malformed tunnel response frame');
+                            ws.send(JSON.stringify({ type: 'error', message: 'malformed response frame' }));
+                            return;
+                        }
+                        let response;
+                        const bodyInit = body.byteLength === 0 && [204, 205, 304].includes(message.status) ? null : new Uint8Array(body);
+                        try {
+                            response = new Response(bodyInit, { status: message.status, headers: responseHeaders(message.headers, item.request, item.path, item.setCookie) });
+                        }
+                        catch {
+                            failPending(item, 502, 'Malformed tunnel response frame');
+                            return;
+                        }
+                        clearTimeout(item.timer);
+                        pending.delete(reqId);
+                        item.resolved = true;
+                        item.resolve(response);
+                    }
+                    else if (message.type === 'response-start') {
+                        if (item.stream || item.resolved) {
+                            failPending(item, 502, 'Duplicate response start frame');
+                            ws.send(JSON.stringify({ type: 'error', message: 'duplicate response-start frame' }));
+                            return;
+                        }
+                        if (!validResponseStatus(message.status) || !validResponseHeaders(message.headers)) {
+                            failPending(item, 502, 'Malformed tunnel response frame');
+                            ws.send(JSON.stringify({ type: 'error', message: 'malformed response-start frame' }));
+                            return;
+                        }
+                        // THE HEAD STAYS UNCOMMITTED UNTIL `response-end`, and that is a MEASURED trade, not
+                        // an unfinished one. Through `Bun.serve`'s Response surface a body that has begun
+                        // cannot be failed: erroring the `ReadableStream` behind it terminates the chunked
+                        // body CLEANLY, so the visitor reads a truncated payload as a successful 200 and
+                        // cannot tell it from a complete one — a fake success. It also drops a
+                        // `content-length` the moment the body is a stream, removing the one framing a
+                        // client could have detected the truncation from.
+                        //
+                        // §9 was right to refuse the broader form of that sentence: `node:http` CAN signal a
+                        // mid-body failure, on this same runtime, in this same process — so the honest
+                        // statement is that THIS HTTP HOST cannot, and that re-hosting the plane on
+                        // `node:http` to gain incremental delivery would mean giving up `server.upgrade`,
+                        // which is what the entire WebSocket bridge above is built on. All three facts are
+                        // measured by `tunnel-stream-boundary.test.ts`; the day the first two flip,
+                        // `tunnel.volter.http.streaming` and its two siblings become buildable here.
+                        // Buffering costs latency on a large response; committing the head would cost the
+                        // ability to fail one honestly, and this pack trades the first for the second.
+                        item.stream = { status: message.status, headers: message.headers, chunks: [] };
+                        armTimeout(reqId, item);
+                    }
+                    else if (message.type === 'response-chunk') {
+                        if (!item.stream) {
+                            failPending(item, 502, 'response chunk arrived before response start');
+                            ws.send(JSON.stringify({ type: 'error', message: 'response chunk arrived before response start' }));
+                            return;
+                        }
+                        const data = decodeBase64(message.data);
+                        if (data === undefined) {
+                            failPending(item, 502, 'Malformed tunnel response chunk');
+                            ws.send(JSON.stringify({ type: 'error', message: 'malformed response-chunk frame' }));
+                            return;
+                        }
+                        item.stream.chunks.push(data);
+                        armTimeout(reqId, item);
+                    }
+                    else if (message.type === 'response-end') {
+                        if (!item.stream) {
+                            failPending(item, 502, 'response end arrived before response start');
+                            ws.send(JSON.stringify({ type: 'error', message: 'response end arrived before response start' }));
+                            return;
+                        }
+                        const bytes = Buffer.concat(item.stream.chunks.map((chunk) => Buffer.from(chunk)));
+                        const bodyInit = bytes.byteLength === 0 && [204, 205, 304].includes(item.stream.status) ? null : new Uint8Array(bytes);
+                        let response;
+                        try {
+                            response = new Response(bodyInit, {
+                                status: item.stream.status,
+                                headers: responseHeaders(item.stream.headers, item.request, item.path, item.setCookie),
+                            });
+                        }
+                        catch {
+                            failPending(item, 502, 'Malformed tunnel response frame');
+                            return;
+                        }
+                        clearTimeout(item.timer);
+                        pending.delete(reqId);
+                        item.resolved = true;
+                        item.resolve(response);
+                    }
+                }
+                catch {
+                    try {
+                        ws.send(JSON.stringify({ type: 'error', fatal: true, message: 'tunnel control frame failed' }));
+                    }
+                    catch { /* disconnected */ }
+                }
+            },
+            close(ws, code, reason) {
+                if (ws.data.kind === 'visitor') {
+                    const visitor = ws.data.visitor;
+                    visitors.delete(visitor.connId);
+                    // The browser hung up: tell the client so it closes its LOCAL socket too. Skipped when
+                    // the close came FROM the client (`closeRelayed`), which would otherwise loop a close
+                    // back at the side that sent it.
+                    if (!visitor.closeRelayed && ownerAlive(visitor)) {
+                        const safe = code >= 1000 && code <= 4999 && code !== 1005 && code !== 1006 ? code : 1000;
+                        visitor.owner.send(JSON.stringify({ type: 'ws-close', connId: visitor.connId, code: safe, reason: reason ?? '' }));
+                    }
+                    return;
+                }
+                ws.data.closed = true;
+                failSocketPending(ws, 'Tunnel disconnected');
+                // Every bridge this control socket owned dies with it — a visitor left open would be
+                // talking to nothing.
+                for (const [connId, visitorSocket] of [...visitors]) {
+                    if (visitorSocket.data.visitor?.owner !== ws)
+                        continue;
+                    visitorSocket.data.visitor.closeRelayed = true;
+                    visitors.delete(connId);
+                    try {
+                        visitorSocket.close(1011, 'Tunnel disconnected');
+                    }
+                    catch { /* already gone */ }
+                }
+                const ownedIds = [...controls.entries()].filter(([, owner]) => owner === ws).map(([id]) => id);
+                for (const tunnelId of ownedIds) {
+                    const claimToken = claimTokens.get(tunnelId);
+                    controls.delete(tunnelId);
+                    claimTokens.delete(tunnelId);
+                    if (claimToken)
+                        void disconnectRegistration(tunnelId, claimToken).catch(() => { });
+                    if (claimToken)
+                        releaseRelayClaim(options.root, tunnelId, claimToken);
+                }
+            },
+        },
+    };
+    return {
+        fetch: relay.fetch,
+        websocket: {
+            open: (ws) => scoped(() => relay.websocket.open(ws)),
+            message: (ws, raw) => scoped(() => relay.websocket.message(ws, raw)),
+            close: (ws, code, reason) => scoped(() => relay.websocket.close(ws, code, reason)),
+        },
+        /** Where the relay is reached when a request does not say (the loopback server's own origin). */
+        setBaseUrl(url) { baseUrl = url; },
+        get url() { return baseUrl; },
+        registerQuickOrigin(id, origin) {
+            if (!allocatedQuickIds.has(id))
+                throw new Error(`unknown quick tunnel allocation: ${id}`);
+            const parsed = parseTunnelLoopbackOrigin(origin);
+            quickOrigins.set(id, parsed.toString());
+        },
+        quickUrl(id) { return `${baseUrl}/__twin/quick/${encodeURIComponent(id)}`; },
+        authUrl(tunnelId, token) {
+            return `${baseUrl}/__volter_auth?__tunnel=${encodeURIComponent(tunnelId)}&__volter_token=${encodeURIComponent(token)}`;
+        },
+        mintToken(tunnelId, payload = {}) {
+            if (!jwtSecret)
+                throw new Error('tunnel JWT auth is disabled');
+            return createTunnelTwinJwt({ sub: 'twin-local', tid: tunnelId, exp: Math.floor(Date.now() / 1000) + 3600, ...payload }, jwtSecret);
+        },
+        stop() {
+            clearInterval(claimHeartbeat);
+            for (const socket of new Set(controls.values()))
+                failSocketPending(socket, 'Tunnel server stopped');
+            for (const [tunnelId, token] of claimTokens) {
+                void disconnectRegistration(tunnelId, token).catch(() => { });
+                releaseRelayClaim(options.root, tunnelId, token);
+            }
+            claimTokens.clear();
+            for (const [tunnelId, token] of reservationTokens)
+                releaseRelayClaim(options.root, tunnelId, token);
+            reservationTokens.clear();
+            controls.clear();
+        },
+    };
+}
+/** The relay on loopback, under `Bun.serve`. */
+export function createTunnelTwinServer(options = {}) {
+    const handler = createTunnelTwinHandler(options);
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: (request, bunServer) => handler.fetch(request, bunServer),
+        websocket: {
+            open: (ws) => handler.websocket.open(ws),
+            message: (ws, raw) => handler.websocket.message(ws, raw),
+            close: (ws, code, reason) => handler.websocket.close(ws, code, reason),
+        },
+    });
+    handler.setBaseUrl(`http://127.0.0.1:${server.port}`);
+    return {
+        port: server.port,
+        url: handler.url,
+        registerQuickOrigin: handler.registerQuickOrigin,
+        quickUrl: handler.quickUrl,
+        authUrl: handler.authUrl,
+        mintToken: handler.mintToken,
+        stop() {
+            handler.stop();
+            server.stop(true);
+        },
+    };
+}
+/**
+ * The relay as a hosted World's twin wire: the same handler, its upgrades answered with a
+ * `WebSocketPair` (a Worker takes a WebSocket as it takes HTTP). Frames are handed to the handler in
+ * arrival order, as `Bun.serve` hands them.
+ */
+export function createTunnelTwinFetch(options = {}) {
+    const handler = createTunnelTwinHandler(options);
+    return async (request) => {
+        let upgraded;
+        const answer = await handler.fetch(request, {
+            upgrade(_request, init) {
+                const Pair = globalThis.WebSocketPair;
+                if (!Pair)
+                    return false;
+                const pair = new Pair();
+                const end = pair[1];
+                end.accept();
+                const socket = {
+                    data: init.data,
+                    send: (message) => end.send(message),
+                    close: (code, reason) => end.close(code, reason),
+                    get readyState() { return end.readyState; },
+                };
+                // One queue in arrival order, `open` first (Bun opens after the 101 is answered); a link that
+                // throws does not stop the ones after it, and `close` runs once (an `error` is followed by one).
+                let order = new Promise((resolve) => setTimeout(resolve, 0)).then(() => handler.websocket.open(socket));
+                const next = (step) => { order = order.catch(() => undefined).then(step); order.catch(() => undefined); };
+                let closed = false;
+                const closeOnce = (code, reason) => { if (closed)
+                    return; closed = true; next(() => handler.websocket.close(socket, code, reason)); };
+                end.addEventListener('message', (event) => {
+                    const data = event.data;
+                    next(async () => {
+                        const raw = typeof data === 'string' ? data : data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(await data.arrayBuffer());
+                        void handler.websocket.message(socket, raw);
+                    });
+                });
+                end.addEventListener('close', (event) => closeOnce(event.code, event.reason));
+                end.addEventListener('error', () => closeOnce(1006, ''));
+                upgraded = new Response(null, { status: 101, webSocket: pair[0], ...(init.headers ? { headers: init.headers } : {}) });
+                return true;
+            },
+        });
+        return answer ?? upgraded ?? jsonError(426, 'expected websocket');
+    };
+}