@johnhenry/wsh 0.28.0 → 0.30.0

package/README.md

@@ -186,6 +186,21 @@ restricted host with no shell. `fs.root` confines every path: `..`, absolute
 paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
+### Gateway (TCP and DNS egress from the host)
+
+`gateway: { allow: ['broker.lan:1883'], socks: '127.0.0.1:9050' }` makes the Node server answer the gateway opcodes, so a
+client (a browser tab via netway's `GatewayBackend`) can open TCP connections and resolve names from the host. Default
+deny; `allow` takes `"*"`, `"host"` or `"host:port"`. `socks` routes every dial through a SOCKS5 proxy (Tor) with the name
+unresolved. UDP and reverse tunnels are refused.
+
+### TLS (`wss://`) and host extensions
+
+`tls: { cert, key }` (PEM, the options of `https.createServer`) serves the WebSocket listener over TLS on the same
+port. `extensions: { [type]: (msg, { username, fingerprint, send }) => void }` handles application-defined control
+messages whose `type` is a string, from authenticated connections only. On a relay,
+`relay: { onUnreachable(from, targetFingerprint, request) }` is told when an operator asked for a peer that is not
+registered (the operator still gets `no such peer`), so the host can reach that peer another way, such as a Web Push.
+
 ### WebTransport listener
 
 The client's ladder prefers WebTransport (`https://`) and falls back to `wss://`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",

package/src/server/connection.mjs

@@ -31,6 +31,7 @@ import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } f
 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 +45,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.
@@ -83,6 +85,8 @@ 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
  * @param {{ limiter: object, key: Function, failureDelayMs: number } | null} cfg.rateLimit - password throttle
@@ -123,6 +127,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) ──────────────────────────────────
@@ -176,6 +182,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();
@@ -224,6 +231,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);
@@ -246,7 +254,12 @@ export function createConnectionFactory(cfg) {
         // Not awaited: the handler chain is serial, and a slow tool must not hold up
         // the next call (or a Close) behind it.
         case MSG.MCP_CALL: handleMcpCall(m); return;
-        default: log(`ignored message type 0x${m.type.toString(16)}`);
+        default:
+          if (typeof m.type === 'string' && Object.hasOwn(cfg.extensions ?? {}, m.type) && typeof cfg.extensions[m.type] === 'function') {
+            try { await cfg.extensions[m.type](m, { username: state.username, fingerprint: state.fingerprint, send }); } catch (e) { log(`extension "${m.type}" threw: ${e.message}`); }
+            return;
+          }
+          log(`ignored message type ${typeof m.type === 'number' ? `0x${m.type.toString(16)}` : JSON.stringify(String(m.type)).slice(0, 80)}`);
       }
     }
 

package/src/server/gateway.mjs

@@ -0,0 +1,241 @@
+/**
+ * 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 net from 'node:net';
+import dns from 'node:dns/promises';
+import { MSG, gatewayOk, gatewayFail, gatewayClose, gatewayData, dnsResult, listenFail } from '../messages.gen.mjs';
+
+/** 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 function socksConnect(proxy, host, port, { timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS } = {}) {
+  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 {
+      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 dns.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

@@ -196,6 +196,17 @@ export interface WshServerRelayOptions {
     from: { username: string; fingerprint: string },
     to: WshRelayPeer,
   ) => boolean | Promise<boolean>;
+  /**
+   * Called (not awaited; a throw is logged) when an authenticated operator asks to connect to a peer that is not
+   * registered, with the operator, the fingerprint it asked for and the `ReverseConnect`'s claimed `username`. It
+   * never changes the answer (the operator is still told `no such peer`); it lets the host reach the peer another
+   * way, e.g. a Web Push notification.
+   */
+  onUnreachable?: (
+    from: { username: string; fingerprint: string },
+    targetFingerprint: string,
+    request: { username?: string },
+  ) => unknown;
   /** Registered peers at once (default 1024). */
   maxPeers?: number;
   /**
@@ -323,6 +334,23 @@ export interface WshServerOptions {
    * Default deny -- give both `canRegister` and `canConnect`. Off by default.
    */
   relay?: WshServerRelayOptions;
