@volter/twin-tunnel 0.1.37 → 1.0.0

package/src/manifest.ts

@@ -0,0 +1,47 @@
+// The tunnel relay's manifest (volter-ai/volter-tunnel, spec/SOURCE.md): a protocol more than an API. A client holds
+// the control socket (`control`, semantics/sockets.ts) and answers the public requests the relay sends down it
+// (semantics/around.ts). Served is what Volter Harness's remote access uses (../journeys/demand.json).
+import type { DerivedManifest } from '@volter/world-core';
+
+export const manifest: DerivedManifest = {
+  vendor: 'tunnel',
+  service: 'tunnel',
+  body: { json: 'always' },
+  ids: { template: '{letters:8}' },
+  time: 'iso',
+  error: '{message}',
+  readOnly: { status: 403, message: 'This twin was started read-only; writes are refused.' },
+  notFound: { status: 404, message: 'Not Found' },
+  gap: { status: 404, message: 'Not Found' },
+  list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  deleted: {},
+  resources: {
+    _account: { idPrefix: '' },
+    // a tunnel id an account holds (one minted when a client names none)
+    _tunnel: { idPrefix: '' },
+  },
+  sockets: [
+    { id: 'control', path: '/ws', note: "a client's control channel: register, then answer each request the relay sends", source: 'https://github.com/volter-ai/volter-tunnel/blob/main/packages/core/src/protocol.ts' },
+  ],
+  doors: [
+    { id: 'accounts', method: 'POST', path: '/_twin/accounts', note: '{ slug }: an account on the relay and its token (the World application\'s TUNNEL_SECRET)' },
+  ],
+  discovery: {
+    twinOf: "Volter's tunnel relay (volter-tunnel) as Volter Harness's remote access uses it: a client's control socket, and every request to its tunnel answered through it",
+    stores: 'accounts and their tokens (by their SHA-256), and the tunnel ids they hold',
+    identity: "the account's token in the control channel's register frame",
+  },
+  descriptor: {
+    protocol: '3',
+    transport: 'rest',
+    archetype: 'proxy',
+    bin: 'world-tunnel',
+    resources: [],
+    specSource: 'written from volter-ai/volter-tunnel (spec/SOURCE.md)',
+    description: "Tunnel relay twin — a client's control socket (register, then each public request sent down it and answered by the frames it sends back), as Volter Harness's remote access shares a local server.",
+    adoption: { sdks: ['@volter/tunnel'], envStems: ['TUNNEL', 'VOLTERTUNNEL'] },
+    hosts: [{ host: 'voltertest.xyz' }, { suffix: '.voltertest.xyz' }, { host: 'www.voltertest.xyz', exclude: true }, { host: 'twins.voltertest.xyz', exclude: true }],
+    credentialDoor: { path: '/_twin/accounts', body: { slug: 'world' }, fill: { TUNNEL_SECRET: 'token', TUNNEL_SERVER_URL: 'server', SUPERCODE_TUNNEL_SERVER_URL: 'server' } },
+    endpointEnvNone: 'the relay URL is the credential door\'s (TUNNEL_SERVER_URL, SUPERCODE_TUNNEL_SERVER_URL), the World claiming voltertest.xyz',
+  },
+};

package/src/semantics/around.ts

@@ -0,0 +1,41 @@
+// THE RELAY'S FRONT: a request to a tunnel (its host `<tunnelId>.voltertest.xyz`, or `?__tunnel=<id>` on a direct host,
+// as the relay's worker routes one) is sent down the control socket of the client holding the tunnel and answered with
+// what the client sends back (the kernel's request answered by a session); anything else is the relay's own.
+import type { HandlerContext } from '@volter/world-core';
+import { b64encode, DOMAIN, holder, RESERVED } from './shared.ts';
+
+const text = (status: number, body: string): Response => new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+const HOP = new Set(['host', 'connection', 'upgrade', 'keep-alive', 'transfer-encoding', 'content-length']);
+
+/** The tunnel a request is for: its host's label, or `?__tunnel=` on a direct host (the relay's local testing). */
+function tunnelOf(request: Request): string | undefined {
+  const url = new URL(request.url);
+  const host = (request.headers.get('host') ?? url.host).toLowerCase().replace(/:\d+$/, '');
+  const label = host.endsWith(`.${DOMAIN}`) ? host.slice(0, -DOMAIN.length - 1) : undefined;
+  if (label && !label.includes('.') && !RESERVED.has(label)) return label;
+  const direct = host === 'localhost' || host.startsWith('127.') || host === '0.0.0.0' || !host.endsWith(DOMAIN);
+  return direct ? url.searchParams.get('__tunnel') ?? undefined : undefined;
+}
+
+export async function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response> {
+  const request = ctx.call.request;
+  const id = tunnelOf(request);
+  if (!id) return next();
+  const client = holder(ctx, id);
+  if (!client) return text(502, 'Tunnel not connected');
+  const url = new URL(request.url);
+  url.searchParams.delete('__tunnel');
+  const body = request.method === 'GET' || request.method === 'HEAD' ? null : new Uint8Array(await request.arrayBuffer());
+  // a body goes in one frame: over the relay's limit it is refused at once
+  if (body && body.length > 750_000) return text(413, 'Request body too large to tunnel (limit ~750KB)');
+  const headers = Object.fromEntries([...request.headers].filter(([k]) => !HOP.has(k.toLowerCase()) && !k.toLowerCase().startsWith('x-volter')));
+  // the relay's correlation key for this request on this client's socket: the socket's own count, not World state (a
+  // request the relay forwards is no subject of the World)
+  const reqId = `${client.id}-${(client.state.requests = Number(client.state.requests ?? 0) + 1)}`;
+  client.send({ type: 'request', reqId, method: request.method, path: `${url.pathname}${url.search}`, headers, body: body?.length ? b64encode(body) : null });
+  try {
+    return (await client.expect(reqId, 30_000)) as Response;
+  } catch {
+    return text(504, 'Tunnel timeout');
+  }
+}

