@johnhenry/wsh 0.17.1 → 0.18.0

package/README.md

@@ -16,7 +16,7 @@ Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.m
 
 Browser-native remote command execution over WebTransport/WebSocket with Ed25519 authentication.
 
-wsh is a pure-JS client library that connects browsers to remote shells. It implements its own binary protocol — CBOR messages over QMux-multiplexed WebSocket or native WebTransport streams — with Ed25519 challenge-response auth, session management, and MCP tool bridging.
+wsh is a pure-JS client library (with an optional Node server at `@johnhenry/wsh/server`) that connects browsers to remote shells. It implements its own binary protocol — CBOR messages over QMux-multiplexed WebSocket or native WebTransport streams — with Ed25519 challenge-response auth, session management, and MCP tool bridging.
 
 ## Contents
 
@@ -25,6 +25,7 @@ wsh is a pure-JS client library that connects browsers to remote shells. It impl
 - [Wire Protocol: QMux](#wire-protocol-qmux)
 - [Quick Start](#quick-start)
 - [One-Shot Command Execution](#one-shot-command-execution)
+- [Node Server](#node-server)
 - [Attach and Resume](#attach-and-resume)
 - [Pinning a Self-Signed Certificate](#pinning-a-self-signed-certificate)
 - [API Overview](#api-overview)
@@ -145,6 +146,48 @@ console.log(new TextDecoder().decode(stdout));
 console.log('Exit code:', exitCode);
 ```
 
+`exec` and `openSession({ type: 'exec' })` need no extra step to receive
+output. Older hosts only discover the client-opened data stream once a byte
+arrives on it, so against a host that does not advertise `stream-announce`
+the client writes a one-byte primer for you (a host that strips it, as those
+hosts do). Pass `primer: false` to never send it.
+
+## Node Server
+
+`@johnhenry/wsh/server` is a Node host for the same protocol, over WebSocket
+(QMux). It is a separate subpath -- the package root stays browser-safe and
+never imports it -- and needs the optional peer dependency `ws`
+(`npm install ws`).
+
+```js
+import { createWshServer } from '@johnhenry/wsh/server';
+import { readFileSync } from 'node:fs';
+
+const server = createWshServer({
+  host: '127.0.0.1',
+  port: 4422,                                          // 0 = pick a free port
+  auth: { authorizedKeys: readFileSync('authorized_keys', 'utf8') },  // ssh-ed25519 lines
+  exec: true,                                          // opt in: run commands via /bin/sh
+  fs: { root: '/srv/share', readOnly: false },         // opt in: list/stat/read/mkdir/remove/upload/download
+  // pty: { spawn: nodePty.spawn },                    // opt in: bring your own node-pty
+});
+const { port } = await server.listen();                // later: server.address(), await server.close()
+```
+
+Everything that touches the machine -- `exec`, `pty`, `fs` -- is **off unless
+you pass it**, and with no `auth` every connection is refused. `auth` is
+`{ authorizedKeys, authorize }` (a key must be on the list and pass
+`authorize({ username, fingerprint, publicKey })` when both are given) or
+just an `authorize` function. `exec` can also be `{ cwd, env, shell,
+timeoutMs, clientEnv }` or a custom `run(command, io)` for a restricted host
+with no shell. `fs.root` confines every path: `..`, absolute paths and
+symlinks pointing out of it are refused. The server advertises
+`stream-announce`, so a current client writes no primer byte; a lone leading
+`0x00` from a client that primes anyway is dropped rather than reaching stdin.
+
+Not implemented: WebTransport, relay/reverse mode, attach/resume, MCP,
+password auth.
+
 ## Attach and Resume
 
 Opening a PTY/exec session returns a session-scoped credential alongside the channel:
@@ -249,6 +292,7 @@ so options the platform gains later need no change here.
 | `SessionRecorder` | Record PTY I/O with timestamps (own schema, not asciicast v2) |
 | `SessionPlayer` | Replay recordings with original timing |
 | `generateKeyPair()` | Create Ed25519 key pair via Web Crypto |
+| `sign(privateKey, message)` / `verify(publicKey, signature, message)` | Raw Ed25519 sign / verify. This positional order (WebCrypto's) is the one canonical form across wsh, raijin and browsermesh |
 | `signChallenge()` | Build transcript + sign for auth handshake |
 | `signPeerRecord()` / `verifyPeerRecord()` | Sign / verify reverse-mode peer records |
 | `fingerprint()` | SHA-256 hex fingerprint of a public key |

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.17.1",
-  "description": "Web Shell — browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
+  "version": "0.18.0",
+  "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.mjs"
+    },
+    "./server": {
+      "types": "./src/server/index.d.ts",
+      "import": "./src/server/index.mjs"
     }
   },
   "types": "./src/index.d.ts",
@@ -19,6 +23,14 @@
   "optionalDependencies": {
     "@noble/post-quantum": "^0.7.0"
   },
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@fails-components/webtransport": "^1.6.4",
     "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",

package/src/client.mjs

@@ -63,6 +63,13 @@ const DEFAULT_OPEN_TIMEOUT   = 10_000;  // ms
  */
 export const MCP_CALL_ID_FEATURE = 'mcp-call-id';
 
+/**
+ * ServerHello feature: the host discovers a client-opened exec data stream
+ * on its own (the transport announces it), so the client must NOT write the
+ * one-byte "primer" -- against such a host it would reach the process's stdin.
+ */
+export const STREAM_ANNOUNCE_FEATURE = 'stream-announce';
+
 /**
  * Reject a missing argument that maps to a `required: true` wire field.
  *
@@ -587,9 +594,14 @@ export class WshClient {
    * @param {number} [opts.rows=24] - Initial terminal rows
    * @param {object} [opts.env] - Environment variables
    * @param {number} [opts.timeout] - Timeout in ms
+   * @param {boolean} [opts.primer=true] - For stream-mode `exec` sessions: write
+   *   the one-byte "primer" some hosts need to discover the client-opened data
+   *   stream (without it they never bind the stream and drop all output).
+   *   Skipped automatically against a host advertising `stream-announce`; pass
+   *   `false` to never send it (e.g. a host that forwards stdin verbatim).
    * @returns {Promise<WshSession>}
    */
-  async openSession({ type = 'pty', command, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async openSession({ type = 'pty', command, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT, primer = true } = {}) {
     this.#assertAuthenticated('openSession');
     const requestedChannelId = this._nextChannelId();
 
@@ -605,6 +617,7 @@ export class WshClient {
       const entry = {
         mode: 'session',
         kind: type,
+        primer,
         requestedChannelId,
         resolve,
         reject,
@@ -842,9 +855,10 @@ export class WshClient {
    * @param {CryptoKeyPair} [opts.keyPair]
    * @param {string} [opts.password]
    * @param {number} [opts.timeout=60000] - Overall timeout in ms
+   * @param {boolean} [opts.primer=true] - See `openSession({ primer })`
    * @returns {Promise<{stdout: Uint8Array, exitCode: number}>}
    */
-  static async exec(url, command, { username, keyPair, password, timeout = DEFAULT_EXEC_TIMEOUT } = {}) {
+  static async exec(url, command, { username, keyPair, password, timeout = DEFAULT_EXEC_TIMEOUT, primer = true } = {}) {
     const client = new WshClient();
     const chunks = [];
     let exitCode = -1;
@@ -852,7 +866,7 @@ export class WshClient {
     try {
       await client.connect(url, { username, keyPair, password });
 
-      const session = await client.openSession({ type: 'exec', command });
+      const session = await client.openSession({ type: 'exec', command, primer });
 
       await new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
@@ -2145,8 +2159,20 @@ export class WshClient {
       // so channel-scoped control messages arriving before the stream
       // finishes binding still route correctly.
       this.#transport.openStream().then(
-        (stream) => {
+        async (stream) => {
           session._bind(stream.readable, stream.writable);
+          // The transport has already announced the stream, which is all a
+          // current host needs. Older hosts only bind a stream on its first
+          // byte, so exec (which has no stdin to send) writes a one-byte
+          // primer they strip -- unless the host says it needs none.
+          if (pending.kind === 'exec' && pending.primer && !this.hasFeature(STREAM_ANNOUNCE_FEATURE)) {
+            try {
+              await session.write(new Uint8Array([0]));
+            } catch (err) {
+              pending.reject(err);
+              return;
+            }
+          }
           pending.resolve(session);
         },
         (err) => pending.reject(err)

package/src/index.d.ts

@@ -238,6 +238,13 @@ export const PROTOCOL_VERSION: 'wsh-v1';
  */
 export const MCP_CALL_ID_FEATURE: 'mcp-call-id';
 
+/**
+ * ServerHello feature: the host discovers a client-opened exec data stream
+ * without help (the transport announces it), so the client writes no
+ * one-byte primer against it.
+ */
+export const STREAM_ANNOUNCE_FEATURE: 'stream-announce';
+
 /** A wsh protocol control message (all messages have a numeric `type`). */
 export interface WshMessage {
   type: number;
@@ -895,15 +902,19 @@ export function exportPrivateKeyPKCS8(privateKey: CryptoKey): Promise<Uint8Array
 export function importPrivateKeyPKCS8(pkcs8: Uint8Array, extractable?: boolean): Promise<CryptoKey>;
 
 /**
- * Sign data with an Ed25519 private key.
+ * Sign data with an Ed25519 private key. Positional order mirrors WebCrypto
+ * (`sign(privateKey, message)`) and is the canonical form across wsh, raijin
+ * and browsermesh.
  * @returns 64-byte signature
  */
-export function sign(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+export function sign(privateKey: CryptoKey, message: Uint8Array): Promise<Uint8Array>;
 
 /**
- * Verify an Ed25519 signature.
+ * Verify an Ed25519 signature. Positional order mirrors WebCrypto
+ * (`verify(publicKey, signature, message)`) and is the canonical form across
+ * wsh, raijin and browsermesh.
  */
-export function verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+export function verify(publicKey: CryptoKey, signature: Uint8Array, message: Uint8Array): Promise<boolean>;
 
 /** Options binding extra context into the auth transcript. */
 export interface WshTranscriptOptions {
@@ -1561,6 +1572,13 @@ export interface WshOpenSessionOptions {
   rows?: number;
   env?: Record<string, string>;
   timeout?: number;
+  /**
+   * Stream-mode `exec` only (default `true`): write the one-byte "primer"
+   * that older hosts need to discover the client-opened data stream. Skipped
+   * automatically against a host advertising `stream-announce`; `false`
+   * never sends it.
+   */
+  primer?: boolean;
 }
 
 /** Options for WshClient.attachSession(). */
@@ -1611,6 +1629,8 @@ export interface WshExecOptions {
   keyPair?: CryptoKeyPair;
   password?: string;
   timeout?: number;
+  /** See {@link WshOpenSessionOptions.primer}. */
+  primer?: boolean;
 }
 
 /** Result from WshClient.exec(). */

package/src/index.mjs

@@ -73,7 +73,7 @@ export {
 // Session + Client
 export { WshSession } from './session.mjs';
 export { WshVirtualSessionBackend, normalizeSessionData } from './virtual-session.mjs';
-export { WshClient, MCP_CALL_ID_FEATURE } from './client.mjs';
+export { WshClient, MCP_CALL_ID_FEATURE, STREAM_ANNOUNCE_FEATURE } from './client.mjs';
 
 // Key storage
 export { WshKeyStore } from './keystore.mjs';

package/src/qmux-connection.mjs

@@ -134,6 +134,27 @@ class QMuxStream {
     }
   }
 
+  /**
+   * Make this locally-initiated stream visible to the peer without sending
+   * any payload. A QMux/QUIC stream is created lazily on the wire: opening
+   * one only allocates an id locally, and the peer first learns it exists
+   * from the first STREAM frame it sees. A zero-length STREAM frame (no FIN)
+   * is legal QUIC and is exactly that first frame, so the peer's
+   * `onStreamOpen` fires now instead of whenever (if ever) the first real
+   * byte is written -- which for an exec session, with no stdin, is never.
+   * No-op once anything has been sent on the stream.
+   */
+  announce() {
+    if (this.#sendState !== SEND_STATE.READY) return;
+    this.#sendState = SEND_STATE.SEND;
+    this.#conn._sendFrame(encodeStream({
+      streamId: this.id,
+      offset: this.#sendOffset,
+      data: new Uint8Array(0),
+      fin: false,
+    }), 0);
+  }
+
   /** Half-close the send side: send FIN. No more write() calls after this. */
   async close() {
     if (this.#sendState === SEND_STATE.RESET_SENT || this.#sendState === SEND_STATE.DATA_SENT) return;

package/src/server/auth.mjs

@@ -0,0 +1,75 @@
+/**
+ * Server-side authentication for `@johnhenry/wsh/server`: an allowlist of
+ * Ed25519 public keys (SSH `authorized_keys` style) and/or a custom callback.
+ */
+
+import {
+  parseSSHPublicKey, extractRawFromSSHWire, fingerprint,
+} from '../auth.mjs';
+
+/**
+ * Parse an `authorized_keys`-style blob (one `ssh-ed25519 AAAA... [comment]`
+ * per line; blank lines and `#` comments ignored) into raw 32-byte keys.
+ * Malformed lines are skipped rather than failing the whole list.
+ *
+ * @param {string} text
+ * @returns {Uint8Array[]}
+ */
+export function parseAuthorizedKeys(text) {
+  const keys = [];
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    try {
+      const parsed = parseSSHPublicKey(line);
+      keys.push(extractRawFromSSHWire(parsed.data));
+    } catch {
+      // skip malformed line
+    }
+  }
+  return keys;
+}
+
+/**
+ * Normalize the `auth` option into one `authorize()` function.
+ *
+ * `auth` is an `authorize` function itself, or an object with
+ * `authorizedKeys` (a string of `ssh-ed25519` lines, a raw 32-byte
+ * `Uint8Array`, or an array of either) and/or `authorize`. A key must be on
+ * the list AND pass `authorize` (when both are given). With no `auth` at all
+ * every connection is refused -- a server never defaults to open.
+ *
+ * @param {undefined | Function | {
+ *   authorizedKeys?: string | Uint8Array | Array<string | Uint8Array>,
+ *   authorize?: (who: {username: string, fingerprint: string, publicKey: Uint8Array}) => boolean | Promise<boolean>,
+ * }} auth
+ * @returns {Promise<(who: {username: string, fingerprint: string, publicKey: Uint8Array}) => Promise<boolean>>}
+ */
+export async function buildAuthorizer(auth) {
+  if (typeof auth === 'function') return async (who) => (await auth(who)) === true;
+  if (!auth) return async () => false;
+
+  /** @type {Set<string> | null} */
+  let allowed = null;
+  if (auth.authorizedKeys !== undefined) {
+    allowed = new Set();
+    const items = Array.isArray(auth.authorizedKeys) ? auth.authorizedKeys : [auth.authorizedKeys];
+    for (const item of items) {
+      const raws = typeof item === 'string' ? parseAuthorizedKeys(item) : [item];
+      for (const raw of raws) {
+        if (!(raw instanceof Uint8Array) || raw.byteLength !== 32) {
+          throw new TypeError('createWshServer: auth.authorizedKeys entries must be ssh-ed25519 lines or raw 32-byte Ed25519 keys');
+        }
+        allowed.add(await fingerprint(raw));
+      }
+    }
+  }
+  const custom = typeof auth.authorize === 'function' ? auth.authorize : null;
+  if (!allowed && !custom) return async () => false;
+
+  return async (who) => {
+    if (allowed && !allowed.has(who.fingerprint)) return false;
+    if (custom) return (await custom(who)) === true;
+    return true;
+  };
+}

package/src/server/connection.mjs

@@ -0,0 +1,381 @@
+/**
+ * One wsh-v1 server connection, written against a byte pipe so it knows
+ * nothing about WebSocket: `attach({ send })` returns `{ receive, close }`.
+ * Speaks the same QMux-over-WebSocket framing the stock client's
+ * `WebSocketTransport` does.
+ *
+ * Exec data plane: exec sessions use `data_mode: 'stream'` -- output flows on
+ * the second, client-opened QMux stream. The client's transport announces that
+ * stream the moment it opens it (an empty STREAM frame), so the host sees it
+ * with no help; the host advertises `stream-announce` in ServerHello so the
+ * client knows not to write a primer byte. A client that does write one anyway
+ * (hosts that predate the announce required it) has the lone leading `0x00`
+ * 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 {
+  MSG, serverHello, challenge, authOk, authFail, openOk, openFail, sessionData,
+  exit as exitMsg, close as closeMsg, pong, fileResult, fileChunk,
+} from '../messages.gen.mjs';
+import {
+  generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
+} from '../auth.mjs';
+import { FILE_CHUNK_BYTES } from './fs.mjs';
+
+export const STREAM_ANNOUNCE = 'stream-announce';
+
+const MAX_CHANNELS = 64;
+const USERNAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+const enc = new TextEncoder();
+
+const randomBytes = (n) => crypto.getRandomValues(new Uint8Array(n));
+const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
+
+/**
+ * @param {object} cfg
+ * @param {(who: object) => Promise<boolean>} cfg.authorize
+ * @param {Function | null} cfg.execRunner
+ * @param {object} cfg.execOptions
+ * @param {object | null} cfg.pty - normalized (see pty.mjs)
+ * @param {object | null} cfg.files - from createFileAccess
+ * @param {number} cfg.bindTimeoutMs - how long exec output waits for the data stream
+ * @param {(line: string) => void} cfg.log
+ */
+export function createConnectionFactory(cfg) {
+  let counter = 0;
+
+  return function attach({ send: sendBytes }) {
+    const cid = ++counter;
+    const log = (m) => cfg.log(`[conn ${cid}] ${m}`);
+    const state = {
+      sessionId: randomUUID(), nonce: null, username: null, authed: false,
+      closed: false, nextChannel: 0,
+    };
+    /** @type {Map<number, any>} */
+    const channels = new Map();
+    /** Channel ids awaiting their client-opened data stream, in OpenOk order. */
+    const pendingStreams = [];
+    const decoder = new FrameDecoder();
+    const pendingSends = [];
+    let control = null;
+    let chain = Promise.resolve();
+
+    const qmux = new QMuxConnection({ isClient: false, send: (b) => { if (!state.closed) sendBytes(b); } });
+
+    const send = (msg) => {
+      if (state.closed) return Promise.resolve();
+      const bytes = frameEncode(msg);
+      if (control) return control.write(bytes).catch(() => {});
+      pendingSends.push(bytes);
+      return Promise.resolve();
+    };
+
+    function shutdown(why) {
+      if (state.closed) return;
+      state.closed = true;
+      for (const ch of channels.values()) ch.kill?.();
+      channels.clear();
+      try { qmux.destroy(new Error(why)); } catch { /* already gone */ }
+      log(`closed (${why})`);
+    }
+
+    qmux.onError = (e) => log(`qmux error: ${e.message}`);
+    qmux.onClose = () => shutdown('peer sent CONNECTION_CLOSE');
+    qmux.onStreamOpen = (s) => {
+      if (s.id !== 0) { bindDataStream(s); return; }
+      control = s;
+      s.onData = (d) => {
+        let msgs;
+        try { msgs = decoder.feed(d); } catch (e) { log(`frame decode error: ${e.message}`); return; }
+        for (const m of msgs) chain = chain.then(() => handle(m)).catch((e) => log(`handler error: ${e.message}`));
+      };
+      s.onEnd = () => shutdown('control stream FIN');
+      s.onReset = () => shutdown('control stream reset');
+      for (const b of pendingSends.splice(0)) s.write(b).catch(() => {});
+    };
+    qmux.sendHandshake();
+
+    function bindDataStream(s) {
+      const channelId = pendingStreams.shift();
+      const ch = channelId !== undefined ? channels.get(channelId) : undefined;
+      if (!ch?.bind) { s.close().catch(() => {}); return; }
+      ch.bind(s);
+    }
+
+    // ── Auth ──────────────────────────────────────────────────────────
+
+    async function handle(m) {
+      if (state.closed) return;
+      if (!state.authed) return handleAuth(m);
+      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.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; }
+        case MSG.FILE_OP: return handleFileOp(m);
+        case MSG.FILE_CHUNK: return channels.get(m.channel_id)?.chunk?.(m);
+        default: log(`ignored message type 0x${m.type.toString(16)}`);
+      }
+    }
+
+    async function refuse(reason) {
+      log(`AUTH_FAIL: ${reason}`);
+      await send(authFail({ reason }));
+      setTimeout(() => shutdown('auth failed'), 50);
+    }
+
+    async function handleAuth(m) {
+      if (m.type === MSG.HELLO) {
+        const user = String(m.username ?? '');
+        if (!USERNAME_RE.test(user)) return refuse(`bad username ${JSON.stringify(user)}`);
+        if (m.auth_method && m.auth_method !== 'pubkey') return refuse('this host only accepts Ed25519 pubkey auth');
+        state.username = user;
+        state.nonce = generateNonce();
+        const features = [STREAM_ANNOUNCE];
+        if (cfg.files) features.push('file-transfer');
+        await send(serverHello({ sessionId: state.sessionId, features }));
+        await send(challenge({ nonce: state.nonce, sessionId: state.sessionId }));
+        return;
+      }
+      if (m.type === MSG.AUTH) {
+        if (!state.nonce) return;
+        if (m.method !== 'pubkey' || !(m.public_key instanceof Uint8Array) || !(m.signature instanceof Uint8Array)) {
+          return refuse('expected a pubkey AUTH with public_key and signature');
+        }
+        let fp;
+        let key;
+        try {
+          fp = await fingerprint(m.public_key);
+          key = await importPublicKeyRaw(m.public_key);
+        } catch { return refuse('malformed public key'); }
+        // Verify the signature first: nothing about who is on the allowlist
+        // is revealed to a caller who cannot even prove they hold a key.
+        let ok = false;
+        try {
+          ok = await verifyChallenge(key, m.signature, state.sessionId, state.nonce, { username: state.username });
+        } catch { ok = false; }
+        if (!ok) return refuse('signature does not verify over the transcript');
+        let allowed = false;
+        try {
+          allowed = await cfg.authorize({ username: state.username, fingerprint: fp, publicKey: m.public_key });
+        } catch (e) { log(`authorize threw: ${e.message}`); }
+        if (!allowed) return refuse('key not authorized');
+        state.authed = true;
+        state.nonce = null;
+        await send(authOk({ sessionId: state.sessionId, token: randomBytes(16), ttl: 3600 }));
+        log(`authenticated ${state.username} (${fp.slice(0, 12)}...)`);
+      }
+    }
+
+    // ── Open ──────────────────────────────────────────────────────────
+
+    function handleOpen(m) {
+      if (channels.size >= MAX_CHANNELS) return send(openFail({ reason: 'too many open channels' }));
+      switch (m.kind) {
+        case 'exec': return openExec(m);
+        case 'pty': return openPty(m);
+        case 'file': return openFile(m);
+        default: return send(openFail({ reason: `kind "${m.kind}" is not supported by this server` }));
+      }
+    }
+
+    function finishChannel(channelId, code) {
+      if (!channels.has(channelId) || state.closed) return Promise.resolve();
+      channels.delete(channelId);
+      return send(exitMsg({ channelId, code })).then(() => send(closeMsg({ channelId })));
+    }
+
+    async function openExec(m) {
+      if (!cfg.execRunner) return send(openFail({ reason: 'exec is not enabled on this server' }));
+      const command = String(m.command ?? '').trim();
+      if (!command) return send(openFail({ reason: 'command is required for kind "exec"' }));
+
+      const channelId = ++state.nextChannel;
+      const abort = new AbortController();
+      let stream = null;
+      let primerChecked = false;
+      let wq = Promise.resolve();
+      const buffered = [];
+      const boundWaiters = [];
+      const inputCbs = [];
+      const endCbs = [];
+      const signalCbs = [];
+
+      const ch = {
+        kill: () => abort.abort(),
+        signal: (name) => {
+          const n = name.replace(/^SIG/, '').toUpperCase();
+          for (const cb of signalCbs) cb(n);
+          if (/^(INT|TERM|KILL|HUP)$/.test(n) && signalCbs.length === 0) abort.abort();
+        },
+        bind(s) {
+          stream = s;
+          s.onData = (d) => {
+            // A client that primes (see header) sends one lone 0x00 first.
+            if (!primerChecked) {
+              primerChecked = true;
+              if (d.byteLength === 1 && d[0] === 0) return;
+            }
+            if (d.byteLength) for (const cb of inputCbs) cb(d);
+          };
+          s.onEnd = () => { for (const cb of endCbs) cb(); };
+          s.onReset = () => abort.abort();
+          const pending = buffered.splice(0);
+          wq = wq.then(async () => { for (const b of pending) await s.write(b).catch(() => {}); });
+          for (const r of boundWaiters.splice(0)) r();
+        },
+      };
+      channels.set(channelId, ch);
+      pendingStreams.push(channelId);
+
+      let timer = null;
+      if (cfg.execOptions.timeoutMs > 0) timer = setTimeout(() => abort.abort(), cfg.execOptions.timeoutMs);
+
+      const io = {
+        user: state.username,
+        env: m.env && typeof m.env === 'object' && cfg.execOptions.clientEnv !== false ? m.env : {},
+        cols: m.cols || 80,
+        rows: m.rows || 24,
+        signal: abort.signal,
+        write(data) {
+          const bytes = toBytes(data);
+          if (!stream) { buffered.push(bytes); return Promise.resolve(); }
+          const s = stream;
+          wq = wq.then(() => s.write(bytes).catch(() => {}));
+          return wq;
+        },
+        onInput: (cb) => inputCbs.push(cb),
+        onInputEnd: (cb) => endCbs.push(cb),
+        onSignal: (cb) => signalCbs.push(cb),
+      };
+
+      await send(openOk({
+        channelId, dataMode: 'stream', capabilities: ['signal'],
+        sessionId: randomUUID(), token: randomBytes(16),
+      }));
+      log(`exec channel ${channelId}: ${command}`);
+
+      // Detached: the message chain must stay free to deliver this
+      // session's Signal/Close/SessionData while the command runs.
+      runExec().catch((e) => log(`exec channel ${channelId}: ${e.message}`));
+
+      async function runExec() {
+      let code;
+      try { code = await cfg.execRunner(command, io); } catch (e) {
+        await io.write(`wsh: ${e.message}\n`);
+        code = 1;
+      }
+      if (timer) clearTimeout(timer);
+      // Output is ready but the client's stream may not have been bound yet
+      // (a host without announce support waits for the first byte): give it
+      // a bounded chance rather than dropping the output or hanging forever.
+      if (!stream) await Promise.race([new Promise((r) => boundWaiters.push(r)), new Promise((r) => setTimeout(r, cfg.bindTimeoutMs))]);
+      if (!stream) log(`exec channel ${channelId}: data stream never appeared; output dropped`);
+      await wq;
+      try { await stream?.close(); } catch { /* peer gone */ }
+      await finishChannel(channelId, Number.isInteger(code) ? code : 0);
+      }
+    }
+
+    async function openPty(m) {
+      if (!cfg.pty) return send(openFail({ reason: 'pty is not enabled on this server' }));
+      const channelId = ++state.nextChannel;
+      const cols = m.cols || 80;
+      const rows = m.rows || 24;
+      const p = cfg.pty;
+      let proc;
+      try {
+        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 : {}) },
+        });
+      } catch (e) {
+        return send(openFail({ reason: `pty spawn failed: ${e.message}` }));
+      }
+      const ch = {
+        input: (data) => { try { proc.write(Buffer.from(data)); } catch { /* exited */ } },
+        resize: (c, r) => { try { proc.resize(c || cols, r || rows); } catch { /* exited */ } },
+        signal: (name) => { try { proc.kill(`SIG${name.replace(/^SIG/, '').toUpperCase()}`); } catch { /* exited */ } },
+        kill: () => { try { proc.kill(); } catch { /* exited */ } },
+      };
+      channels.set(channelId, ch);
+      let out = Promise.resolve();
+      proc.onData((d) => { out = out.then(() => send(sessionData({ channelId, data: toBytes(d) }))); });
+      proc.onExit(({ exitCode }) => { out.then(() => finishChannel(channelId, exitCode ?? 0)); });
+      await send(openOk({
+        channelId, dataMode: 'virtual', capabilities: ['resize', 'signal'],
+        sessionId: randomUUID(), token: randomBytes(16),
+      }));
+      log(`pty channel ${channelId} opened (${cols}x${rows})`);
+    }
+
+    async function openFile(m) {
+      if (!cfg.files) return send(openFail({ reason: 'file access is not enabled on this server' }));
+      const spec = String(m.command ?? '');
+      const mm = spec.match(/^(upload|download):(.*)$/s);
+      if (!mm) return send(openFail({ reason: 'file channel expects upload:<path> or download:<path>' }));
+      const [, direction, filePath] = mm;
+      const channelId = ++state.nextChannel;
+
+      if (direction === 'download') {
+        let data;
+        try { data = await cfg.files.readWhole(filePath); } catch (e) { return send(openFail({ reason: e.message })); }
+        channels.set(channelId, { kill: () => channels.delete(channelId) });
+        await send(openOk({ channelId, dataMode: 'virtual', capabilities: [] }));
+        let off = 0;
+        do {
+          const end = Math.min(off + FILE_CHUNK_BYTES, data.byteLength);
+          await send(fileChunk({ channelId, offset: off, data: data.subarray(off, end), isFinal: end >= data.byteLength, totalSize: data.byteLength }));
+          off = end;
+        } while (off < data.byteLength);
+        log(`download ${filePath} (${data.byteLength} B)`);
+        return;
+      }
+
+      const ch = { buf: null, kill: () => channels.delete(channelId) };
+      channels.set(channelId, ch);
+      const done = async (code, why) => {
+        if (why) log(`upload ${filePath}: ${why}`);
+        await finishChannel(channelId, code);
+      };
+      ch.chunk = async (c) => {
+        if (ch.failed) return;
+        const total = Number(c.total_size ?? 0);
+        if (total > cfg.files.maxFileBytes) { ch.failed = true; return done(1, `refused: ${total} B exceeds ${cfg.files.maxFileBytes} B`); }
+        ch.buf ??= new Uint8Array(total);
+        const data = c.data instanceof Uint8Array ? c.data : new Uint8Array(0);
+        if (c.offset + data.byteLength > ch.buf.byteLength) { ch.failed = true; return done(1, 'chunk past total_size'); }
+        ch.buf.set(data, c.offset);
+        if (c.is_final) {
+          try { await cfg.files.writeWhole(filePath, ch.buf); } catch (e) { ch.failed = true; return done(1, e.message); }
+          return done(0, `stored ${ch.buf.byteLength} B`);
+        }
+      };
+      await send(openOk({ channelId, dataMode: 'virtual', capabilities: [] }));
+    }
+
+    async function handleFileOp(m) {
+      const channelId = m.channel_id;
+      if (!cfg.files) return send(fileResult({ channelId, success: false, errorMessage: 'file access is not enabled on this server' }));
+      try {
+        const r = await cfg.files.operate(m.op, m.path, { offset: m.offset, length: m.length });
+        return send(fileResult({ channelId, success: true, metadata: r.metadata ?? {}, entries: r.entries ?? [] }));
+      } catch (e) {
+        const message = e.wsh ? e.message : (e.code === 'ENOENT' ? 'no such file or directory' : `${m.op} failed`);
+        if (!e.wsh && e.code !== 'ENOENT') log(`file ${m.op} ${m.path}: ${e.message}`);
+        return send(fileResult({ channelId, success: false, errorMessage: message }));
+      }
+    }
+
+    return {
+      receive(bytes) { if (!state.closed) qmux.receiveBytes(bytes); },
+      close() { shutdown('transport closed'); },
+    };
+  };
+}

