@johnhenry/wsh 0.17.0 → 0.18.0

package/src/messages.gen.mjs

@@ -145,6 +145,10 @@ export const MSG = Object.freeze({
 
   // Terminal
   TERMINAL_CONFIG:   0x9e,
+
+  // Keys
+  AUTHORIZED_KEY_ADD: 0x9f,
+  AUTHORIZED_KEY_RESULT: 0xa0,
 });
 
 // Reverse lookup: number → name
@@ -187,13 +191,10 @@ export function hello({ username, features = [], authMethod = AUTH_METHOD.PUBKEY
   };
 }
 
-export function serverHello({ sessionId, features = [], fingerprints = [] } = {}) {
-  return {
-    type: MSG.SERVER_HELLO,
-    session_id: sessionId,
-    features,
-    fingerprints,
-  };
+export function serverHello({ sessionId, features = [], fingerprints = [], hostFingerprint } = {}) {
+  const msg = { type: MSG.SERVER_HELLO, session_id: sessionId, features, fingerprints };
+  if (hostFingerprint !== undefined) msg.host_fingerprint = hostFingerprint;
+  return msg;
 }
 
 export function challenge({ nonce, sessionId } = {}) {
@@ -864,8 +865,8 @@ export function fileOp({ channelId, op, path, offset, length } = {}) {
   return msg;
 }
 
-export function fileResult({ channelId, success, metadata = {}, errorMessage } = {}) {
-  const msg = { type: MSG.FILE_RESULT, channel_id: channelId, success, metadata };
+export function fileResult({ channelId, success, metadata = {}, entries = [], errorMessage } = {}) {
+  const msg = { type: MSG.FILE_RESULT, channel_id: channelId, success, metadata, entries };
   if (errorMessage !== undefined) msg.error_message = errorMessage;
   return msg;
 }
@@ -915,6 +916,18 @@ export function terminalConfig({ channelId, frontend, options = {} } = {}) {
   };
 }
 
+export function authorizedKeyAdd({ publicKey, comment } = {}) {
+  const msg = { type: MSG.AUTHORIZED_KEY_ADD, public_key: publicKey };
+  if (comment !== undefined) msg.comment = comment;
+  return msg;
+}
+
+export function authorizedKeyResult({ success, added = false, errorMessage } = {}) {
+  const msg = { type: MSG.AUTHORIZED_KEY_RESULT, success, added };
+  if (errorMessage !== undefined) msg.error_message = errorMessage;
+  return msg;
+}
+
 // ── Relay forwarding ─────────────────────────────────────────────────
 
 // Message types a relay may forward inside a RelayForward wrapper.

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`, ...).
+ */