@johnhenry/wsh 0.17.1 → 0.19.0

package/src/server/fs.mjs

@@ -0,0 +1,174 @@
+/**
+ * File access for `@johnhenry/wsh/server`: FileOp requests (list, stat, read,
+ * write, rename, 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, rename,
+} from 'node:fs/promises';
+import { constants as fsc } from 'node:fs';
+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, newPath, data } = {}) {
+      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 } };
+        }
+        case 'write': {
+          if (!(data instanceof Uint8Array)) throw fail('write needs data');
+          await this.writeAt(clientPath, data, offset);
+          return { metadata: { written: data.byteLength } };
+        }
+        case 'rename': {
+          assertWritable();
+          if (typeof newPath !== 'string' || !newPath) throw fail('rename needs a destination path');
+          const from = await resolveInside(clientPath);
+          const to = await resolveInside(newPath);
+          if (from === base || to === base) throw fail('refusing to rename the file root');
+          if (from === to) return { metadata: { renamed: clientPath, to: newPath } };
+          if (to.startsWith(from + path.sep)) throw fail('cannot move a directory into itself');
+          await lstat(from); // ENOENT -> "no such file or directory"
+          let exists = true;
+          try { await lstat(to); } catch (e) { if (e.code === 'ENOENT') exists = false; else throw e; }
+          if (exists) throw fail('destination already exists');
+          await rename(from, to);
+          return { metadata: { renamed: clientPath, to: newPath } };
+        }
+        default:
+          throw fail(`"${op}" is not offered by this host (list, stat, read, write, rename, mkdir, remove)`);
+      }
+    },
+
+    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) {
+      return this.writeAt(clientPath, data, undefined, { mkdirs: true });
+    },
+
+    /**
+     * Write bytes into a regular file. `offset` omitted: replace the whole
+     * file (create/truncate). `offset` given: write in place at that byte
+     * offset without truncating (creates the file if missing).
+     */
+    async writeAt(clientPath, data, offset, { mkdirs = false } = {}) {
+      assertWritable();
+      const full = await resolveInside(clientPath);
+      if (full === base) throw fail('not a regular file');
+      const at = offset === undefined || offset === null ? undefined : Number(offset);
+      if (at !== undefined && (!Number.isSafeInteger(at) || at < 0)) throw fail('illegal offset');
+      if ((at ?? 0) + data.byteLength > maxFileBytes) throw fail(`write would exceed the ${maxFileBytes} byte limit`);
+      if (mkdirs) await mkdir(path.dirname(full), { recursive: true });
+      // A FIFO or device would block or misbehave on open: regular files only.
+      try {
+        if (!(await stat(full)).isFile()) throw fail('not a regular file');
+      } catch (e) { if (e.wsh) throw e; if (e.code !== 'ENOENT') throw e; }
+      if (at === undefined) { await writeFile(full, data); return; }
+      const fh = await open(full, fsc.O_RDWR | fsc.O_CREAT, 0o644);
+      try { await fh.write(data, 0, data.byteLength, at); } finally { await fh.close(); }
+    },
+  };
+}

package/src/server/host-key.mjs

@@ -0,0 +1,66 @@
+/**
+ * The server's own Ed25519 identity (see ../host-key.mjs for the wire shape).
+ *
+ * `hostKey` option forms:
+ *  - `true`                          ephemeral key, new every start (TOFU clients will see "changed" after a restart -- tests/demos only)
+ *  - `{ file: '/path/host_key' }`    PKCS#8 PEM; created (mode 0600) on first start, reused after -- the normal choice
+ *  - a `CryptoKeyPair`               your own key, e.g. from `generateKeyPair()`
+ */
+
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as nodeSign } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { exportPublicKeyRaw, importPublicKeyRaw, exportPublicKeySSH, sign, fingerprint } from '../auth.mjs';
+
+const PEM_OPTS = { type: 'pkcs8', format: 'pem' };
+
+function fromNodePrivateKey(priv) {
+  const x = createPublicKey(priv).export({ format: 'jwk' }).x;
+  return Buffer.from(x, 'base64url');
+}
+
+/**
+ * @returns {Promise<{ publicKey: Uint8Array, fingerprint: string, openssh: string, sign(data: Uint8Array): Promise<Uint8Array> }>}
+ */
+export async function loadHostKey(option) {
+  let raw;
+  let signFn;
+
+  if (option === true) {
+    const priv = generateKeyPairSync('ed25519').privateKey;
+    raw = new Uint8Array(fromNodePrivateKey(priv));
+    signFn = async (data) => new Uint8Array(nodeSign(null, data, priv));
+  } else if (option && typeof option === 'object' && typeof option.file === 'string') {
+    let pem;
+    try {
+      pem = await readFile(option.file, 'utf8');
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      await mkdir(path.dirname(path.resolve(option.file)), { recursive: true });
+      const fresh = generateKeyPairSync('ed25519').privateKey.export(PEM_OPTS);
+      try {
+        await writeFile(option.file, fresh, { mode: 0o600, flag: 'wx' });
+        pem = fresh;
+      } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        pem = await readFile(option.file, 'utf8'); // another start won the race
+      }
+    }
+    const priv = createPrivateKey(pem);
+    if (priv.asymmetricKeyType !== 'ed25519') throw new TypeError(`createWshServer: hostKey.file ${option.file} is not an Ed25519 key`);
+    raw = new Uint8Array(fromNodePrivateKey(priv));
+    signFn = async (data) => new Uint8Array(nodeSign(null, data, priv));
+  } else if (option && option.privateKey && option.publicKey) {
+    raw = await exportPublicKeyRaw(option.publicKey);
+    signFn = (data) => sign(option.privateKey, data);
+  } else {
+    throw new TypeError('createWshServer: hostKey must be true, { file }, or a CryptoKeyPair');
+  }
+
+  return {
+    publicKey: raw,
+    fingerprint: await fingerprint(raw),
+    openssh: await exportPublicKeySSH(await importPublicKeyRaw(raw)),
+    sign: signFn,
+  };
+}