package/src/server/exec.mjs

@@ -0,0 +1,60 @@
+/**
+ * Default `exec` runner for `@johnhenry/wsh/server`: runs the command through
+ * a shell with `node:child_process` and wires it to the session `io`.
+ *
+ * A custom runner has the same shape -- `run(command, io) => Promise<exitCode>`
+ * -- so a restricted host (no real shell) can replace this wholesale.
+ */
+
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+
+/**
+ * @param {{ cwd?: string, env?: object, shell?: boolean | string }} [opts]
+ * @returns {(command: string, io: ExecIo) => Promise<number>}
+ */
+export function spawnRunner({ cwd, env, shell = true } = {}) {
+  return (command, io) => new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(command, {
+        shell,
+        cwd,
+        env: { ...(env ?? process.env), ...io.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      io.write(`wsh: ${err.message}\n`).finally(() => resolve(127));
+      return;
+    }
+
+    const out = (chunk) => { io.write(new Uint8Array(chunk)); };
+    proc.stdout.on('data', out);
+    proc.stderr.on('data', out);
+    proc.stdin.on('error', () => { /* process exited before stdin drained */ });
+    io.onInput((bytes) => { try { proc.stdin.write(bytes); } catch { /* exited */ } });
+    io.onInputEnd(() => { try { proc.stdin.end(); } catch { /* exited */ } });
+    io.onSignal((name) => { try { proc.kill(`SIG${name}`); } catch { /* exited or unknown */ } });
+    io.signal.addEventListener('abort', () => { try { proc.kill('SIGTERM'); } catch { /* exited */ } }, { once: true });
+
+    proc.on('error', (err) => {
+      io.write(`wsh: ${err.message}\n`).finally(() => resolve(127));
+    });
+    proc.on('close', (code, signal) => {
+      resolve(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 0));
+    });
+  });
+}
+
+/**
+ * @typedef {object} ExecIo
+ * @property {string} user - Authenticated username.
+ * @property {Record<string,string>} env - Environment requested by the client.
+ * @property {number} cols
+ * @property {number} rows
+ * @property {AbortSignal} signal - Aborts on client Close, disconnect or timeout.
+ * @property {(data: Uint8Array | string) => Promise<void>} write - Send output; resolves when flow control accepts it.
+ * @property {(cb: (bytes: Uint8Array) => void) => void} onInput - Client stdin.
+ * @property {(cb: () => void) => void} onInputEnd - Client closed stdin.
+ * @property {(cb: (name: string) => void) => void} onSignal - Named signal (`INT`, `TERM`, ...).
+ */

