@johnhenry/wsh 0.29.0 → 0.31.0

package/src/memory-host.mjs

@@ -0,0 +1,175 @@
+/**
+ * `@johnhenry/wsh/memory` -- a wsh host that lives in the same JavaScript realm as its clients, with no sockets, no
+ * ports and no Node. Browser-safe (a page, a Worker, Deno, Bun, Node): it imports nothing from `node:*`, and a test
+ * (`test/memory-host.test.mjs`) keeps it that way. For demos, docs and tests of an application that talks wsh.
+ *
+ * It is the real protocol end to end -- the same connection handler `createWshServer` runs (handshake, Ed25519 or
+ * password auth, exec channels, MCP tools, extensions), speaking QMux over a pair of in-memory WebSocket-like
+ * sockets -- so what a client does here is what it does against a server. It serves what a browser can: `exec` as a
+ * function you provide (there is no shell), `mcp` tools, `extensions`. Not available: `pty`, `fs`, `gateway`, `relay`,
+ * `sessions`, `rpc`, `hostKey`, WebTransport (they need Node; use `@johnhenry/wsh/server`).
+ *
+ * ```js
+ * import { createMemoryHost } from '@johnhenry/wsh/memory';
+ * const host = createMemoryHost({
+ *   auth: { authorizedKeys: [rawPublicKey] },
+ *   exec: async (command, io) => { await io.write(`you ran: ${command}\n`); return 0; },
+ * });
+ * const client = await host.connect({ username: 'demo', keyPair });
+ * ```
+ */
+
+import { WshClient } from './client.mjs';
+import { WebSocketTransport } from './transport-ws.mjs';
+import { createConnectionFactory } from './server/connection.mjs';
+import { buildAuthorizer, authMethods, FailureLimiter } from './server/auth.mjs';
+import { createMcpHost } from './server/mcp.mjs';
+import { bindSocket } from './server/socket.mjs';
+
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+
+/** The URL to hand `client.connect()` (the host ignores it; it only has to look like a WebSocket URL). */
+const MEMORY_URL = 'ws://memory.invalid/';
+
+function event(type, props) {
+  const ev = new Event(type);
+  Object.assign(ev, props);
+  return ev;
+}
+
+/** One end of an in-memory socket pair: just enough WebSocket for `WebSocketTransport` and `bindSocket`. */
+class MemorySocket extends EventTarget {
+  static CONNECTING = CONNECTING;
+  static OPEN = OPEN;
+  static CLOSING = CLOSING;
+  static CLOSED = CLOSED;
+
+  readyState = CONNECTING;
+  binaryType = 'arraybuffer';
+  /** @type {MemorySocket | null} */
+  peer = null;
+
+  send(data) {
+    if (this.readyState !== OPEN) throw new Error('WebSocket is not open');
+    if (typeof data === 'string') return; // wsh frames are binary
+    const view = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const copy = view.slice().buffer;
+    const peer = this.peer;
+    queueMicrotask(() => { if (peer.readyState === OPEN) peer.dispatchEvent(event('message', { data: copy })); });
+  }
+
+  close(code = 1000, reason = '') {
+    if (this.readyState >= CLOSING) return;
+    this.readyState = CLOSING;
+    const peer = this.peer;
+    queueMicrotask(() => {
+      for (const s of [this, peer]) {
+        if (s.readyState === CLOSED) continue;
+        s.readyState = CLOSED;
+        s.dispatchEvent(event('close', { code, reason, wasClean: true }));
+      }
+    });
+  }
+}
+
+/**
+ * Two connected sockets: what one sends, the other receives (asynchronously, in order). Both are open after a tick.
+ * @returns {[MemorySocket, MemorySocket]}
+ */
+export function createSocketPair() {
+  const a = new MemorySocket();
+  const b = new MemorySocket();
+  a.peer = b;
+  b.peer = a;
+  queueMicrotask(() => {
+    for (const s of [a, b]) { s.readyState = OPEN; s.dispatchEvent(new Event('open')); }
+  });
+  return [a, b];
+}
+
+/**
+ * @param {object} [options]
+ * @param {object | Function} [options.auth] - As for `createWshServer`. Omitted = refuse everyone.
+ * @param {Function | { run: Function, timeoutMs?: number, clientEnv?: boolean }} [options.exec]
+ *   `run(command, io) => Promise<exitCode>` (see `ExecIo` in `server/exec.mjs`): the host has no shell, so there is no `true`.
+ * @param {{ tools?: object[] | object, client?: object, authorize?: Function, maxConcurrent?: number, timeoutMs?: number }} [options.mcp]
+ * @param {Record<string, Function>} [options.extensions] - Handlers for application-defined messages, as for `createWshServer`.
+ * @param {number} [options.bindTimeoutMs=3000]
+ * @param {(line: string) => void} [options.onLog]
+ */
+export function createMemoryHost({ auth, exec, mcp, extensions, bindTimeoutMs = 3000, onLog = () => {} } = {}) {
+  if (exec === true) throw new TypeError('createMemoryHost: exec must be a function (run(command, io)); there is no shell to run `true` with');
+  if (exec !== undefined && typeof exec !== 'function' && typeof exec?.run !== 'function') {
+    throw new TypeError('createMemoryHost: exec must be a function or { run }');
+  }
+  if (extensions !== undefined && (extensions === null || typeof extensions !== 'object')) throw new TypeError('createMemoryHost: extensions must be an object of handlers');
+  const execOptions = typeof exec === 'function' || !exec ? {} : exec;
+  const execRunner = typeof exec === 'function' ? exec : exec?.run ?? null;
+  const rl = auth?.rateLimit ?? {};
+  const rateLimit = {
+    limiter: new FailureLimiter(rl),
+    key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
+    failureDelayMs: rl.failureDelayMs ?? 250,
+  };
+  const methods = authMethods(auth);
+  const mcpHost = mcp ? createMcpHost(mcp) : null;
+
+  const ready = buildAuthorizer(auth).then((authorize) => createConnectionFactory({
+    authorize, execRunner, execOptions, pty: null, files: null, bindTimeoutMs, log: onLog,
+    methods, hostKey: null, rateLimit, extensions, mcp: mcpHost, rpc: null, gateway: null, sessions: null, relay: null,
+  }));
+  ready.catch(() => {});
+
+  const accepted = new Set();
+  let closed = false;
+
+  async function accept(socket, options) {
+    if (closed) throw new Error('createMemoryHost: host is closed');
+    const handle = await bindSocket(socket, ready, options);
+    accepted.add(handle);
+    return handle;
+  }
+
+  /** A `WebSocket` constructor that dials this host: `new host.WebSocket(url)` ignores the URL. */
+  class HostWebSocket extends MemorySocket {
+    constructor() {
+      super();
+      const [client, server] = createSocketPair();
+      void accept(server, { remote: { address: 'memory' } }).catch(onLog);
+      return client;
+    }
+  }
+
+  const host = {
+    /** Pass to `client.connect()`. */
+    url: MEMORY_URL,
+    WebSocket: HostWebSocket,
+    accept,
+    socketPair: createSocketPair,
+    /** A `WshClient` whose transport is this host (`await client.connect(host.url, ...)`). */
+    createClient(clientOptions = {}) {
+      return new WshClient({
+        ...clientOptions,
+        transportFactories: {
+          ws: () => new WebSocketTransport({ WebSocket: HostWebSocket }),
+          wt: () => { throw new Error('createMemoryHost: WebTransport is not available in memory'); },
+        },
+      });
+    },
+    /** `createClient()` and `connect()` in one: resolves to a connected client. */
+    async connect(credentials) {
+      const client = host.createClient();
+      await client.connect(MEMORY_URL, { transport: 'ws', ...credentials });
+      return client;
+    },
+    async close() {
+      closed = true;
+      for (const handle of accepted) handle.close();
+      accepted.clear();
+    },
+  };
+  return host;
+}

