@volter/twin-tunnel 0.1.0

package/src/tunnel-twin.ts

@@ -0,0 +1,339 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { appendAction, applyTwinWrite, listActions, projectResources, TwinActionPreconditionError, type TwinActionPrecondition } 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',
+] as const;
+
+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> };
+
+function nextRev(id: string, root?: string): number {
+  let max = 0;
+  for (const action of listActions(SERVICE, root)) {
+    if (action.subject?.id !== id) continue;
+    const rev = (action.fields as Record<string, unknown> | undefined)?.rev;
+    if (typeof rev === 'number') max = Math.max(max, rev);
+  }
+  return max + 1;
+}
+
+async function writeTunnel(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  operation: string,
+  req: TunnelRequest,
+  preconditions?: TwinActionPrecondition[],
+): Promise<void> {
+  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: TunnelRequest): Promise<TunnelResponse> {
+  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: string, n: number): string => createHash('sha256').update(`quick_tunnel:${part}:${req.occurredAt ?? ''}:${held}`).digest('hex').slice(0, n);
+    const uuidOf = (hex: string): string => `${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' } };
+}
+
+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 function prepareTunnelRelayRegistration(input: {
+  message: unknown;
+  session: RelaySession;
+  authoritativeId?: string;
+  publicBaseUrl: string;
+  readOnly?: boolean;
+}): RelayReduction | PreparedRelayRegistration {
+  const message = input.message as Partial<RelayControlMessage> & Record<string, unknown>;
+  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 as Record<string, unknown>).user !== 'string'
+    || typeof (message.basicAuth as Record<string, unknown>).pass !== 'string'
+  )) {
+    return { session: input.session, outbound: { type: 'error', fatal: true, message: 'Invalid basic-auth configuration' } };
+  }
+  const basicAuthInput = message.basicAuth as { user: string; pass: string } | undefined;
+  // 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: PreparedRelayRegistration,
+  options: { root?: string; occurredAt?: string; registrationId?: string } = {},
+): Promise<void> {
+  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: string,
+  registrationId: string,
+  options: { root?: string; occurredAt?: string } = {},
+): boolean {
+  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 as Record<string, unknown> | undefined)?.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: {
+  message: unknown;
+  session: RelaySession;
+  authoritativeId?: string;
+  publicBaseUrl: string;
+  root?: string;
+  occurredAt?: string;
+  readOnly?: boolean;
+}): Promise<RelayReduction> {
+  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;
+}
+
+/**
+ * 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 function clampTunnelCloseCode(raw: unknown): number {
+  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: unknown): string {
+  return typeof raw === 'string' ? raw.slice(0, 123) : '';
+}
+
+export function reduceTunnelWsFrame(input: { message: unknown; ownership: TunnelWsOwnership }): TunnelWsDecision {
+  const message = (input.message ?? {}) as Record<string, unknown>;
+  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: string,
+  root?: string,
+  occurredAt?: string,
+  expectedRegistrationId?: string,
+): Promise<boolean> {
+  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;
+}