package/src/semantics/doors.ts

@@ -0,0 +1,21 @@
+// The World's doors (architecture, "Doors, screens and the gap"): an account on the relay and its token, as its signup
+// makes one.
+import type { HandlerContext } from '@volter/world-core';
+import { ACCOUNT, sha256 } from './shared.ts';
+
+/** An account by its slug (answered again for the same slug) and its token, drawn from the World's secret. */
+export async function accounts(ctx: HandlerContext): Promise<Response> {
+  const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Record<string, unknown>;
+  const slug = String(b.slug ?? '');
+  // the relay's account slug (server-cf/src/credits.ts, SLUG_RE)
+  if (!/^[a-z0-9][a-z0-9-]{1,62}$/.test(slug)) return Response.json({ message: 'slug must be lowercase letters, digits and dashes' }, { status: 400 });
+  let account = ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.slug === slug);
+  // Where the documentation stops: a token's form is the relay's own; the twin's is `vt_` and 40 letters and digits
+  const tokenOf = async (id: string): Promise<string> => `vt_${(await ctx.secret(`tunnel-token:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 40)}`;
+  if (!account) {
+    const id = ctx.mint(ACCOUNT);
+    await ctx.record(ACCOUNT, { slug, token_sha256: sha256(ctx, await tokenOf(id)) }, id);
+    account = ctx.row(ACCOUNT, id)!;
+  }
+  return Response.json({ slug, token: await tokenOf(String(account.id)), server: `https://voltertest.xyz` }, { status: 201 });
+}

package/src/semantics/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+
+export const tunnelSemantics: Record<string, Handler> = {
+};

package/src/semantics/shared.ts

@@ -0,0 +1,26 @@
+// What the relay shares: accounts and their tokens (each by its SHA-256), the tunnel ids they hold, the relay's domain,
+// and a tunnel's control session found among the World's open sockets.
+import type { HandlerContext, SocketSession } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+export type { HandlerContext };
+export const ACCOUNT = '_account';
+export const TUNNEL = '_tunnel';
+// the relay's TUNNEL_DOMAIN (server-cf/wrangler.jsonc, spec/SOURCE.md)
+export const DOMAIN = 'voltertest.xyz';
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export const RESERVED = new Set(['www', 'twins']);
+
+export const sha256 = (ctx: Pick<HandlerContext, 'crypto'>, v: string): string => ctx.crypto.digest('sha256', v);
+export const tunnelUrl = (id: string): string => `https://${id}.${DOMAIN}`;
+
+/** A tunnel id as the relay's registry takes one: lowercase letters, digits and inner dashes. */
+export const validId = (id: string): boolean => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(id);
+
+/** The registered control session holding a tunnel, if a client holds it now. */
+export const holder = (ctx: Pick<HandlerContext, 'sockets'>, id: string): SocketSession | undefined =>
+  ctx.sockets('control').find((s) => s.state.registered === true && s.state.tunnelId === id);
+
+export const b64encode = (bytes: Uint8Array): string => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+export const b64decode = (text: string): Uint8Array => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));

package/src/semantics/sockets.ts

