@volter/twin-tunnel 0.1.0

package/dist/src/tunnel-twin.d.ts

@@ -0,0 +1,175 @@
+/** Message discriminators implemented or deliberately inventoried by the owned relay protocol.
+ * The capability manifest checks against this runtime-owned list; a test separately pins it to
+ * the installed first-party tunnel-core SDK without pulling that dev-only SDK into runtime code. */
+export declare const TUNNEL_PROTOCOL_MESSAGE_TYPES: readonly ["register", "response", "response-start", "response-chunk", "response-end", "ws-ready", "ws-error", "ws-message", "ws-close", "registered", "request", "request-abort", "ws-upgrade", "quota", "error"];
+export type TunnelRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string | undefined>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    liveTunnels?: number;
+};
+export type TunnelResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** Cloudflare's quick-tunnel allocation control API plus the owned relay health surface.
+ * The quick response follows cloudflared's first-party `QuickTunnelResponse` structure. */
+export declare function handleTunnelTwinRequest(req: TunnelRequest): Promise<TunnelResponse>;
+export type RegisterMessage = {
+    type: 'register';
+    tunnelId?: string;
+    secret?: string;
+    replace?: boolean;
+    authRequired?: boolean;
+    basicAuth?: {
+        user: string;
+        pass: string;
+    };
+};
+export type RelayControlMessage = RegisterMessage | {
+    type: 'response';
+    reqId: string | number;
+    status: number;
+    headers: Record<string, string | string[]>;
+    body: string;
+} | {
+    type: 'response-start';
+    reqId: string | number;
+    status: number;
+    headers: Record<string, string | string[]>;
+} | {
+    type: 'response-chunk';
+    reqId: string | number;
+    data: string;
+} | {
+    type: 'response-end';
+    reqId: string | number;
+} | {
+    type: 'ws-ready' | 'ws-error' | 'ws-message' | 'ws-close';
+    [key: string]: unknown;
+};
+export type RelaySession = {
+    tunnelId?: string;
+    authRequired?: boolean;
+    basicAuth?: {
+        user: string;
+        pass: string;
+    };
+    registered?: boolean;
+    superseded?: boolean;
+};
+export type RelayReduction = {
+    session: RelaySession;
+    outbound?: Record<string, unknown>;
+    registration?: {
+        tunnelId: string;
+        authRequired: boolean;
+    };
+};
+export type PreparedRelayRegistration = RelayReduction & {
+    registration: {
+        tunnelId: string;
+        authRequired: boolean;
+    };
+    persistence: {
+        tunnelId: string;
+        fields: Record<string, unknown>;
+    };
+};
+/** Validate and normalize a registration without changing persisted or live ownership. The
+ * socket adapter uses this seam before it makes an existing owner inert, so a malformed takeover
+ * can never evict a healthy tunnel. */
+export declare function prepareTunnelRelayRegistration(input: {
+    message: unknown;
+    session: RelaySession;
+    authoritativeId?: string;
+    publicBaseUrl: string;
+    readOnly?: boolean;
+}): RelayReduction | PreparedRelayRegistration;
+export declare function persistTunnelRelayRegistration(prepared: PreparedRelayRegistration, options?: {
+    root?: string;
+    occurredAt?: string;
+    registrationId?: string;
+}): Promise<void>;
+/** Undo exactly the registration action identified by the durable registration id. Persistence can
+ * append successfully and still reject afterward (for example while projecting the result). A
+ * kernel revert preserves that attempted write in the audit log while suppressing its projection,
+ * restoring either the prior live owner or the prior absence byte-for-byte. */
+export declare function revertTunnelRelayRegistration(tunnelId: string, registrationId: string, options?: {
+    root?: string;
+    occurredAt?: string;
+}): boolean;
+/** Reducer behind the WebSocket adapter. It is deliberately in a separate module so the
+ * mutation gate can replace it while the real socket/data-path adapter remains intact. */
+export declare function handleTunnelRelayMessage(input: {
+    message: unknown;
+    session: RelaySession;
+    authoritativeId?: string;
+    publicBaseUrl: string;
+    root?: string;
+    occurredAt?: string;
+    readOnly?: boolean;
+}): Promise<RelayReduction>;
+/**
+ * What the relay should DO with one connId-correlated WebSocket frame.
+ *
+ * `ws-ready` / `ws-message` / `ws-error` / `ws-close` are the four frames that address a bridged
+ * browser socket rather than an HTTP request, and the decision they lead to is PURE: it depends
+ * only on the frame and on who owns that connId. Keeping it here rather than inline in the socket
+ * adapter is the same split `handleTunnelRelayMessage` already uses, and for the same reason —
+ * the mutation gate can replace this seam while the real socket/data path stays intact, so the
+ * bridge's verifies are killed at the FRAME. §9 found they were only ever killed at REGISTRATION
+ * (every one of them traverses `prepareTunnelRelayRegistration` through `openControl`), which
+ * meant the bridge itself was reported as covered while nothing sabotaged it.
+ */
+export type TunnelWsOwnership = 'self' | 'other' | 'unknown';
+export type TunnelWsDecision = 
+/** Not a connId frame, or one whose bridge is already gone. Do nothing. */
+{
+    kind: 'ignore';
+}
+/** Answer the control socket with a protocol error. */
+ | {
+    kind: 'error';
+    message: string;
+}
+/** The bridge is up: flush anything the browser said while it was coming up. */
+ | {
+    kind: 'ready';
+    connId: string;
+}
+/** Send payload to the browser. */
+ | {
+    kind: 'deliver';
+    connId: string;
+    data: Uint8Array;
+    binary: boolean;
+}
+/** End the browser socket with this code and reason. */
+ | {
+    kind: 'close';
+    connId: string;
+    code: number;
+    reason: string;
+};
+/** Close codes 1005 ("no status") and 1006 ("abnormal") may never appear ON THE WIRE, and
+ *  anything outside 1000-4999 is not a close code at all — the vendor's client clamps the
+ *  identical way on the frames it receives. */
+export declare function clampTunnelCloseCode(raw: unknown): number;
+/** A close `reason` may carry at most 123 bytes. */
+export declare function clampTunnelCloseReason(raw: unknown): string;
+export declare function reduceTunnelWsFrame(input: {
+    message: unknown;
+    ownership: TunnelWsOwnership;
+}): TunnelWsDecision;
+/** Persist a disconnect only for the registration generation that actually lost its socket.
+ * Replacement appends its new generation before transferring the live controls map, so a close
+ * from the prior socket can arrive in that interval. The server serializes this conditional write
+ * behind the registration turn; the identity check then prevents the stale close from overwriting
+ * the successor's durable connected state. */
+export declare function markTunnelDisconnected(tunnelId: string, root?: string, occurredAt?: string, expectedRegistrationId?: string): Promise<boolean>;