package/src/server/fs.mjs

@@ -0,0 +1,134 @@
+/**
+ * File access for `@johnhenry/wsh/server`: FileOp requests (list, stat, read,
+ * mkdir, remove) and `upload:`/`download:` file channels, confined to one
+ * root directory.
+ *
+ * Every path a client sends is resolved against `root`; a path that would
+ * leave it -- by `..`, an absolute path, or a symlink -- is refused.
+ */
+
+import {
+  readdir, lstat, stat, readFile, writeFile, mkdir, rmdir, unlink, readlink, realpath, open,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+export const FILE_CHUNK_BYTES = 64 * 1024;
+
+/**
+ * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} opts
+ */
+export function createFileAccess({ root, readOnly = false, maxFileBytes = DEFAULT_MAX_FILE_BYTES }) {
+  if (typeof root !== 'string' || !root) throw new TypeError('createWshServer: fs.root is required');
+  const base = path.resolve(root);
+  let realBase = null;
+
+  const fail = (message) => Object.assign(new Error(message), { wsh: true });
+
+  /** Resolve a client path to an absolute path inside `root`, or throw. */
+  async function resolveInside(clientPath) {
+    if (typeof clientPath !== 'string') throw fail('path is required');
+    if (clientPath.includes('\0')) throw fail('illegal path');
+    realBase ??= await realpath(base);
+    const target = path.resolve(base, '.' + path.sep + clientPath.replace(/^[/\\]+/, ''));
+    if (target !== base && !target.startsWith(base + path.sep)) throw fail('path escapes the file root');
+    // Symlink escape: the deepest existing ancestor must still be inside the real root.
+    let probe = target;
+    for (;;) {
+      try {
+        const real = await realpath(probe);
+        if (real !== realBase && !real.startsWith(realBase + path.sep)) throw fail('path escapes the file root');
+        break;
+      } catch (err) {
+        if (err.wsh) throw err;
+        const parent = path.dirname(probe);
+        if (parent === probe) break;
+        probe = parent;
+      }
+    }
+    return target;
+  }
+
+  const typeOf = (st) => st.isSymbolicLink() ? 'symlink'
+    : st.isDirectory() ? 'directory'
+      : st.isFile() ? 'file'
+        : st.isBlockDevice() || st.isCharacterDevice() ? 'device'
+          : st.isFIFO() ? 'pipe'
+            : st.isSocket() ? 'socket' : 'file';
+
+  async function entryFor(full, name) {
+    const st = await lstat(full);
+    const entry = { name, size: st.size, modified: Math.floor(st.mtimeMs / 1000), type: typeOf(st) };
+    if (entry.type === 'symlink') {
+      try { entry.symlink_target = await readlink(full); } catch { /* raced */ }
+    }
+    return entry;
+  }
+
+  const assertWritable = () => { if (readOnly) throw fail('file root is read-only'); };
+
+  return {
+    maxFileBytes,
+
+    /** @returns {Promise<{ metadata?: object, entries?: object[] }>} */
+    async operate(op, clientPath, { offset, length } = {}) {
+      switch (op) {
+        case 'list': {
+          const dir = await resolveInside(clientPath || '/');
+          const names = await readdir(dir);
+          const entries = [];
+          for (const name of names.sort()) {
+            try { entries.push(await entryFor(path.join(dir, name), name)); } catch { /* raced */ }
+          }
+          return { entries, metadata: { path: clientPath || '/' } };
+        }
+        case 'stat': {
+          const full = await resolveInside(clientPath);
+          return { metadata: await entryFor(full, path.basename(full)) };
+        }
+        case 'read': {
+          const full = await resolveInside(clientPath);
+          const st = await stat(full);
+          if (!st.isFile()) throw fail('not a regular file');
+          const start = Math.max(0, Number(offset ?? 0));
+          const want = Math.min(Number(length ?? FILE_CHUNK_BYTES), FILE_CHUNK_BYTES);
+          const fh = await open(full, 'r');
+          try {
+            const buf = new Uint8Array(want);
+            const { bytesRead } = await fh.read(buf, 0, want, start);
+            return { metadata: { data: buf.subarray(0, bytesRead), size: st.size } };
+          } finally { await fh.close(); }
+        }
+        case 'mkdir': {
+          assertWritable();
+          await mkdir(await resolveInside(clientPath), { recursive: true });
+          return { metadata: {} };
+        }
+        case 'remove': {
+          assertWritable();
+          const full = await resolveInside(clientPath);
+          if (full === base) throw fail('refusing to remove the file root');
+          await ((await lstat(full)).isDirectory() ? rmdir(full) : unlink(full));
+          return { metadata: { removed: clientPath } };
+        }
+        default:
+          throw fail(`"${op}" is not offered by this host (list, stat, read, mkdir, remove; use upload/download to write)`);
+      }
+    },
+
+    async readWhole(clientPath) {
+      const full = await resolveInside(clientPath);
+      const st = await stat(full);
+      if (!st.isFile()) throw fail('not a regular file');
+      if (st.size > maxFileBytes) throw fail(`file is ${st.size} bytes; the limit is ${maxFileBytes}`);
+      return new Uint8Array(await readFile(full));
+    },
+
+    async writeWhole(clientPath, data) {
+      assertWritable();
+      const full = await resolveInside(clientPath);
+      await mkdir(path.dirname(full), { recursive: true });
+      await writeFile(full, data);
+    },
+  };
+}

package/src/server/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Types for `@johnhenry/wsh/server` -- the Node host. Node-only; the package
+ * root (`@johnhenry/wsh`) never imports it.
+ */
+
+/** Who is asking to authenticate. */
+export interface WshServerPrincipal {
+  username: string;
+  /** Hex SHA-256 of the raw public key (see `fingerprint()`). */
+  fingerprint: string;
+  /** Raw 32-byte Ed25519 public key. */
+  publicKey: Uint8Array;
+}
+
+export interface WshServerAuthOptions {
+  /**
+   * Keys allowed to connect: `ssh-ed25519 AAAA... [comment]` lines (an
+   * `authorized_keys` file's text works), raw 32-byte keys, or an array of either.
+   */
+  authorizedKeys?: string | Uint8Array | Array<string | Uint8Array>;
+  /** Extra policy, run after the signature verifies (and after the allowlist, when given). */
+  authorize?: (who: WshServerPrincipal) => boolean | Promise<boolean>;
+}
+
+/** What a custom `exec` runner receives for one session. */
+export interface WshExecIo {
+  user: string;
+  /** Environment the client asked for (empty when `clientEnv: false`). */
+  env: Record<string, string>;
+  cols: number;
+  rows: number;
+  /** Aborts on client Close, disconnect, timeout, or a terminating signal nothing handled. */
+  signal: AbortSignal;
+  /** Send output; resolves when flow control has accepted it. */
+  write(data: Uint8Array | string): Promise<void>;
+  /** Client stdin. */
+  onInput(cb: (bytes: Uint8Array) => void): void;
+  /** Client closed stdin. */
+  onInputEnd(cb: () => void): void;
+  /** Named signal from the client (`INT`, `TERM`, ...). */
+  onSignal(cb: (name: string) => void): void;
+}
+
+/** Runs one exec session; resolve with the exit code. */
+export type WshExecRunner = (command: string, io: WshExecIo) => Promise<number>;
+
+export interface WshServerExecOptions {
+  /** Working directory of spawned commands. */
+  cwd?: string;
+  /** Base environment (default `process.env`). */
+  env?: Record<string, string | undefined>;
+  /** `true` (default `/bin/sh`), or a shell path. */
+  shell?: boolean | string;
+  /** Kill a session after this long (0 / omitted = never). */
+  timeoutMs?: number;
+  /** Apply `env` sent by the client (default `true`). */
+  clientEnv?: boolean;
+  /** Replace the child_process runner entirely (e.g. a restricted, no-shell host). */
+  run?: WshExecRunner;
+}
+
+/** The part of a pseudo-terminal process the server uses -- `node-pty`'s `IPty` fits. */
+export interface WshPtyProcess {
+  onData(cb: (data: string | Uint8Array) => void): unknown;
+  onExit(cb: (e: { exitCode: number; signal?: number }) => void): unknown;
+  write(data: string | Uint8Array): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+export interface WshServerPtyOptions {
+  /** `node-pty`'s `spawn(file, args, options)`, or anything shaped like it. */
+  spawn(file: string, args: string[], options: {
+    name: string; cols: number; rows: number; cwd?: string; env: Record<string, string | undefined>;
+  }): WshPtyProcess;
+  /** Shell to run (default `$SHELL` or `/bin/sh`). */
+  shell?: string;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** `TERM` value (default `xterm-256color`). */
+  term?: string;
+}
+
+export interface WshServerFsOptions {
+  /** Every client path is resolved inside this directory; `..`, absolute paths and symlinks out of it are refused. */
+  root: string;
+  readOnly?: boolean;
+  /** Upload / download size cap in bytes (default 64 MiB). */
+  maxFileBytes?: number;
+}
+
+export interface WshServerOptions {
+  /** Bind address (default `127.0.0.1`). */
+  host?: string;
+  /** Port (default `0` = pick a free one; read it back from `address()`). */
+  port?: number;
+  /** Who may connect. Omitted = every connection is refused. A function is shorthand for `{ authorize }`. */
+  auth?: WshServerAuthOptions | ((who: WshServerPrincipal) => boolean | Promise<boolean>);
+  /** Enable `exec` sessions. `true`, options, or a custom runner. Off by default. */
+  exec?: true | WshServerExecOptions | WshExecRunner;
+  /** Enable `pty` sessions by injecting a pty implementation. Off by default. */
+  pty?: WshServerPtyOptions;
+  /** Enable file ops and uploads/downloads under one directory. Off by default. */
+  fs?: WshServerFsOptions;
+  /** How long exec output waits for a client that has not yet opened its data stream (default 3000). */
+  bindTimeoutMs?: number;
+  onLog?: (line: string) => void;
+}
+
+export interface WshServerAddress {
+  address: string;
+  port: number;
+}
+
+export interface WshServer {
+  /** Start listening. Requires the `ws` package. */
+  listen(): Promise<WshServerAddress>;
+  /** Drop every connection and stop listening. */
+  close(): Promise<void>;
+  /** The bound address, or `null` when not listening. */
+  address(): WshServerAddress | null;
+}
+
+export function createWshServer(options?: WshServerOptions): WshServer;
+
+/** Parse `authorized_keys`-style text into raw 32-byte Ed25519 keys (malformed lines skipped). */
+export function parseAuthorizedKeys(text: string): Uint8Array[];
+
+/** ServerHello feature: the host discovers client-opened exec data streams itself (no primer byte). */
+export const STREAM_ANNOUNCE: 'stream-announce';

package/src/server/index.mjs

@@ -0,0 +1,95 @@
+/**
+ * `@johnhenry/wsh/server` -- a Node host for the wsh-v1 protocol, built on the
+ * same primitives the client is. Node-only (`ws`, `node:child_process`,
+ * `node:fs`); the package root stays browser-safe and never imports this.
+ *
+ * Everything that grants a client access to the machine -- `exec`, `pty`,
+ * `fs` -- is OFF unless you pass it, and with no `auth` every connection is
+ * refused.
+ */
+
+import { buildAuthorizer, parseAuthorizedKeys } from './auth.mjs';
+import { spawnRunner } from './exec.mjs';
+import { normalizePty } from './pty.mjs';
+import { createFileAccess } from './fs.mjs';
+import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
+
+export { parseAuthorizedKeys, STREAM_ANNOUNCE };
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.host='127.0.0.1']
+ * @param {number} [options.port=0] - 0 picks a free port; read it back from `address()`.
+ * @param {object | Function} [options.auth] - See `buildAuthorizer`. Omitted = refuse everyone.
+ * @param {true | object | Function} [options.exec] - `true` (shell via child_process),
+ *   `{ cwd, env, shell, timeoutMs, clientEnv }`, or a custom `run(command, io)` function.
+ * @param {{ spawn: Function, shell?: string, cwd?: string, env?: object }} [options.pty]
+ * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} [options.fs]
+ * @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, bindTimeoutMs = 3000, onLog = () => {},
+} = {}) {
+  let wss = null;
+  let bound = null;
+
+  let execRunner = null;
+  let execOptions = {};
+  if (typeof exec === 'function') {
+    execRunner = exec;
+  } else if (exec) {
+    execOptions = exec === true ? {} : exec;
+    execRunner = typeof execOptions.run === 'function' ? execOptions.run : spawnRunner(execOptions);
+  }
+  const ptyConfig = pty ? normalizePty(pty) : null;
+  const files = fs ? createFileAccess(fs) : null;
+
+  return {
+    async listen() {
+      if (wss) throw new Error('createWshServer: already listening');
+      let WebSocketServer;
+      try {
+        ({ WebSocketServer } = await import('ws'));
+      } catch (err) {
+        throw new Error('@johnhenry/wsh/server needs the "ws" package: npm install ws', { cause: err });
+      }
+      const authorize = await buildAuthorizer(auth);
+      const attach = createConnectionFactory({
+        authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
+      });
+
+      wss = new WebSocketServer({ host, port });
+      wss.on('connection', (ws) => {
+        const conn = attach({ send: (b) => { if (ws.readyState === 1) ws.send(b); } });
+        ws.on('message', (d) => {
+          const buf = Array.isArray(d) ? Buffer.concat(d) : Buffer.isBuffer(d) ? d : Buffer.from(d);
+          conn.receive(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+        });
+        ws.on('close', () => conn.close());
+        ws.on('error', () => {});
+      });
+      await new Promise((resolve, reject) => {
+        wss.once('listening', resolve);
+        wss.once('error', reject);
+      });
+      const a = wss.address();
+      bound = { address: a.address, port: a.port };
+      return bound;
+    },
+
+    async close() {
+      if (!wss) return;
+      const server = wss;
+      wss = null;
+      bound = null;
+      for (const client of server.clients) client.terminate();
+      await new Promise((resolve) => server.close(resolve));
+    },
+
+    address() {
+      return bound;
+    },
+  };
+}

package/src/server/pty.mjs

@@ -0,0 +1,25 @@
+/**
+ * `pty` support for `@johnhenry/wsh/server`.
+ *
+ * A pseudo-terminal needs a native addon, which this package deliberately
+ * does not depend on: the host application injects one. `pty.spawn` is
+ * `node-pty`'s `spawn(file, args, options)` (or anything shaped like it):
+ * it returns `{ onData(cb), onExit(cb), write(data), resize(cols, rows),
+ * kill(signal?) }`.
+ */
+
+/**
+ * @param {{ spawn: Function, shell?: string, cwd?: string, env?: object, term?: string }} pty
+ */
+export function normalizePty(pty) {
+  if (!pty || typeof pty.spawn !== 'function') {
+    throw new TypeError('createWshServer: pty.spawn must be a function (e.g. node-pty\'s spawn)');
+  }
+  return {
+    spawn: pty.spawn,
+    shell: pty.shell ?? process.env.SHELL ?? '/bin/sh',
+    cwd: pty.cwd,
+    env: pty.env,
+    term: pty.term ?? 'xterm-256color',
+  };
+}

package/src/transport-ws.mjs

@@ -256,6 +256,10 @@ export class WebSocketTransport extends WshTransport {
   /** @override */
   async _doOpenStream() {
     const qs = await this.#qmux.openStream();
+    // A stream is invisible to the peer until its first frame; a data stream
+    // that may never carry client bytes (exec has no stdin) must announce
+    // itself or the host never discovers it.
+    qs.announce();
     const adapter = new QMuxStreamAdapter(qs);
     return { readable: adapter.readable, writable: adapter.writable, id: qs.id };
   }