@johnhenry/wsh 0.27.1 → 0.29.0

package/src/index.d.ts

@@ -616,6 +616,14 @@ export function reverseReject(opts?: {
 export function relayForward(opts?: {
   fromFingerprint?: string;
   inner?: Uint8Array;
+  /** Peer -> relay: the operator this is for, when the peer serves several (wsh #89). */
+  toFingerprint?: string;
+}): WshMessage;
+
+/** Relay -> peer: one operator of a multi-operator peer left (wsh #89). */
+export function reverseClose(opts?: {
+  targetFingerprint?: string;
+  reason?: string;
 }): WshMessage;
 
 /** Message types a relay may forward inside a RelayForward wrapper. */
@@ -851,6 +859,8 @@ export function keyExchange(opts?: {
   sessionId?: string;
   kemPublicKey?: Uint8Array;
   kemCiphertext?: Uint8Array;
+  /** Round 1 only: the sender's Ed25519 signature over the exchange (see the spec's KeyExchange). */
+  signature?: Uint8Array;
 }): WshMessage;
 
 export function encryptedFrame(opts?: {
@@ -1909,6 +1919,27 @@ export interface WshPeerInfo {
   verified: boolean;
 }
 
+/** Host feature: it answers `KeyExchange` and seals/opens `EncryptedFrame`s (a reverse host with `e2e` on). */
+export const E2E_FEATURE: 'e2e';
+/** Host feature: it signs its `KeyExchange` reply, so `initiateE2E(..., { verifyPeer })` can authenticate it. */
+export const E2E_SIGN_FEATURE: 'e2e-sign';
+
+/** The bytes a responder signs in `KeyExchange.signature`. */
+export function keyExchangeTranscript(t: {
+  sessionId: string;
+  /** The initiator's `algorithm` string. */
+  algorithm: string;
+  initiatorKey: Uint8Array;
+  responderKey: Uint8Array;
+}): Uint8Array;
+
+/** Verify a responder's `KeyExchange.signature` against its long-term Ed25519 public key. */
+export function verifyKeyExchangeSignature(
+  peerIdentity: Uint8Array | CryptoKey,
+  signature: Uint8Array | undefined,
+  transcript: Parameters<typeof keyExchangeTranscript>[0],
+): Promise<boolean>;
+
 /** Result from WshClient.initiateE2E(). */
 export interface WshE2EResult {
   /** Non-extractable AES-256-GCM key derived from the exchange. */
@@ -1921,6 +1952,8 @@ export interface WshE2EResult {
    * requested but the peer didn't support it (automatic fallback).
    */
   hybrid: boolean;
+  /** True when `verifyPeer` was given and the peer's signature over the exchange verified. */
+  peerAuthenticated: boolean;
 }
 
 /**
@@ -2005,7 +2038,13 @@ export class WshClient {
    * In reverse mode, the relay bridge forwards messages from the CLI peer
    * to this browser client.
    */
-  onRelayMessage: ((msg: WshMessage) => void) | null;
+  onRelayMessage: ((msg: WshMessage, fromFingerprint?: string) => void) | null;
+
+  /**
+   * Called on a peer that serves several operators when the relay reports that one left (`ReverseClose`,
+   * wsh #89): end that operator's bridge and clean up what belongs to it.
+   */
+  onReverseClose: ((msg: WshMessage) => void) | null;
 
   /**
    * Called when a gateway-subsystem control message arrives (opcodes 0x70-0x7f).
@@ -2169,7 +2208,7 @@ export class WshClient {
   /**
    * Send a control message over the authenticated relay connection.
    */
-  sendRelayControl(msg: WshMessage): Promise<void>;
+  sendRelayControl(msg: WshMessage, opts?: { to?: string }): Promise<void>;
 
   /**
    * Send a raw control message on the authenticated connection.
@@ -2202,7 +2241,15 @@ export class WshClient {
    * fallback to classical if the peer doesn't support it). Experimental
    * -- the derived key is not yet wired to any actual encryption.
    */
-  initiateE2E(sessionId: string, algorithm?: 'X25519' | 'X25519+ML-KEM-768', timeout?: number): Promise<WshE2EResult>;
+  initiateE2E(
+    sessionId: string,
+    algorithm?: 'X25519' | 'X25519+ML-KEM-768',
+    timeout?: number,
+    opts?: {
+      /** The peer's long-term Ed25519 public key; the exchange is refused (`E2E_PEER_UNAUTHENTICATED`) unless it signed its half. */
+      verifyPeer?: Uint8Array | CryptoKey;
+    },
+  ): Promise<WshE2EResult>;
 
   /**
    * Mark a peer fingerprint as an accepted reverse-connect bridge partner.

package/src/index.mjs

@@ -17,7 +17,7 @@ export {
   presence, controlChanged, metrics,
   mcpDiscover, mcpTools, mcpCall, mcpResult,
   reverseRegister, reverseList, reversePeers, reverseConnect, reverseAccept, reverseReject,
-  relayForward, RELAY_FORWARDABLE, isRelayForwardable,
+  relayForward, reverseClose, RELAY_FORWARDABLE, isRelayForwardable,
   openTcp, openUdp, resolveDns, gatewayOk, gatewayFail, gatewayClose,
   inboundOpen, inboundAccept, inboundReject, dnsResult,
   listenRequest, listenOk, listenFail, listenClose, gatewayData,
@@ -76,6 +76,9 @@ export { WshSession } from './session.mjs';
 export { WshVirtualSessionBackend, normalizeSessionData } from './virtual-session.mjs';
 export { WshClient, MCP_CALL_ID_FEATURE, STREAM_ANNOUNCE_FEATURE } from './client.mjs';
 
+// End-to-end key exchange (responder side, feature names, signed transcript) -- wsh #90
+export { E2E_FEATURE, E2E_SIGN_FEATURE, keyExchangeTranscript, verifyKeyExchangeSignature } from './e2e-exchange.mjs';
+
 // Key storage
 export { WshKeyStore } from './keystore.mjs';
 

package/src/messages.gen.mjs

@@ -63,6 +63,7 @@ export const MSG = Object.freeze({
   REVERSE_ACCEPT:    0x54,
   REVERSE_REJECT:    0x55,
   RELAY_FORWARD:     0x56,
+  REVERSE_CLOSE:     0x57,
 
   // Session
   SESSION_LIST:      0x5f,
@@ -510,12 +511,16 @@ export function reverseReject({ targetFingerprint, username, reason } = {}) {
   };
 }
 
-export function relayForward({ fromFingerprint, inner } = {}) {
-  return {
-    type: MSG.RELAY_FORWARD,
-    from_fingerprint: fromFingerprint,
-    inner,
-  };
+export function relayForward({ fromFingerprint, inner, toFingerprint } = {}) {
+  const msg = { type: MSG.RELAY_FORWARD, from_fingerprint: fromFingerprint, inner };
+  if (toFingerprint !== undefined) msg.to_fingerprint = toFingerprint;
+  return msg;
+}
+
+export function reverseClose({ targetFingerprint, reason } = {}) {
+  const msg = { type: MSG.REVERSE_CLOSE, target_fingerprint: targetFingerprint };
+  if (reason !== undefined) msg.reason = reason;
+  return msg;
 }
 
 export function sessionList({ sessions } = {}) {
@@ -762,11 +767,12 @@ export function copilotDetach({ sessionId, reason } = {}) {
   return msg;
 }
 
-export function keyExchange({ algorithm, publicKey, sessionId, kemPublicKey, kemCiphertext } = {}) {
+export function keyExchange({ algorithm, publicKey, sessionId, kemPublicKey, kemCiphertext, signature } = {}) {
   const msg = { type: MSG.KEY_EXCHANGE, algorithm, session_id: sessionId };
   if (publicKey !== undefined) msg.public_key = publicKey;
   if (kemPublicKey !== undefined) msg.kem_public_key = kemPublicKey;
   if (kemCiphertext !== undefined) msg.kem_ciphertext = kemCiphertext;
+  if (signature !== undefined) msg.signature = signature;
   return msg;
 }
 

package/src/server/connection.mjs

@@ -18,7 +18,7 @@ import { QMuxConnection } from '../qmux-connection.mjs';
 import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
   MSG, serverHello, challenge, authOk, authFail, openOk, openFail, sessionData,
-  exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk, mcpTools, mcpResult,
+  exit as exitMsg, close as closeMsg, encryptedFrame as encryptedFrameMsg, pong, fileResult, fileChunk, mcpTools, mcpResult,
   presence as presenceMsg, error as errorMsg, sessionList, detachOk, detachFail, reversePeers, reverseReject,
 } from '../messages.gen.mjs';
 import {
@@ -28,6 +28,9 @@ import { FILE_CHUNK_BYTES } from './fs.mjs';
 import { MAX_ATTACHMENTS } from './sessions.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 { HOST_KEY_PREFIX, HOST_KEY_SIG_PREFIX, findClientNonce, hostKeyProofMessage, toHex } from '../host-key.mjs';
 
 export const STREAM_ANNOUNCE = 'stream-announce';
@@ -42,6 +45,15 @@ export function hostFeatures(cfg, { dataStreams = true } = {}) {
   const features = dataStreams ? [STREAM_ANNOUNCE] : [];
   if (cfg.mcp) features.push(MCP_CALL_ID_FEATURE);
   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.
+  // A relay carries a signed KeyExchange untouched, and (when configured) several operators per peer: peers read
+  // these from its ServerHello before relying on either, since an older relay would drop the connection on them.
+  if (cfg.relay) {
+    features.push(E2E_SIGN_FEATURE);
+    if (cfg.relay.maxOperatorsPerPeer > 1) features.push(MULTI_OPERATOR_FEATURE);
+  }
+  if (cfg.e2e && !dataStreams) features.push(E2E_FEATURE, ...(cfg.e2e.signKey ? [E2E_SIGN_FEATURE] : []));
   if (cfg.rpc && dataStreams && cfg.rpc.protocols.size) {
     features.push(RPC_FEATURE, ...[...cfg.rpc.protocols.keys()].map(rpcProtocolFeature), RPC_MAX_MESSAGE_PREFIX + cfg.rpc.maxMessageBytes);
   }
@@ -70,6 +82,8 @@ const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
  * @param {object | null} cfg.hostKey - from loadHostKey
  * @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 {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
@@ -86,8 +100,9 @@ export function createConnectionFactory(cfg) {
    *    for a transport that already frames messages itself (a relay bridge, WebTransport). `authenticated`
    *    (`{ username, fingerprint }`) skips the handshake for a peer something else has already authenticated;
    *    `dataStreams: false` means there are no client-opened streams to bind, so exec output rides SessionData.
+   *    `e2e` overrides `cfg.e2e` for this connection.
    */
-  return function attach({ send: sendBytes, sendMessage = null, remote = {}, authenticated = null, dataStreams = true, closeTransport = null }) {
+  return function attach({ send: sendBytes, sendMessage = null, remote = {}, authenticated = null, dataStreams = true, closeTransport = null, e2e: e2eOverride }) {
     const cid = ++counter;
     const log = (m) => cfg.log(`[conn ${cid}] ${m}`);
     const state = {
@@ -111,7 +126,39 @@ export function createConnectionFactory(cfg) {
 
     const qmux = sendMessage ? null : new QMuxConnection({ isClient: false, send: (b) => { if (!state.closed) sendBytes(b); } });
 
+    // ── End-to-end encryption (#90) ──────────────────────────────────
+    // An operator that sent KeyExchange for one of this connection's sessions gets that session's output sealed
+    // into EncryptedFrames and its input opened from them; plaintext input for it is ignored from then on (a relay
+    // must not be able to inject stdin around the encryption).
+    /** channel id -> the session id its OpenOk named (the AAD of its frames). */
+    const sessionOfChannel = new Map();
+    /** session id -> { key, sendCounter, recvCounter } for sessions with E2E on. */
+    const e2eSessions = new Map();
+    const MAX_E2E_SESSIONS = 64;
+    const e2eConfig = e2eOverride === undefined ? cfg.e2e : e2eOverride;
+    const responder = e2eConfig && !dataStreams ? new E2EResponder({ signKey: e2eConfig.signKey ?? null, hybrid: e2eConfig.hybrid !== false }) : null;
+    /** Outgoing messages in order, once E2E is on (sealing is async; order on the wire must not change). */
+    let outChain = Promise.resolve();
+    const e2eFor = (channelId) => e2eSessions.get(sessionOfChannel.get(channelId));
+
     const send = (msg) => {
+      if (state.closed) return Promise.resolve();
+      if (msg.type === MSG.OPEN_OK && typeof msg.session_id === 'string') sessionOfChannel.set(msg.channel_id, msg.session_id);
+      if (e2eSessions.size === 0) return deliver(msg);
+      // E2E is on for something: everything goes through one chain, so a sealed frame cannot be overtaken
+      // by (or overtake) the Exit that follows it.
+      const done = outChain.then(async () => {
+        const st = msg.type === MSG.SESSION_DATA ? e2eFor(msg.channel_id) : undefined;
+        if (!st) return deliver(msg);
+        const sessionId = sessionOfChannel.get(msg.channel_id);
+        const { nonce, ciphertext } = await sealFrame(st.key, sessionId, ROLE_TAGS.responder, st.sendCounter++, msg.data);
+        return deliver(encryptedFrameMsg({ channelId: msg.channel_id, nonce, ciphertext, sessionId }));
+      });
+      outChain = done.catch(() => {});
+      return done.catch(() => {});
+    };
+
+    const deliver = (msg) => {
       if (state.closed) return Promise.resolve();
       if (sendMessage) {
         try { return Promise.resolve(sendMessage(msg)).catch(() => {}); } catch { return Promise.resolve(); }
@@ -129,6 +176,8 @@ export function createConnectionFactory(cfg) {
       // everything else dies with it.
       for (const ch of [...channels.values()]) (ch.detach ?? ch.kill)?.call(ch);
       channels.clear();
+      responder?.close();
+      e2eSessions.clear();
       for (const c of mcpCalls) c.abort(new Error('connection closed'));
       mcpCalls.clear();
       for (const w of fileWrites.values()) clearTimeout(w.timer);
@@ -179,7 +228,12 @@ export function createConnectionFactory(cfg) {
       switch (m.type) {
         case MSG.PING: return send(pong({ id: m.id }));
         case MSG.OPEN: return handleOpen(m);
-        case MSG.SESSION_DATA: channels.get(m.channel_id)?.input?.(m.data); return;
+        case MSG.SESSION_DATA:
+          if (e2eFor(m.channel_id)) { log(`ignored plaintext SessionData on E2E channel ${m.channel_id}`); return; }
+          channels.get(m.channel_id)?.input?.(m.data);
+          return;
+        case MSG.KEY_EXCHANGE: return handleKeyExchange(m);
+        case MSG.ENCRYPTED_FRAME: return handleEncryptedFrame(m);
         case MSG.RESIZE: channels.get(m.channel_id)?.resize?.(m.cols, m.rows); return;
         case MSG.SIGNAL: channels.get(m.channel_id)?.signal?.(String(m.signal ?? '')); return;
         case MSG.CLOSE: { const ch = channels.get(m.channel_id); if (ch) { ch.kill?.(); } return; }
@@ -193,8 +247,44 @@ 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)}`);
+      }
+    }
+
+    async function handleKeyExchange(m) {
+      if (!responder) { log('ignored KeyExchange (end-to-end encryption is not enabled here)'); return; }
+      // Only for a session this connection actually has: the id is the AAD of every frame, and it bounds the state kept.
+      const known = typeof m.session_id === 'string' && [...sessionOfChannel.values()].includes(m.session_id);
+      if (!known) { log('ignored KeyExchange for a session this connection does not have'); return; }
+      if (!e2eSessions.has(m.session_id) && e2eSessions.size >= MAX_E2E_SESSIONS) { log('ignored KeyExchange (too many encrypted sessions)'); return; }
+      let result;
+      try { result = await responder.respond(m, send); } catch (e) { log(`KeyExchange refused: ${e.message}`); return; }
+      // Sealing starts after the reply is on its way, so the operator never gets a frame before it has the key.
+      if (result.key) {
+        e2eSessions.set(result.sessionId, { key: result.key, sendCounter: 0, recvCounter: 0 });
+        log(`end-to-end encryption on for session ${result.sessionId.slice(0, 8)}${result.hybrid ? ' (hybrid)' : ''}`);
+      }
+    }
+
+    async function handleEncryptedFrame(m) {
+      const st = e2eSessions.get(m.session_id);
+      // The frame must name the session its channel belongs to, or it could be spliced onto another channel.
+      if (!st || sessionOfChannel.get(m.channel_id) !== m.session_id) { log('dropped an EncryptedFrame for a session without E2E'); return; }
+      let plain;
+      try {
+        plain = await openFrame(st.key, m.session_id, st.recvCounter, { nonce: m.nonce, ciphertext: m.ciphertext, expectedRoleTag: ROLE_TAGS.initiator });
+      } catch (e) {
+        // Garbage (a replay, a tampered or foreign frame) neither reaches the process nor consumes a counter.
+        log(`dropped an EncryptedFrame: ${e.message}`);
+        return;
       }
+      st.recvCounter += 1;
+      channels.get(m.channel_id)?.input?.(plain);
     }
 
     async function refuse(reason) {

package/src/server/index.d.ts

@@ -196,8 +196,25 @@ 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;
+  /**
+   * Operators bridged to one peer at once (default 1). Above 1, a peer is held to one operator unless it stated
+   * `relay-multi-operator` in its `ReverseAccept.features` (it then addresses replies with
+   * `RelayForward.to_fingerprint` and is sent a `ReverseClose` when one operator leaves instead of being closed).
+   */
+  maxOperatorsPerPeer?: number;
   /** How long a `ReverseConnect` waits for its peer to answer before the operator is rejected (default 8000). */
   connectTimeoutMs?: number;
 }
@@ -317,6 +334,16 @@ 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 };
+  /**
+   * 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
@@ -421,6 +448,23 @@ export interface WshReverseHostOptions {
   /** Extra options for the relay connection (`expectHostKey`, `knownHosts`, `trustOnFirstUse`, ...). */
   connect?: Record<string, unknown>;
   peerType?: string;
+  /**
+   * Operators served at once (default 1). Above 1 the host states `relay-multi-operator`, addresses each reply
+   * to its operator and handles `ReverseClose`; each operator gets its own connection state and is passed through
+   * `accept` on its own identity. Needs `reportFeatures` and a relay with `maxOperatorsPerPeer` above 1; any other
+   * relay serves it one operator, as before.
+   */
+  maxOperators?: number;
+  /** State this host's features in `ReverseAccept.features` (default true). */
+  reportFeatures?: boolean;
+  /**
+   * End-to-end encryption for the bridged operator (default on; `false` turns it off). The host answers an
+   * operator's `KeyExchange` for a session it opened, seals that session's output into `EncryptedFrame`s and opens its
+   * input from them. `sign`: sign the reply with `keyPair` so the operator can authenticate this host
+   * (`initiateE2E(..., { verifyPeer })`); `'auto'` (default) signs when the relay's `ServerHello` carries `e2e-sign`.
+   * `hybrid` (default true) offers X25519+ML-KEM-768 when asked and available.
+   */
+  e2e?: false | { sign?: boolean | 'auto'; hybrid?: boolean };
   onLog?: (line: string) => void;
 }
 
@@ -433,6 +477,8 @@ export interface WshReverseHost {
   readonly fingerprint: string | null;
   /** Is the relay connection up right now? */
   readonly connected: boolean;
+  /** Fingerprints of the operators bridged right now. */
+  readonly operators: string[];
 }
 
 /**

package/src/server/index.mjs

@@ -39,10 +39,12 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  *   SHA-256 through `webTransport()` / `certificateHashes()` for the client's `serverCertificateHashes`, and rotates it
  *   before it expires (`rotateCertificate()`). Needs the optional peers
  *   `@fails-components/webtransport` and `@fails-components/webtransport-transport-http3-quiche`. Off unless given.
- * @param {{ canRegister?: Function, canConnect?: Function, maxPeers?: number, connectTimeoutMs?: number }} [options.relay]
+ * @param {{ canRegister?: Function, canConnect?: Function, maxPeers?: number, maxOperatorsPerPeer?: number, connectTimeoutMs?: number }} [options.relay]
  *   Act as a relay: peers register (`ReverseRegister`, a signed record), operators list and connect to them
  *   (`ReverseList` / `ReverseConnect`) and traffic is carried between them as `RelayForward`. Default deny:
  *   `canRegister(who, record)` and `canConnect(from, to)` must both be given and return true. See `createReverseHost`.
+ *   One operator per peer unless `maxOperatorsPerPeer` is raised -- and then only for peers that state
+ *   `relay-multi-operator` (`createReverseHost({ maxOperators })`).
  * @param {true | { detachTtlMs?: number, maxDetached?: number, ringBytes?: number, sessionSecret?: string | Uint8Array }} [options.sessions]
  *   Keep pty/exec sessions alive across disconnects so a client can `resumeSession()` / `attachSession()`
  *   them: a per-server registry, a ring buffer of the newest `ringBytes` (default 1 MiB) of output, and
@@ -58,14 +60,22 @@ 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 {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, 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 });
@@ -76,6 +86,9 @@ export function createWshServer({
     key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
     failureDelayMs: rl.failureDelayMs ?? 250,
   };
+  if (relay && relay.maxOperatorsPerPeer !== undefined && (!Number.isSafeInteger(relay.maxOperatorsPerPeer) || relay.maxOperatorsPerPeer < 1)) {
+    throw new TypeError('createWshServer: relay.maxOperatorsPerPeer must be a positive integer');
+  }
   const rpcHost = rpc ? createRpcHost(rpc, { files, maxMessageBytes: rpcMaxMessageBytes, maxInflight: rpcMaxInflight }) : null;
   let host_ = null;
   let registry = null;
@@ -105,12 +118,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, 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); },
@@ -125,10 +145,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 {
@@ -150,6 +175,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();