+  /**
+   * Serve the WebSocket listener over TLS (`wss://`) on the same port; these are the options of `https.createServer`.
+   * 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.
+   */
+  extensions?: Record<string, (msg: Record<string, unknown>, ctx: { username: string; fingerprint: string | null; send: (msg: object) => unknown }) => unknown>;
   /**
    * Also listen for WebTransport (HTTP/3 over UDP) clients -- the same auth, exec, pty, fs, mcp, sessions and relay as the
    * WebSocket listener, with real independent streams. Needs the optional peers `@fails-components/webtransport` and

package/src/server/index.mjs

@@ -15,6 +15,7 @@ import { SessionRegistry } from './sessions.mjs';
 import { RelayHub } from './relay.mjs';
 import { startWebTransport } from './webtransport.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
+import { normalizeGateway } from './gateway.mjs';
 import { createRpcHost, mcpServerAdapter } from './rpc.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE, mcpServerAdapter };
@@ -60,14 +61,26 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  *   identity, advertised (with proof of possession) so clients can pin it. See `src/host-key.mjs`.
  * @param {object} [options.auth.rateLimit] - Password-failure throttle: `{ maxFailures=5, windowMs=60000,
  *   lockoutMs=60000, failureDelayMs=250, key(info) }` (`key` defaults to the peer address).
+ * @param {{ cert: string | Buffer, key: string | Buffer, ca?: string | Buffer, passphrase?: string }} [options.tls] - Serve the
+ *   WebSocket listener over TLS (`wss://`) on the same port: the options of `https.createServer`. Off (plain `ws://`) unless given.
+ *   The WebTransport listener has its own certificate (`webTransport.cert` / `selfSigned`).
+ * @param {Record<string, (msg: object, ctx: { username: string, fingerprint: string | null, send: Function }) => unknown>} [options.extensions]
+ *   Handlers for application-defined messages: a control message whose `type` is a *string* (every protocol message
+ *   has a numeric type, so these cannot collide) from an authenticated connection is passed to `extensions[type]`.
+ *   A handler that throws is logged and ignored. Off unless given.
+ * @param {{ allow: string[], maxConnections?: number, connectTimeoutMs?: number, socks?: string | { host: string, port: number } }} [options.gateway]
+ *   Answer the gateway opcodes (OpenTcp, ResolveDns, GatewayData/Close): the client opens TCP connections and resolves
+ *   names from this host. Default deny: a destination must match `allow` (`"*"`, `"host"`, `"host:port"`). `socks` dials
+ *   through a SOCKS5 proxy (Tor) with the name unresolved. UDP and reverse tunnels are refused. Off unless given. See `gateway.mjs`.
  * @param {number} [options.bindTimeoutMs=3000]
  * @param {(line: string) => void} [options.onLog]
  * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
-  host = '127.0.0.1', port = 0, auth, exec, pty, fs, hostKey, mcp, rpc, rpcMaxMessageBytes, rpcMaxInflight, sessions, sessionSecret, relay, webTransport, bindTimeoutMs = 3000, onLog = () => {},
+  host = '127.0.0.1', port = 0, tls, auth, exec, pty, fs, hostKey, mcp, rpc, rpcMaxMessageBytes, rpcMaxInflight, sessions, sessionSecret, relay, extensions, gateway, webTransport, bindTimeoutMs = 3000, onLog = () => {},
 } = {}) {
   let wss = null;
+  let httpsServer = null;
   let bound = null;
 
   const { execRunner, execOptions, pty: ptyConfig, files, mcp: mcpHost } = buildBackends({ exec, pty, fs, mcp });
@@ -86,6 +99,7 @@ export function createWshServer({
   let registry = null;
   let hub = null;
   let wt = null;
+  const gatewayCfg = gateway === undefined ? null : normalizeGateway(gateway);
   const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
   return {
@@ -110,12 +124,19 @@ export function createWshServer({
         });
       }
       if (relay) hub = new RelayHub({ ...relay, log: onLog });
+      if (extensions !== undefined && (extensions === null || typeof extensions !== 'object')) throw new TypeError('createWshServer: extensions must be an object of handlers');
       const attach = createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
-        methods, hostKey: host_, rateLimit, mcp: mcpHost, rpc: rpcHost, sessions: registry, relay: hub,
+        methods, hostKey: host_, rateLimit, extensions, mcp: mcpHost, rpc: rpcHost, gateway: gatewayCfg, sessions: registry, relay: hub,
       });
 
-      wss = new WebSocketServer({ host, port });
+      if (tls) {
+        const { createServer } = await import('node:https');
+        httpsServer = createServer(tls);
+        wss = new WebSocketServer({ server: httpsServer });
+      } else {
+        wss = new WebSocketServer({ host, port });
+      }
       wss.on('connection', (ws, req) => {
         const conn = attach({
           send: (b) => { if (ws.readyState === 1) ws.send(b); },
@@ -130,10 +151,15 @@ export function createWshServer({
         ws.on('error', () => {});
       });
       await new Promise((resolve, reject) => {
-        wss.once('listening', resolve);
-        wss.once('error', reject);
+        if (httpsServer) {
+          httpsServer.once('error', reject);
+          httpsServer.listen(port, host, () => { httpsServer.off('error', reject); resolve(); });
+        } else {
+          wss.once('listening', resolve);
+          wss.once('error', reject);
+        }
       });
-      const a = wss.address();
+      const a = (httpsServer ?? wss).address();
       bound = { address: a.address, port: a.port };
       if (webTransport) {
         try {
@@ -155,6 +181,7 @@ export function createWshServer({
       await wt?.close();
       wt = null;
       await new Promise((resolve) => server.close(resolve));
+      if (httpsServer) { const h = httpsServer; httpsServer = null; await new Promise((resolve) => h.close(resolve)); }
       registry?.closeAll();
       registry = null;
       hub?.closeAll();

package/src/server/relay.mjs

@@ -77,8 +77,8 @@ export class RelayHub {
   /** fingerprint -> the highest record seq ever accepted (survives disconnects, bounded). */
   #lastSeq = new Map();
 