package/src/recording.mjs

@@ -2,8 +2,14 @@
  * Session recording and playback for wsh PTY sessions.
  *
  * Records all terminal I/O with timestamps for later replay.
- * The export format is compatible with the asciicast v2 structure
- * used by asciinema, enabling interop with standard terminal players.
+ * The export (`toJSON()`) is asciicast-v2-*shaped*, not an asciicast v2 file: the header
+ * fields (`version: 2`, `width`, `height`, `timestamp`, `env`) and the `[seconds, code, data]`
+ * events with the `o` / `i` / `r` codes are asciicast's, but it is one JSON document (asciicast
+ * v2 is newline-delimited JSON: a header line, then one event per line), the header carries
+ * wsh's own `sessionId`, `width`/`height` follow the latest resize rather than the start size,
+ * and the lifecycle events `open` / `exit` have no asciicast code. `asciinema play` therefore
+ * cannot read it as-is. The README ("Session recording") shows the short conversion to a real
+ * `.cast` file (header line + the `o`/`i`/`r` events); `fromJSON()` reads this document shape.
  */
 
 // ── SessionRecorder ──────────────────────────────────────────────────
@@ -66,16 +72,17 @@ export class SessionRecorder {
   /**
    * Export the recording as a JSON-serializable object.
    *
-   * The format is compatible with asciicast v2:
+   * The shape follows asciicast v2 but this is NOT a playable asciicast file (see the file header):
    *   - version: 2
-   *   - width, height: terminal dimensions at start
+   *   - width, height: terminal dimensions as of the latest resize (asciicast: at start)
    *   - timestamp: Unix epoch seconds when recording started
-   *   - env: optional environment metadata
-   *   - events: array of [time_seconds, event_type, data]
+   *   - env: environment metadata
+   *   - sessionId: wsh's own field
+   *   - events: array of [time_seconds, event_type, data] -- one JSON document, not one line per event
    *
-   * Event types in asciicast:
-   *   "o" = output, "i" = input, "r" = resize
-   * We extend with: "open", "exit" for session lifecycle.
+   * Event types from asciicast:
+   *   "o" = output, "i" = input, "r" = resize ("COLSxROWS")
+   * Not in asciicast, so dropped by the conversion in the README: "open", "exit" (session lifecycle).
    *
    * @returns {object}
    */
@@ -111,7 +118,8 @@ export class SessionRecorder {
   }
 
   /**
-   * Import a recording from JSON (as produced by toJSON or parsed from asciicast).
+   * Import a recording from the JSON document `toJSON()` produces. An asciicast v2 `.cast` file is not read directly:
+   * parse its lines and gather them into `{ ...header, events }` first.
    *
    * @param {object | string} json - Recording object or JSON string
    * @returns {SessionRecorder}

package/src/server/connection.mjs

@@ -13,7 +13,6 @@
  * dropped rather than forwarded to the process's stdin.
  */
 
-import { randomUUID } from 'node:crypto';
 import { QMuxConnection } from '../qmux-connection.mjs';
 import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
@@ -24,13 +23,13 @@ import {
 import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
 } from '../auth.mjs';
-import { FILE_CHUNK_BYTES } from './fs.mjs';
-import { MAX_ATTACHMENTS } from './sessions.mjs';
+import { FILE_CHUNK_BYTES, MAX_ATTACHMENTS } from './constants.mjs';
 import { MCP_CALL_ID_FEATURE } from '../client.mjs';
 import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } from '../rpc.mjs';
 import { sealFrame, openFrame, ROLE_TAGS } from '../e2e-frame.mjs';
 import { E2EResponder, E2E_FEATURE, E2E_SIGN_FEATURE } from '../e2e-exchange.mjs';
 import { MULTI_OPERATOR_FEATURE } from './relay.mjs';
