@volter/twin-tunnel 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @volter/twin-tunnel
+
+> **Legacy connector helpers:** this package still has callable helpers using the retired v1
+> `syncPull` API. Those paths require migration before use on the current kernel;
+> older helper descriptions below do not establish current compatibility. Check the
+> [generated index](../../../generated/INDEX.md) for protocol standing and use the
+> [shared model](../../../docs/concepts/the-model.md) for current state semantics.
+
+A local twin of two tunnel surfaces used by Volter worlds:
+
+- Cloudflare Quick Tunnel allocation (`POST /tunnel`) using the first-party `cloudflared`
+  quick-service field envelope. Generated field values are independent twin-local facts; the twin
+  does not assert undocumented relationships among `id`, `name`, `hostname`, or `account_tag`.
+- The owned `@volter/tunnel` WebSocket control protocol and HTTP relay path.
+
+The boundary is deliberate. The control plane is twinned; payload transport is real loopback
+HTTP. `world-tunnel quick --url ...` prints the machine-readable
+`VOLTER_SHARE_URL=http://127.0.0.1:...` handshake and genuinely forwards through that loopback
+ingress. It does not claim Cloudflare edge QUIC, public DNS, TLS, reachability, or an SLA. Those
+remain real deployment concerns. `quick --url` accepts a credential-free loopback HTTP(S) origin
+only; path/query/fragment and backslash-normalized inputs are rejected rather than silently
+discarded while forwarding.
+
+```bash
+# Local share rehearsal used by world cookbooks
+world-tunnel quick --url http://127.0.0.1:3000
+
+# Standalone quick API + Volter relay
+world-tunnel serve --port 8787 --root .volter/world/tunnel
+world-tunnel conformance
+# Cloudflare control URL: http://127.0.0.1:8787/tunnel
+# @volter/tunnel host:   http://127.0.0.1:8787
+```
+
+An unmodified `@volter/tunnel` client registers against the `serve` URL and forwards requests to
+its configured local port. Its normal default (`authRequired: true`) is preserved: anonymous
+requests receive 401, and the server's `mintToken(tunnelId)` helper creates a fake-local,
+tunnel-bound HS256 token for Bearer/query/cookie rehearsal. Matching the owned relay default, a
+valid signed token without `tid` is shared SSO while a present `tid` must match; start `serve` with
+`--require-tid` to select the owned `REQUIRE_TID=true` policy. Basic-auth values remain only in the
+live socket session; the append-only kernel stores a SHA-256 digest and configured bit, never the
+plaintext. As upstream does, Basic auth is configured only when both user and password are
+non-empty; an SDK-emitted empty value leaves that gate disabled. The twin accepts any non-empty
+fake relay credential and rejects a missing one.
+
+**Browser WebSockets relay for real.** A `ws://<relay>/__twin/tunnels/<id>/<path>` upgrade passes
+the same Basic/JWT gates the HTTP path does, then bridges: the relay sends `ws-upgrade` with a
+fresh `connId`, the tunnelled path and the browser’s own handshake headers; the client answers
+`ws-ready` (or `ws-error`, which closes the browser socket with 1011 and the client’s own reason);
+`ws-message` carries base64 payloads with the `binary` flag in both directions; `ws-close` bridges
+either way with the vendor’s own code clamping. Frames a browser sends before `ws-ready` are
+QUEUED and delivered in order rather than dropped, a control socket may only drive the `connId`s
+it owns, and a control socket closing takes its bridges with it. `request-abort` is now sent from
+ONE place for every way a request can end badly — timeout, visitor hang-up, malformed frame, owner
+disconnect — so the client always stops producing for a request the relay has forgotten.
+
+Still explicit capability todos: reliable end-to-end incremental delivery and its
+backpressure/cancellation (see "the streaming trade" below), account/reservation management,
+usage metering, inspector/replay, and Cloudflare managed tunnels.
+
+There is no UI mirror. Both products' relevant surface is a CLI/control protocol; their hosted
+dashboards are incidental account and operations tooling, not an agent navigation target.
+
+## Coverage
+
+The capability manifest in `src/tunnel-capabilities.ts` is the honest denominator for both the
+Cloudflare Quick Tunnel allocation surface and the owned Volter relay. Run
+`bun scripts/twin-capabilities.ts tunnel` for the current counts. Every capability is classified
+as done or planned; nothing disappears behind a broad feature label.
+
+### Done (proven, verifiable)
+
+- Cloudflare Quick Tunnel allocation envelope, unique ephemeral allocations, persistence,
+  read-only refusal, and bounded reserved-route/loopback-origin handling.
+- Real loopback forwarding through both the quick adapter and the owned relay, including method,
+  path, body, status, the owned cache/privacy response-header rules, CORS preflight,
+  malformed-frame containment, and single durable/live ownership under overlapping claims.
+- Relay registration, replacement, disconnect, authentication, JWT bootstrap/cookie behavior,
+  session-only Basic-auth plaintext, persistence ordering, and live status.
+- An authoritative 15-discriminator census imported from `@volter/tunnel-core`, with one explicit
+  capability row per frame; implemented frames have transport proofs and unimplemented frames
+  remain planned. Fourteen of the fifteen now carry transport proofs — everything but `quota` —
+  driven over a genuine loopback WebSocket against a real local server, with the pretend client
+  a harness shaped after the owned client's `handleWsUpgrade` — it dials with the offered
+  subprotocols, strips the hop-by-hop handshake headers, and reports a real local failure as
+  `ws-error`; it does not reproduce the client's `x-forwarded-*` re-stamping, its 15s dial
+  timeout or `safeClose`'s teardown, none of which any assertion depends on.
+- Visitor-disconnect abort: a browser hang-up before `response-start` sends `request-abort`, and
+  the request is genuinely FORGOTTEN — a late response frame naming it is refused.
+- Read-only connector pull, mapping, idempotence, refusal-state survival, conformance, and the
+  fail-closed persistent live-call budget.
+
+### The streaming trade, measured
+
+The relay BUFFERS a streamed response to `response-end` before answering the visitor, and that is
+a measured choice rather than an unfinished one. On this runtime a response body that has begun
+cannot be failed THROUGH `Bun.serve`'s response surface: erroring the `ReadableStream` behind a
+`Response` ends the chunked body cleanly,
+so a visitor reads a truncated payload as a successful 200 and cannot tell it from a complete one
+— and a `content-length` that would have made the truncation detectable is dropped the moment the
+body is a stream. `node:http` on the SAME runtime CAN signal it (`src/tunnel-stream-boundary.test.ts`
+measures that too) — so this is a trade with a named alternative, not an impossibility: re-hosting
+the HTTP plane would mean giving up `server.upgrade`, which the entire WebSocket bridge is built
+on. The first two measurements go RED the day `Bun.serve` gains the ability; that is the signal to build
+`tunnel.volter.http.streaming`, `…stream_backpressure` and `…stream_cancel_abort` and revisit the
+trade. Committing the head today would buy latency and sell the ability to fail a response
+honestly — which is what keeps the malformed-sequence 502 reachable at all.
+`stream_backpressure` has a second, independent blocker: the owned protocol's fifteen
+discriminators contain no pause frame, so a relay cannot ask a client to slow down.
+
+### Planned (todo — covered by default, not yet built)
+
+- Reliable incremental streaming, backpressure and cancellation (blocked as above).
+- Reconnect/backoff, quota frames, forwarded/response-header rules, rate limiting, and
+  constant-time shared-secret comparison.
+- Managed tunnel/account/reservation/usage/signup/inspector surfaces and confirmed public push.
+- Cloudflare Quick Tunnel concurrency and SSE limitations, plus Cloudflare managed tunnels.
+
+### No UI mirror
+
+The modeled products expose a CLI, HTTP API, and WebSocket control protocol. Their hosted account
+dashboards are operations tooling rather than an agent workflow, so this package deliberately has
+no React mirror and no UI capabilities. Coverage is API + connector.

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

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

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

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