@@ -0,0 +1,69 @@
+// The relay's control channel (the manifest's socket `control`, the kernel's sockets.ts): a client registers a tunnel id
+// with its token and is told the tunnel's URL; then the relay sends it each public request (./../semantics/around.ts)
+// and the client answers with a whole `response` or a stream (`response-start`, `response-chunk`s, `response-end`),
+// which settle the request waiting on it by its `reqId`. Frames as volter-tunnel's protocol.ts defines them.
+import type { HandlerContext, SocketEngine, SocketSession } from '@volter/world-core';
+import { ACCOUNT, b64decode, holder, type Row, sha256, TUNNEL, tunnelUrl, validId } from './shared.ts';
+
+type Streams = Map<string, ReadableStreamDefaultController<Uint8Array>>;
+const obj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+const streams = (s: SocketSession): Streams => (s.state.streams ??= new Map()) as Streams;
+const headersOf = (v: unknown): Headers => { const h = new Headers(); for (const [k, x] of Object.entries(obj(v))) h.set(k, String(x)); return h; };
+
+/** A rejected registration: the error frame, then the close (protocol.ts `ErrorMsg`; tunnel-do's rejection). */
+function reject(s: SocketSession, message: string, code: number, reason: string): void {
+  s.send({ type: 'error', message });
+  s.close(code, reason);
+}
+
+async function register(s: SocketSession, msg: Row, ctx: HandlerContext): Promise<void> {
+  const token = typeof msg.secret === 'string' ? msg.secret : '';
+  const account = token ? ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.token_sha256 === sha256(ctx, token)) : undefined;
+  if (!account) return reject(s, 'Tunnel rejected: credential is invalid or revoked. On an owner-authenticated device, run "volter-tunnel tokens" and restore this host token, or sign in again on the host.', 4003, 'badToken');
+  // the control URL's ?id= names the tunnel (the routing relay's authority), else the register frame's, else one minted
+  // This id names a stored reservation: mint it, then record the reservation with its owner below. ctx.issue is for
+  // issued ids whose subjects the vendor does not store; its empty row would look like another account's reservation.
+  const id = String(s.state.tunnelId || msg.tunnelId || ctx.mint(TUNNEL));
+  if (!validId(id)) return reject(s, `Tunnel rejected: invalid tunnel id ${id}`, 4029, 'invalidId');
+  const held = ctx.row(TUNNEL, id);
+  // Where the documentation stops: a tunnel id another account holds is refused, as the relay's reservation refuses it
+  if (held && held._owner !== account.id) return reject(s, `Tunnel rejected: ${id} is reserved by another account`, 4029, 'reserved');
+  const live = holder(ctx, id);
+  if (live && live !== s) {
+    // Where the documentation stops: a live registration of the id is refused unless this one replaces it
+    if (msg.replace !== true) return reject(s, `Tunnel rejected: ${id} is already connected`, 4029, 'inUse');
+    live.state.registered = false;
+    live.close(4001, 'Replaced by new client');
+  }
+  if (!held) await ctx.record(TUNNEL, { _owner: account.id, reservedAt: ctx.occurredAt }, id);
+  Object.assign(s.state, { registered: true, tunnelId: id, account: account.id, authRequired: msg.authRequired !== false });
+  s.send({ type: 'registered', tunnelId: id, url: tunnelUrl(id) });
+}
+
+export const control: SocketEngine<HandlerContext> = {
+  open(s, ctx) {
+    s.state.tunnelId = new URL(ctx.call.request.url).searchParams.get('id') ?? '';
+  },
+  async message(s, data, ctx) {
+    let msg: Row;
+    try { msg = obj(JSON.parse(data)); } catch { return; }
+    if (msg.type === 'register') return register(s, msg, ctx);
+    if (s.state.registered !== true) return;
+    const reqId = String(msg.reqId ?? '');
+    if (msg.type === 'response') {
+      s.fulfil(reqId, new Response(msg.body ? b64decode(String(msg.body)) as Uint8Array<ArrayBuffer> : null, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+    } else if (msg.type === 'response-start') {
+      const body = new ReadableStream<Uint8Array>({ start: (c) => { streams(s).set(reqId, c); } });
+      s.fulfil(reqId, new Response(body, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+    } else if (msg.type === 'response-chunk') {
+      streams(s).get(reqId)?.enqueue(b64decode(String(msg.data ?? '')));
+    } else if (msg.type === 'response-end') {
+      streams(s).get(reqId)?.close();
+      streams(s).delete(reqId);
+    }
+  },
+  close(s) {
+    for (const c of streams(s).values()) { try { c.error(new Error('Tunnel closed')); } catch { /* already ended */ } }
+    streams(s).clear();
+  },
+};

package/src/semantics/states.ts

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

package/src/server.ts

@@ -0,0 +1,10 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp, type PackFetchOptions } from '@volter/world-core';
+import { createTunnelFetch } from './fetch.ts';
+
+export async function createTunnelTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const fetch = createTunnelFetch(options);
+  // the vendor's sockets, when its manifest declares any (the kernel's sockets.ts)
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch, ...(fetch.upgrade ? { upgrade: fetch.upgrade } : {}) });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -1,21 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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>;