-  constructor({ canRegister, canConnect, maxPeers = DEFAULT_MAX_PEERS, maxOperatorsPerPeer = 1, connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS, log = () => {} } = {}) {
-    for (const [name, fn] of [['canRegister', canRegister], ['canConnect', canConnect]]) {
+  constructor({ canRegister, canConnect, maxPeers = DEFAULT_MAX_PEERS, maxOperatorsPerPeer = 1, connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS, onUnreachable, log = () => {} } = {}) {
+    for (const [name, fn] of [['canRegister', canRegister], ['canConnect', canConnect], ['onUnreachable', onUnreachable]]) {
       if (fn !== undefined && typeof fn !== 'function') throw new TypeError(`createWshServer: relay.${name} must be a function`);
     }
     if (!Number.isSafeInteger(maxOperatorsPerPeer) || maxOperatorsPerPeer < 1) throw new TypeError('createWshServer: relay.maxOperatorsPerPeer must be a positive integer');
@@ -87,6 +87,7 @@ export class RelayHub {
     this.canConnect = canConnect ?? (() => false);
     this.maxPeers = maxPeers;
     this.connectTimeoutMs = connectTimeoutMs;
+    this.onUnreachable = onUnreachable;
     this.log = log;
   }
 
@@ -209,6 +210,14 @@ export class RelayHub {
   async connect(operator, msg) {
     const reject = (reason) => operator.send(reverseReject({ targetFingerprint: String(msg.target_fingerprint ?? ''), username: msg.username ?? '', reason }));
     const target = this.#find(msg.target_fingerprint);
+    if (!target && this.onUnreachable) {
+      // Tell the host application nobody is registered under that name (it may know another way to reach them, e.g. a
+      // push notification). Fire and forget: it never changes the answer, and a throw is logged, not propagated.
+      try {
+        Promise.resolve(this.onUnreachable({ username: operator.username, fingerprint: operator.fingerprint }, String(msg.target_fingerprint ?? ''), { username: msg.username }))
+          .catch((e) => this.log(`relay onUnreachable threw: ${e.message}`));
+      } catch (e) { this.log(`relay onUnreachable threw: ${e.message}`); }
+    }
     // Unknown, unreachable-by-policy and self look the same to the caller.
     if (!target || target.handle === operator
       || !(await this.#allowed(this.canConnect, { username: operator.username, fingerprint: operator.fingerprint }, {