@@ -0,0 +1,21 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions } from '@volter/world-core';
+export declare const TUNNEL_BUDGET_WINDOW_MS = 60000;
+export declare const TUNNEL_BUDGET_CEILING = 60;
+export declare const TUNNEL_CALL_WEIGHTS: {
+    readonly create: 3;
+    readonly other: 2;
+};
+/** 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 declare const TUNNEL_RATE_BUDGET: RateBudgetDeclaration;
+export declare const tunnelCallWeight: (method: string, path: string) => number;
+export declare const tunnelBudgetPath: (opts?: {
+    root?: string;
+    token?: string;
+} | string) => string;
+export type TunnelBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+export declare class TunnelBudget extends RateBudget {
+    constructor(opts?: TunnelBudgetOptions);
+}
+export { RateBudgetError as TunnelBudgetError } from '@volter/world-core';

package/dist/src/tunnel-budget.js

@@ -0,0 +1,26 @@
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } 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 };
+/** 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 = {
+    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, path) => rateBudgetWeight(VENDOR, `${method.toUpperCase()} ${path}`);
+export const tunnelBudgetPath = (opts = {}) => {
+    const value = typeof opts === 'string' ? { root: opts } : opts;
+    return rateBudgetPath({ ...value, vendor: VENDOR });
+};
+export class TunnelBudget extends RateBudget {
+    constructor(opts = {}) { super({ ...opts, vendor: VENDOR }); }
+}
+export { RateBudgetError as TunnelBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const TUNNEL_CAPABILITIES: CapabilitySpec[];
+export declare const TUNNEL_AREAS: readonly ["cloudflare_quick", "cloudflare_managed", "volter_control", "volter_http", "volter_websocket", "volter_auth", "volter_reservations", "volter_accounts", "volter_usage", "volter_signup", "volter_inspector", "volter_management", "connector"];
+export declare function tunnelCapabilities(): Promise<CapabilityReport>;