@johnhenry/wsh 0.28.0 → 0.29.0

package/README.md

@@ -186,6 +186,14 @@ 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`.
 
+### 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.29.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

@@ -83,6 +83,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 {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
@@ -246,7 +247,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/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,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

package/src/server/index.mjs

@@ -60,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 });
@@ -110,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); },
@@ -130,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 {
@@ -155,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();

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 }, {