package/dist/src/tunnel-twin.js

@@ -0,0 +1,236 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { appendAction, applyTwinWrite, listActions, projectResources, TwinActionPreconditionError } from '@volter/world-core';
+const SERVICE = 'tunnel';
+/** Message discriminators implemented or deliberately inventoried by the owned relay protocol.
+ * The capability manifest checks against this runtime-owned list; a test separately pins it to
+ * the installed first-party tunnel-core SDK without pulling that dev-only SDK into runtime code. */
+export const TUNNEL_PROTOCOL_MESSAGE_TYPES = [
+    'register', 'response', 'response-start', 'response-chunk', 'response-end',
+    'ws-ready', 'ws-error', 'ws-message', 'ws-close', 'registered', 'request',
+    'request-abort', 'ws-upgrade', 'quota', 'error',
+];
+function nextRev(id, root) {
+    let max = 0;
+    for (const action of listActions(SERVICE, root)) {
+        if (action.subject?.id !== id)
+            continue;
+        const rev = action.fields?.rev;
+        if (typeof rev === 'number')
+            max = Math.max(max, rev);
+    }
+    return max + 1;
+}
+async function writeTunnel(type, id, fields, operation, req, preconditions) {
+    const occurredAt = req.occurredAt ?? new Date().toISOString();
+    await applyTwinWrite(SERVICE, {
+        operation,
+        subjectType: type,
+        subjectId: id,
+        fields: { ...fields, rev: nextRev(id, req.root), writtenAt: occurredAt },
+        occurredAt,
+        actor: { kind: 'agent', id: 'tunnel-twin' },
+        preconditions,
+    }, req.root);
+}
+/** Cloudflare's quick-tunnel allocation control API plus the owned relay health surface.
+ * The quick response follows cloudflared's first-party `QuickTunnelResponse` structure. */
+export async function handleTunnelTwinRequest(req) {
+    const url = new URL(req.path, 'http://twin.local');
+    if (req.method === 'POST' && url.pathname === '/tunnel') {
+        if (req.readOnly)
+            return {
+                status: 405,
+                body: { success: false, errors: [{ message: 'tunnel twin is read-only' }] },
+                headers: { 'content-type': 'application/json' },
+            };
+        // The allocation's identity is state (R9): id, name, hostname and account tag derive from
+        // the world instant and the quick tunnels already allocated, in cloudflared's shapes. The
+        // tunnel secret is the credential the connector authenticates with, so it stays random.
+        const held = projectResources(SERVICE, req.root).filter((r) => r.type === 'quick_tunnel').length;
+        const derive = (part, n) => createHash('sha256').update(`quick_tunnel:${part}:${req.occurredAt ?? ''}:${held}`).digest('hex').slice(0, n);
+        const uuidOf = (hex) => `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-${((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+        const id = uuidOf(derive('id', 32));
+        const name = derive('name', 16);
+        const hostname = `${derive('hostname', 16)}.trycloudflare.com`;
+        const accountTag = uuidOf(derive('account_tag', 32));
+        const secret = randomBytes(32).toString('base64');
+        await writeTunnel('quick_tunnel', `quick:${id}`, {
+            vendor: 'cloudflare', id, name, hostname, account_tag: accountTag, secret,
+            ephemeral: true, connected: false,
+        }, 'quick_tunnel.create', req);
+        return {
+            status: 200,
+            body: {
+                success: true,
+                result: { id, name, hostname, account_tag: accountTag, secret },
+                errors: [],
+            },
+            headers: { 'content-type': 'application/json' },
+        };
+    }
+    if (req.method === 'GET' && url.pathname === '/api/status') {
+        // Connection count is a live-process fact. The server adapter supplies its authoritative
+        // socket-map size; the pure reducer has no live sockets and therefore reports zero instead of
+        // treating an append-only historical registration as currently connected.
+        const tunnels = req.liveTunnels ?? 0;
+        return { status: 200, body: { ok: true, relay: 'twin-local', tunnels }, headers: { 'content-type': 'application/json' } };
+    }
+    return { status: 404, body: { error: 'not found' }, headers: { 'content-type': 'application/json' } };
+}
+/** Validate and normalize a registration without changing persisted or live ownership. The
+ * socket adapter uses this seam before it makes an existing owner inert, so a malformed takeover
+ * can never evict a healthy tunnel. */
+export function prepareTunnelRelayRegistration(input) {
+    const message = input.message;
+    if (message.type !== 'register')
+        return { session: input.session };
+    if (input.readOnly)
+        return { session: input.session, outbound: { type: 'error', fatal: true, message: 'tunnel twin is read-only' } };
+    const requested = input.authoritativeId || (typeof message.tunnelId === 'string' ? message.tunnelId : '') || randomUUID().slice(0, 8);
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(requested)) {
+        return { session: input.session, outbound: { type: 'error', fatal: true, message: 'Invalid tunnel ID' } };
+    }
+    if (typeof message.secret !== 'string' || message.secret.length === 0) {
+        return { session: input.session, outbound: { type: 'error', fatal: true, message: 'Tunnel rejected: credential is invalid or revoked.' } };
+    }
+    if (message.basicAuth !== undefined && (!message.basicAuth || typeof message.basicAuth !== 'object'
+        || typeof message.basicAuth.user !== 'string'
+        || typeof message.basicAuth.pass !== 'string')) {
+        return { session: input.session, outbound: { type: 'error', fatal: true, message: 'Invalid basic-auth configuration' } };
+    }
+    const basicAuthInput = message.basicAuth;
+    // The owned relay configures its Basic gate only when BOTH values are non-empty. The SDK/CLI can
+    // emit `{ user: 'name', pass: '' }`; upstream accepts that registration but leaves Basic auth
+    // unconfigured, so the twin must not invent a gate for the empty-value edge.
+    const basicAuth = basicAuthInput?.user && basicAuthInput.pass ? basicAuthInput : undefined;
+    const authRequired = message.authRequired !== false;
+    const basicAuthHash = basicAuth
+        ? createHash('sha256').update(`${basicAuth.user}:${basicAuth.pass}`).digest('hex')
+        : null;
+    const session = { tunnelId: requested, authRequired, registered: true, ...(basicAuth ? { basicAuth } : {}) };
+    return {
+        session,
+        registration: { tunnelId: requested, authRequired },
+        persistence: {
+            tunnelId: requested,
+            fields: {
+                vendor: 'volter-tunnel', tunnel_id: requested, connected: true, auth_required: authRequired,
+                basic_auth_configured: basicAuth !== undefined,
+                basic_auth_sha256: basicAuthHash,
+            },
+        },
+        outbound: { type: 'registered', tunnelId: requested, url: `${input.publicBaseUrl}/__twin/tunnels/${encodeURIComponent(requested)}` },
+    };
+}
+export async function persistTunnelRelayRegistration(prepared, options = {}) {
+    await writeTunnel('relay_tunnel', `relay:${prepared.persistence.tunnelId}`, {
+        ...prepared.persistence.fields,
+        ...(options.registrationId ? { registration_id: options.registrationId } : {}),
+    }, 'relay.register', { method: 'WS', path: '/ws', root: options.root, occurredAt: options.occurredAt });
+}
+/** Undo exactly the registration action identified by the durable registration id. Persistence can
+ * append successfully and still reject afterward (for example while projecting the result). A
+ * kernel revert preserves that attempted write in the audit log while suppressing its projection,
+ * restoring either the prior live owner or the prior absence byte-for-byte. */
+export function revertTunnelRelayRegistration(tunnelId, registrationId, options = {}) {
+    const actions = listActions(SERVICE, options.root);
+    const registration = [...actions].reverse().find((action) => action.operation === 'relay.register'
+        && action.subject.type === 'relay_tunnel' && action.subject.id === `relay:${tunnelId}`
+        && action.fields?.registration_id === registrationId);
+    if (!registration)
+        return false;
+    if (actions.some((action) => action.op === 'revert' && action.revertsActionId === registration.id))
+        return true;
+    appendAction({
+        id: `twin:tunnel:relay.register.rollback:${registrationId}`,
+        service: SERVICE,
+        op: 'revert',
+        operation: 'relay.register.rollback',
+        subject: registration.subject,
+        occurredAt: options.occurredAt ?? new Date().toISOString(),
+        actor: { kind: 'system', id: 'tunnel-twin' },
+        revertsActionId: registration.id,
+    }, options.root);
+    return true;
+}
+/** Reducer behind the WebSocket adapter. It is deliberately in a separate module so the
+ * mutation gate can replace it while the real socket/data-path adapter remains intact. */
+export async function handleTunnelRelayMessage(input) {
+    const prepared = prepareTunnelRelayRegistration(input);
+    if (!('persistence' in prepared))
+        return prepared;
+    await persistTunnelRelayRegistration(prepared, { root: input.root, occurredAt: input.occurredAt });
+    const { persistence: _persistence, ...reduction } = prepared;
+    return reduction;
+}
+/** Close codes 1005 ("no status") and 1006 ("abnormal") may never appear ON THE WIRE, and
+ *  anything outside 1000-4999 is not a close code at all — the vendor's client clamps the
+ *  identical way on the frames it receives. */
+export function clampTunnelCloseCode(raw) {
+    const code = typeof raw === 'number' ? raw : 1000;
+    return code >= 1000 && code <= 4999 && code !== 1005 && code !== 1006 ? code : 1000;
+}
+/** A close `reason` may carry at most 123 bytes. */
+export function clampTunnelCloseReason(raw) {
+    return typeof raw === 'string' ? raw.slice(0, 123) : '';
+}
+export function reduceTunnelWsFrame(input) {
+    const message = (input.message ?? {});
+    const type = message.type;
+    if (type !== 'ws-ready' && type !== 'ws-error' && type !== 'ws-message' && type !== 'ws-close')
+        return { kind: 'ignore' };
+    const connId = typeof message.connId === 'string' ? message.connId : '';
+    // AN UNKNOWN connId IS NOT A VIOLATION — it is the normal tail of every bridged close, in both
+    // directions: the vendor's client closes its local socket on a relayed `ws-close`, and that
+    // socket's own close listener echoes a `ws-close` back after the relay has already torn the
+    // bridge down. Answering "not owned by this control socket" there accuses a CORRECT client of
+    // a protocol violation on the happy path (§9).
+    if (!connId || input.ownership === 'unknown')
+        return { kind: 'ignore' };
+    // A control socket may only speak for the bridges IT was handed. Without this, any registered
+    // client could drive another tunnel's LIVE browser sockets by guessing a connId.
+    if (input.ownership === 'other')
+        return { kind: 'error', message: 'websocket correlation is not owned by this control socket' };
+    if (type === 'ws-ready')
+        return { kind: 'ready', connId };
+    if (type === 'ws-message') {
+        const raw = typeof message.data === 'string' ? message.data : '';
+        const data = Buffer.from(raw, 'base64');
+        // `Buffer.from(x, 'base64')` is LENIENT — it drops what it cannot parse — so the round trip
+        // is what rejects a payload that is not really base64, the same strictness the response
+        // frames' own decoder applies.
+        if (data.toString('base64').replace(/=+$/, '') !== raw.replace(/=+$/, ''))
+            return { kind: 'error', message: 'malformed ws-message frame' };
+        return { kind: 'deliver', connId, data: new Uint8Array(data), binary: message.binary === true };
+    }
+    if (type === 'ws-error') {
+        // 1011 "internal error" with the CLIENT's own reason — the browser learns why, and the relay
+        // does not invent one of its own.
+        const reason = typeof message.error === 'string' ? message.error : 'tunnel websocket error';
+        return { kind: 'close', connId, code: 1011, reason: clampTunnelCloseReason(reason) };
+    }
+    return { kind: 'close', connId, code: clampTunnelCloseCode(message.code), reason: clampTunnelCloseReason(message.reason) };
+}
+/** Persist a disconnect only for the registration generation that actually lost its socket.
+ * Replacement appends its new generation before transferring the live controls map, so a close
+ * from the prior socket can arrive in that interval. The server serializes this conditional write
+ * behind the registration turn; the identity check then prevents the stale close from overwriting
+ * the successor's durable connected state. */
+export async function markTunnelDisconnected(tunnelId, root, occurredAt, expectedRegistrationId) {
+    try {
+        await writeTunnel('relay_tunnel', `relay:${tunnelId}`, {
+            vendor: 'volter-tunnel', tunnel_id: tunnelId, connected: false,
+        }, 'relay.disconnect', { method: 'WS', path: '/ws', root, occurredAt }, expectedRegistrationId ? [{
+                subject: { type: 'relay_tunnel', id: `relay:${tunnelId}` },
+                field: 'registration_id',
+                op: 'eq',
+                value: expectedRegistrationId,
+            }] : undefined);
+    }
+    catch (error) {
+        if (expectedRegistrationId && error instanceof TwinActionPreconditionError)
+            return false;
+        throw error;
+    }
+    return true;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-tunnel",
+  "version": "0.1.0",
+  "description": "Local Cloudflare Quick Tunnel control-plane and Volter relay twin with a genuine loopback HTTP data path.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/tunnel"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-tunnel": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "@volter/tunnel": "^2.0.5",
+    "@volter/tunnel-core": "0.1.3",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createTunnelTwinServer, parseTunnelLoopbackOrigin } from './tunnel-server.ts';
+
+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() as { success: boolean; result?: { id: string } };
+  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`);
+  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.ts');
+  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');
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+export { createTunnelTwinFetch, createTunnelTwinHandler, createTunnelTwinServer } from './tunnel-server.ts';
+export { handleTunnelRelayMessage, handleTunnelTwinRequest } from './tunnel-twin.ts';
+export { liveTunnelExecute, mapTunnelRelay, pullTunnelRelay, syncTunnelFromReal } from './tunnel-connector.ts';
+export {
+  TunnelBudget, TunnelBudgetError, TUNNEL_RATE_BUDGET, TUNNEL_BUDGET_CEILING,
+  TUNNEL_BUDGET_WINDOW_MS, TUNNEL_CALL_WEIGHTS,
+} from './tunnel-budget.ts';
+export type { RelayControlMessage, RelaySession, TunnelRequest, TunnelResponse } from './tunnel-twin.ts';
+
+// Registry descriptor (#1): the pack self-describes so tooling can discover it.
+// A consumer does `registerPack(pack)` after importing this package.
+import type { TwinPack } from '@volter/world-core';
+import { TUNNEL_RATE_BUDGET as RATE_BUDGET } from './tunnel-budget.ts';
+export const pack: TwinPack = {
+  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'],
+  },
+};