+import { createGatewaySession } from './gateway.mjs';
 import { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
@@ -44,6 +43,7 @@ export const STREAM_ANNOUNCE = 'stream-announce';
 export function hostFeatures(cfg, { dataStreams = true } = {}) {
   const features = dataStreams ? [STREAM_ANNOUNCE] : [];
   if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
+  if (cfg.gateway) features.push('gateway');
   if (cfg.files) features.push('file-transfer', 'file-write', 'file-rename');
   // End-to-end encryption (#90) is the virtual-mode EncryptedFrame layer, so it is offered where there are no
   // client-opened streams: over a relay bridge.
@@ -68,6 +68,7 @@ const REPLAY_CHUNK_BYTES = 32 * 1024;
 const USERNAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
 const enc = new TextEncoder();
 
+const randomUUID = () => crypto.randomUUID();
 const randomBytes = (n) => crypto.getRandomValues(new Uint8Array(n));
 const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
 
@@ -83,6 +84,7 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {object | null} cfg.mcp - from createMcpHost
  * @param {{ protocols: Map<string, Function>, maxMessageBytes: number, maxInflight: number } | null} cfg.rpc - from createRpcHost
  * @param {{ signKey: CryptoKey | null, hybrid?: boolean } | null} cfg.e2e - answer KeyExchange and seal virtual-mode traffic (bridged connections only)
+ * @param {object | null} cfg.gateway - from normalizeGateway: TCP/DNS egress for the client (default deny)
  * @param {Record<string, Function> | undefined} cfg.extensions - handlers for application-defined (string-typed) messages
  * @param {object | null} cfg.relay - a RelayHub (see relay.mjs); null = not a relay
  * @param {object | null} cfg.sessions - a SessionRegistry (see sessions.mjs); null = sessions die with their connection
@@ -124,6 +126,8 @@ export function createConnectionFactory(cfg) {
     /** This connection as the relay hub sees it (created on first need). */
     let relayHandle = null;
 
+    const gateway = cfg.gateway ? createGatewaySession(cfg.gateway, (m) => send(m), log) : null;
+
     const qmux = sendMessage ? null : new QMuxConnection({ isClient: false, send: (b) => { if (!state.closed) sendBytes(b); } });
 
     // ── End-to-end encryption (#90) ──────────────────────────────────
@@ -177,6 +181,7 @@ export function createConnectionFactory(cfg) {
       for (const ch of [...channels.values()]) (ch.detach ?? ch.kill)?.call(ch);
       channels.clear();
       responder?.close();
+      gateway?.close();
       e2eSessions.clear();
       for (const c of mcpCalls) c.abort(new Error('connection closed'));
       mcpCalls.clear();
@@ -225,6 +230,7 @@ export function createConnectionFactory(cfg) {
       if (state.closed) return;
       if (!state.authed) return handleAuth(m);
       if (await handleRelay(m)) return;
+      if (gateway && await gateway.handle(m)) return;
       switch (m.type) {
         case MSG.PING: return send(pong({ id: m.id }));
         case MSG.OPEN: return handleOpen(m);
@@ -824,7 +830,7 @@ export function createConnectionFactory(cfg) {
         const args = m.command ? ['-c', String(m.command)] : [];
         proc = p.spawn(p.shell, args, {
           name: p.term, cols, rows, cwd: p.cwd,
-          env: { ...(p.env ?? process.env), TERM: p.term, ...(m.env && typeof m.env === 'object' ? m.env : {}) },
+          env: { ...(p.env ?? globalThis.process?.env), TERM: p.term, ...(m.env && typeof m.env === 'object' ? m.env : {}) },
         });
       } catch (e) {
         return send(openFail({ reason: `pty spawn failed: ${e.message}` }));

package/src/server/constants.mjs

@@ -0,0 +1,10 @@
+/**
+ * Limits shared by the connection handler and the Node-only modules that also export them
+ * (kept here so the connection handler imports nothing from `node:*` -- see `src/memory-host.mjs`).
+ */
+
+/** Size of one FileChunk when a file is streamed to the client. */
+export const FILE_CHUNK_BYTES = 64 * 1024;
+
+/** Most clients attached to one detached-session at once. */
+export const MAX_ATTACHMENTS = 16;

package/src/server/fs.mjs

@@ -14,7 +14,8 @@ import { constants as fsc } from 'node:fs';
 import path from 'node:path';
 
 export const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
-export const FILE_CHUNK_BYTES = 64 * 1024;
+import { FILE_CHUNK_BYTES } from './constants.mjs';
+export { FILE_CHUNK_BYTES };
 
 /**
  * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} opts

package/src/server/gateway.mjs

@@ -0,0 +1,248 @@
+/**
+ * Gateway for the Node server: the TCP and DNS half of the wire protocol's
+ * gateway opcodes (0x70-0x7e), which until now only the Rust `wsh-server`
+ * answered. It lets an authenticated client (typically a browser tab running
+ * `GatewayBackend` from `@johnhenry/browsermesh-netway`) open TCP connections
+ * and resolve names FROM THE HOST, so a page can reach a plain-TCP service
+ * (an MQTT broker, a database) that a browser cannot.
+ *
+ * Off unless `createWshServer({ gateway })` is given, and then default-deny:
+ * a destination must match `allow`. Pattern forms (the same as the Rust policy):
+ * `"*"` any host and port, `"host"` that name on any port, `"host:port"`.
+ * Matching is on the NAME the client asked for, case-insensitively; with `socks`
+ * set the name is handed to the proxy unresolved, so the host never looks it up.
+ *
+ * Not implemented, and answered with a clean GatewayFail / ListenFail rather than
+ * silence: UDP (`OpenUdp`) and reverse tunnels (`ListenRequest`).
+ *
+ * `socks`: dial through a SOCKS5 proxy (`'host:port'`, `socks5://host:port` or
+ * `{ host, port }`), e.g. a local Tor client (`127.0.0.1:9050`). Commands carry the
+ * destination as a domain name (ATYP 3), so name resolution happens at the proxy
+ * (no DNS leak) and `.onion` names work. In that mode `ResolveDns` is refused:
+ * the host would have to resolve the name itself.
+ */
+
+import { MSG, gatewayOk, gatewayFail, gatewayClose, gatewayData, dnsResult, listenFail } from '../messages.gen.mjs';
+
+// Loaded on first use so that importing the connection handler (which serves the gateway opcodes)
+// does not pull `node:net` into a browser bundle (see `src/memory-host.mjs`).
+let netModule = null;
+let dnsModule = null;
+const loadNet = async () => (netModule ??= (await import('node:net')).default);
+const loadDns = async () => (dnsModule ??= (await import('node:dns/promises')).default);
+
+/** Numeric codes of GatewayFail (the same table `@johnhenry/browsermesh-netway` decodes). */
+export const GATEWAY_FAIL = Object.freeze({
+  CONNECTION_REFUSED: 1, HOST_UNREACHABLE: 2, DNS_FAILED: 3, POLICY_DENIED: 4, TIMEOUT: 5, CLOSED: 6, QUEUE_FULL: 7,
+});
+
+const DEFAULT_MAX_CONNECTIONS = 32;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
+const MAX_DATA_BYTES = 1024 * 1024;
+
+/** @param {string|{host:string,port:number}} socks */
+export function parseSocks(socks) {
+  if (socks === undefined || socks === null || socks === false) return null;
+  if (typeof socks === 'object') {
+    if (!socks.host || !Number.isInteger(socks.port)) throw new TypeError('gateway.socks must be "host:port" or { host, port }');
+    return { host: String(socks.host), port: socks.port };
+  }
+  const m = /^(?:socks5h?:\/\/)?(\[[^\]]+\]|[^:/]+):(\d{1,5})$/.exec(String(socks));
+  if (!m) throw new TypeError('gateway.socks must be "host:port" or { host, port }');
+  return { host: m[1].replace(/^\[|\]$/g, ''), port: Number(m[2]) };
+}
+
+/** Does `host:port` match one of the allow patterns? */
+export function destinationAllowed(allow, host, port) {
+  const h = String(host).toLowerCase();
+  for (const raw of allow) {
+    const p = String(raw).toLowerCase();
+    if (p === '*' || p === h || p === `${h}:${port}`) return true;
+  }
+  return false;
+}
+
+/**
+ * SOCKS5 CONNECT (RFC 1928) with no authentication, destination as a domain name.
+ * Resolves with the connected socket, or rejects with an Error carrying `.code`
+ * (a GATEWAY_FAIL value).
+ */
+export async function socksConnect(proxy, host, port, { timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS } = {}) {
+  const net = await loadNet();
+  return new Promise((resolve, reject) => {
+    const name = Buffer.from(host, 'utf8');
+    const fail = (code, message, sock) => { sock?.destroy(); const e = new Error(message); e.code = code; reject(e); };
+    if (name.length === 0 || name.length > 255) return fail(GATEWAY_FAIL.DNS_FAILED, 'invalid host name');
+    const sock = net.connect({ host: proxy.host, port: proxy.port });
+    sock.setNoDelay(true);
+    const timer = setTimeout(() => fail(GATEWAY_FAIL.TIMEOUT, 'SOCKS5 connect timed out', sock), timeoutMs);
+    let stage = 'method';
+    let buf = Buffer.alloc(0);
+    sock.once('error', (e) => { clearTimeout(timer); fail(GATEWAY_FAIL.HOST_UNREACHABLE, `SOCKS5 proxy: ${e.message}`, sock); });
+    sock.once('connect', () => sock.write(Buffer.from([0x05, 0x01, 0x00])));
+    const onData = (d) => {
+      buf = Buffer.concat([buf, d]);
+      if (stage === 'method') {
+        if (buf.length < 2) return;
+        if (buf[0] !== 0x05 || buf[1] !== 0x00) { clearTimeout(timer); return fail(GATEWAY_FAIL.POLICY_DENIED, 'SOCKS5 proxy requires authentication', sock); }
+        buf = buf.subarray(2);
+        stage = 'reply';
+        const req = Buffer.alloc(7 + name.length);
+        req.set([0x05, 0x01, 0x00, 0x03, name.length], 0);
+        name.copy(req, 5);
+        req.writeUInt16BE(port, 5 + name.length);
+        sock.write(req);
+      }
+      if (stage === 'reply') {
+        if (buf.length < 5) return;
+        const atyp = buf[3];
+        const need = 4 + (atyp === 0x01 ? 4 : atyp === 0x04 ? 16 : 1 + buf[4]) + 2;
+        if (buf.length < need) return;
+        clearTimeout(timer);
+        sock.off('data', onData);
+        sock.removeAllListeners('error');
+        const rest = buf.subarray(need);
+        if (buf[1] !== 0x00) {
+          const code = buf[1] === 0x05 ? GATEWAY_FAIL.CONNECTION_REFUSED : buf[1] === 0x04 || buf[1] === 0x03 ? GATEWAY_FAIL.HOST_UNREACHABLE : buf[1] === 0x02 ? GATEWAY_FAIL.POLICY_DENIED : GATEWAY_FAIL.HOST_UNREACHABLE;
+          return fail(code, `SOCKS5 proxy refused (reply 0x${buf[1].toString(16)})`, sock);
+        }
+        if (rest.length) sock.unshift(rest);
+        resolve(sock);
+      }
+    };
+    sock.on('data', onData);
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {string[]} [opts.allow=[]]  destination patterns; empty = nothing is reachable
+ * @param {number} [opts.maxConnections=32]  concurrent gateway sockets per client connection
+ * @param {number} [opts.connectTimeoutMs=15000]
+ * @param {string|{host:string,port:number}} [opts.socks]  dial through this SOCKS5 proxy (Tor)
+ * @param {(line: string) => void} [opts.log]
+ */
+export function normalizeGateway(opts) {
+  if (opts === true) throw new TypeError('createWshServer: gateway needs an explicit allow list (default deny): { allow: ["host:port", ...] }');
+  if (!opts || typeof opts !== 'object') return null;
+  const allow = opts.allow ?? [];
+  if (!Array.isArray(allow) || allow.some((a) => typeof a !== 'string' || !a)) throw new TypeError('gateway.allow must be an array of non-empty strings');
+  const maxConnections = opts.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+  if (!Number.isInteger(maxConnections) || maxConnections < 1) throw new TypeError('gateway.maxConnections must be a positive integer');
+  return {
+    allow: [...allow],
+    maxConnections,
+    connectTimeoutMs: opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    socks: parseSocks(opts.socks),
+  };
+}
+
+/**
+ * The per-connection half: one instance per client connection, torn down with it.
+ * @param {ReturnType<typeof normalizeGateway>} cfg
+ * @param {(msg: object) => unknown} send
+ * @param {(line: string) => void} log
+ */
+export function createGatewaySession(cfg, send, log = () => {}) {
+  /** @type {Map<number, net.Socket>} */
+  const sockets = new Map();
+  /** gateway_ids whose connect is still in flight (they count against the cap). */
+  const pending = new Set();
+
+  const reply = (m) => { try { return send(m); } catch { return undefined; } };
+  const fail = (gatewayId, code, message) => reply(gatewayFail({ gatewayId, code, message }));
+  const active = () => sockets.size + pending.size;
+
+  async function openTcp(m) {
+    const id = m.gateway_id;
+    if (!Number.isInteger(id) || typeof m.host !== 'string' || !Number.isInteger(m.port) || m.port < 1 || m.port > 65535) {
+      return fail(id, GATEWAY_FAIL.POLICY_DENIED, 'malformed OpenTcp');
+    }
+    if (sockets.has(id) || pending.has(id)) return fail(id, GATEWAY_FAIL.POLICY_DENIED, 'gateway_id already in use');
+    if (!destinationAllowed(cfg.allow, m.host, m.port)) {
+      log(`gateway: refused ${m.host}:${m.port} (not on the allow list)`);
+      return fail(id, GATEWAY_FAIL.POLICY_DENIED, 'destination not allowed by the gateway policy');
+    }
+    if (active() >= cfg.maxConnections) return fail(id, GATEWAY_FAIL.QUEUE_FULL, 'too many gateway connections');
+    pending.add(id);
+    let sock;
+    try {
+      const net = await loadNet();
+      if (cfg.socks) sock = await socksConnect(cfg.socks, m.host, m.port, { timeoutMs: cfg.connectTimeoutMs });
+      else {
+        sock = await new Promise((resolve, reject) => {
+          const s = net.connect({ host: m.host, port: m.port });
+          const t = setTimeout(() => { s.destroy(); const e = new Error('connect timed out'); e.code = GATEWAY_FAIL.TIMEOUT; reject(e); }, cfg.connectTimeoutMs);
+          s.once('connect', () => { clearTimeout(t); s.removeAllListeners('error'); resolve(s); });
+          s.once('error', (e) => {
+            clearTimeout(t);
+            const code = e.code === 'ECONNREFUSED' ? GATEWAY_FAIL.CONNECTION_REFUSED : e.code === 'ENOTFOUND' || e.code === 'EAI_AGAIN' ? GATEWAY_FAIL.DNS_FAILED : GATEWAY_FAIL.HOST_UNREACHABLE;
+            const err = new Error(e.code === 'ENOTFOUND' ? 'name not found' : e.message);
+            err.code = code;
+            reject(err);
+          });
+        });
+      }
+    } catch (e) {
+      pending.delete(id);
+      return fail(id, typeof e.code === 'number' ? e.code : GATEWAY_FAIL.HOST_UNREACHABLE, String(e.message).slice(0, 200));
+    }
+    pending.delete(id);
+    sockets.set(id, sock);
+    sock.setNoDelay(true);
+    sock.on('data', (d) => { void reply(gatewayData({ gatewayId: id, data: new Uint8Array(d.buffer, d.byteOffset, d.length) })); });
+    sock.on('error', (e) => log(`gateway ${id}: ${e.message}`));
+    sock.on('close', () => {
+      if (sockets.get(id) === sock) { sockets.delete(id); void reply(gatewayClose({ gatewayId: id })); }
+    });
+    log(`gateway: ${id} -> ${m.host}:${m.port}${cfg.socks ? ' (via SOCKS5)' : ''}`);
+    return reply(gatewayOk({ gatewayId: id }));
+  }
+
+  async function resolveDns(m) {
+    const id = m.gateway_id;
+    if (cfg.socks) return fail(id, GATEWAY_FAIL.POLICY_DENIED, 'names are resolved by the SOCKS proxy; this gateway does not look them up');
+    if (typeof m.name !== 'string' || !m.name) return fail(id, GATEWAY_FAIL.DNS_FAILED, 'malformed ResolveDns');
+    // Only names the client could also connect to: the allow list is about hosts, not ports, here.
+    const hostAllowed = cfg.allow.some((a) => { const p = a.toLowerCase(); return p === '*' || p === m.name.toLowerCase() || p.startsWith(`${m.name.toLowerCase()}:`); });
+    if (!hostAllowed) return fail(id, GATEWAY_FAIL.POLICY_DENIED, 'destination not allowed by the gateway policy');
+    try {
+      const family = m.record_type === 'AAAA' ? 6 : m.record_type === 'A' || m.record_type === undefined ? 4 : 0;
+      if (!family) return fail(id, GATEWAY_FAIL.DNS_FAILED, `unsupported record type ${String(m.record_type).slice(0, 8)}`);
+      const addresses = (await (await loadDns()).lookup(m.name, { family, all: true })).map((a) => a.address);
+      return reply(dnsResult({ gatewayId: id, addresses }));
+    } catch (e) {
+      return fail(id, GATEWAY_FAIL.DNS_FAILED, String(e.code === 'ENOTFOUND' ? 'name not found' : e.message).slice(0, 200));
+    }
+  }
+
+  return {
+    /** @returns {Promise<boolean>} true when the message was a gateway message this session consumed */
+    async handle(m) {
+      switch (m.type) {
+        case MSG.OPEN_TCP: await openTcp(m); return true;
+        case MSG.OPEN_UDP: fail(m.gateway_id, GATEWAY_FAIL.POLICY_DENIED, 'UDP is not supported by this gateway'); return true;
+        case MSG.RESOLVE_DNS: await resolveDns(m); return true;
+        case MSG.GATEWAY_DATA: {
+          const s = sockets.get(m.gateway_id);
+          const d = m.data;
+          if (s && d && d.length <= MAX_DATA_BYTES) s.write(Buffer.from(d.buffer, d.byteOffset, d.length));
+          return true;
+        }
+        case MSG.GATEWAY_CLOSE: {
+          const s = sockets.get(m.gateway_id);
+          if (s) { s.end(); setTimeout(() => s.destroy(), 1000).unref(); } // its 'close' event deletes it and acknowledges
+          return true;
+        }
+        case MSG.LISTEN_REQUEST: reply(listenFail({ listenerId: m.listener_id, reason: 'reverse tunnels are not supported by this gateway' })); return true;
+        case MSG.LISTEN_CLOSE: return true;
+        default: return false;
+      }
+    },
+    close() {
+      for (const s of sockets.values()) s.destroy();
+      sockets.clear();
+    },
+    get size() { return sockets.size; },
+  };
+}

package/src/server/index.d.ts

@@ -339,6 +339,13 @@ export interface WshServerOptions {
    * The WebTransport listener has its own certificate (`webTransport`). Off (plain `ws://`) by default.
    */
   tls?: { cert: string | Uint8Array; key: string | Uint8Array; ca?: string | Uint8Array; passphrase?: string };
+  /**
+   * Answer the gateway opcodes (OpenTcp, ResolveDns, GatewayData, GatewayClose) so a client can open TCP connections and
+   * resolve names from this host. Default deny: a destination must match `allow` (`"*"`, `"host"` any port, `"host:port"`).
+   * `socks` dials through a SOCKS5 proxy (e.g. Tor at `127.0.0.1:9050`) with the name left unresolved; `ResolveDns` is then
+   * refused. UDP and reverse tunnels are answered with a failure. Off by default.
+   */
+  gateway?: { allow: string[]; maxConnections?: number; connectTimeoutMs?: number; socks?: string | { host: string; port: number } };
   /**
    * Handlers for application-defined control messages: one whose `type` is a string (protocol messages are numeric, so
    * there is no collision) from an authenticated connection is handed to `extensions[type]`. A throw is logged.
@@ -395,9 +402,32 @@ export interface WshServerAddress {
   port: number;
 }
 
+/**
+ * An already-accepted WebSocket-like duplex: `send(bytes)`, `close(code?)`, `readyState` (1 = open), and either Node-style
+ * `on(event, fn)` or `addEventListener(event, fn)`. A `ws` socket, a browser/Worker `WebSocket`, or a test double.
+ */
+export interface WshAcceptableSocket {
+  send(data: Uint8Array): void;
+  close(code?: number): void;
+  readonly readyState: number;
+  on?(event: string, listener: (...args: any[]) => void): unknown;
+  addEventListener?(event: string, listener: (ev: any) => void): unknown;
+}
+
+export interface WshAcceptOptions {
+  /** What the embedder knows of the peer; `address` keys the password-failure throttle. */
+  remote?: { address?: string; headers?: Record<string, unknown> };
+}
+
 export interface WshServer {
   /** Start listening. Requires the `ws` package. */
   listen(): Promise<WshServerAddress>;
+  /**
+   * Serve a pre-upgraded transport -- a socket your own HTTP server, Worker or test already accepted -- with this
+   * server's auth, features and sessions, so no listener of wsh's own is needed (`listen()` is optional).
+   * Resolves once the connection is attached; the handle's `close()` drops it. `close()` of the server drops all of them.
+   */
+  accept(socket: WshAcceptableSocket, options?: WshAcceptOptions): Promise<{ close(): void }>;
   /** Drop every connection and stop listening. */
   close(): Promise<void>;
   /** The bound address, or `null` when not listening. */