@johnhenry/wsh 0.17.0 → 0.18.0

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