package/src/tunnel-budget.ts

@@ -0,0 +1,34 @@
+import {
+  declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget,
+  type RateBudgetDeclaration, type RateBudgetOptions,
+} from '@volter/world-core';
+
+const VENDOR = 'tunnel';
+export const TUNNEL_BUDGET_WINDOW_MS = 60_000;
+export const TUNNEL_BUDGET_CEILING = 60;
+export const TUNNEL_CALL_WEIGHTS = { create: 3, other: 2 } as const;
+
+/** Cloudflare documents a 200 concurrent in-flight request cap for Quick Tunnels, but no scalar
+ * create-control-API rate. Volter's relay publishes data-plane and signup rates, not a status-read
+ * rate. The connector ledger is account-wide, so it uses the kernel's conservative fallback. */
+export const TUNNEL_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: TUNNEL_BUDGET_WINDOW_MS,
+  ceiling: TUNNEL_BUDGET_CEILING,
+  defaultWeight: TUNNEL_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: 300,
+  rules: [{ match: '^POST /tunnel$', weight: TUNNEL_CALL_WEIGHTS.create }],
+  reason:
+    'Cloudflare Quick Tunnels documentation (developers.cloudflare.com, fetched 2026-08-20) publishes a 200 concurrent in-flight data-plane cap but no scalar quick-control creation rate; the first-party cloudflared source POSTs /tunnel once per quick session. The owned volter-tunnel relay (a5abc628, 2026-08-20) publishes data-plane and signup limits, not a status-read rate. This account-wide connector therefore uses the kernel fallback: 60 weighted units/60s, reads weight 2 (30/min) and tunnel allocation weight 3 (20/min), never more permissive than an undeclared vendor.',
+};
+
+declareRateBudget(VENDOR, TUNNEL_RATE_BUDGET);
+export const tunnelCallWeight = (method: string, path: string) => rateBudgetWeight(VENDOR, `${method.toUpperCase()} ${path}`);
+export const tunnelBudgetPath = (opts: { root?: string; token?: string } | string = {}) => {
+  const value = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...value, vendor: VENDOR });
+};
+export type TunnelBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+export class TunnelBudget extends RateBudget {
+  constructor(opts: TunnelBudgetOptions = {}) { super({ ...opts, vendor: VENDOR }); }
+}
+export { RateBudgetError as TunnelBudgetError } from '@volter/world-core';