package/src/server/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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>;
+  /**
+   * Enable password login: return `true` to admit. Sent in the clear inside the
+   * connection -- serve over `wss://` / a trusted link. Use a constant-time
+   * compare against hashes, never `===` on plaintext. Failures are throttled
+   * (see `rateLimit`); the callback is not consulted while a caller is locked out.
+   */
+  password?: (username: string, password: string) => boolean | Promise<boolean>;
+  /** Password-failure throttle. */
+  rateLimit?: {
+    /** Failures inside `windowMs` before lockout (default 5). */
+    maxFailures?: number;
+    /** Failure counting window (default 60000). */
+    windowMs?: number;
+    /** Lockout length once tripped (default 60000). */
+    lockoutMs?: number;
+    /** Pause before answering a failed attempt (default 250). */
+    failureDelayMs?: number;
+    /** Throttle bucket; default the peer address. Use this behind a proxy (e.g. read `x-forwarded-for` from `headers`). */
+    key?: (info: { address: string | undefined; headers: Record<string, string | string[] | undefined>; username: string }) => string;
+  };
+}
+
+/** The server's own identity, as advertised to clients. */
+export interface WshServerHostKey {
+  /** Hex SHA-256 of the raw key. */
+  fingerprint: string;
+  /** Raw 32-byte Ed25519 key. */
+  publicKey: Uint8Array;
+  /** `ssh-ed25519 AAAA...` */
+  openssh: string;
+}
+
+/** 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;
+  /**
+   * Advertise an Ed25519 host identity (with proof of possession) so clients can pin it.
+   * `{ file }` persists a PKCS#8 PEM (created 0600 on first start) -- the normal choice;
+   * `true` is a fresh key every start; or pass a `CryptoKeyPair`. Off by default.
+   */
+  hostKey?: true | { file: string } | CryptoKeyPair;
+  /** 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;
+  /** The advertised host identity; `null` before `listen()` resolves or without a `hostKey`. */
+  hostKey(): WshServerHostKey | 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,118 @@
+/**
+ * `@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, authMethods, FailureLimiter } from './auth.mjs';
+import { loadHostKey } from './host-key.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 {true | { file: string } | CryptoKeyPair} [options.hostKey] - The server's own Ed25519
+ *   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 {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, 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;
+  const methods = authMethods(auth);
+  const rl = auth?.rateLimit ?? {};
+  const rateLimit = {
+    limiter: new FailureLimiter(rl),
+    key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
+    failureDelayMs: rl.failureDelayMs ?? 250,
+  };
+  let host_ = 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);
+      host_ = hostKey ? await loadHostKey(hostKey) : null;
+      const attach = createConnectionFactory({
+        authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
+        methods, hostKey: host_, rateLimit,
+      });
+
+      wss = new WebSocketServer({ host, port });
+      wss.on('connection', (ws, req) => {
+        const conn = attach({
+          send: (b) => { if (ws.readyState === 1) ws.send(b); },
+          remote: { address: req?.socket?.remoteAddress, headers: req?.headers ?? {} },
+        });
+        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;
+    },
+
+    /** The advertised host identity (`null` until `listen()` resolves, or with no `hostKey`). */
+    hostKey() {
+      return host_ ? { fingerprint: host_.fingerprint, publicKey: host_.publicKey, openssh: host_.openssh } : null;
+    },
+  };
+}

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 };
   }