@johnhenry/wsh 0.17.1 → 0.19.0

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 {
@@ -1538,8 +1549,48 @@ export class WshVirtualSessionBackend {
 // client.mjs -- WshClient
 // ============================================================================
 
+/** The host identity a server proved it holds (see `WshClient.hostKey`). */
+export interface WshHostKey {
+  /** Hex SHA-256 of the raw key (same as `fingerprint()` / `ServerHello.host_fingerprint`). */
+  fingerprint: string;
+  /** Raw 32-byte Ed25519 host public key. */
+  publicKey: Uint8Array;
+  /** `ssh-ed25519 AAAA...` form, for display or `expectHostKey`. */
+  openssh: string;
+  /** `pinned` matched `expectHostKey`; `known`/`unknown` per `knownHosts`; `unpinned` = surfaced, nothing checked. */
+  status: 'pinned' | 'known' | 'unknown' | 'unpinned';
+}
+
+/** Why a host key was refused. */
+export type WshHostKeyErrorCode =
+  | 'HOST_KEY_MISSING' | 'HOST_KEY_INVALID' | 'HOST_KEY_MISMATCH' | 'HOST_KEY_UNKNOWN' | 'HOST_KEY_REJECTED';
+
+/** Thrown by `connect()` when the host key fails the caller's policy. No credential has been sent. */
+export class HostKeyError extends Error {
+  constructor(code: WshHostKeyErrorCode, message: string, details?: { expected?: string; actual?: string });
+  readonly code: WshHostKeyErrorCode;
+  /** MISMATCH: the pinned / expected fingerprint. */
+  readonly expected?: string;
+  /** MISMATCH / UNKNOWN: the fingerprint the host presented. */
+  readonly actual?: string;
+}
+
+/** Host-key policy shared by `connect()`, `exec()` and `connectReverse()`. */
+export interface WshHostKeyOptions {
+  /** Pin: hex fingerprint (optionally `sha256:`-prefixed), raw 32-byte key, or `ssh-ed25519 AAAA...` line. Refuses on mismatch or when the host presents no key. */
+  expectHostKey?: string | Uint8Array;
+  /** TOFU store. A changed key is always refused; an unseen host is refused unless `trustOnFirstUse` / `onHostKey` accepts it. */
+  knownHosts?: WshKnownHosts;
+  /** Pin an unseen host's key into `knownHosts`. */
+  trustOnFirstUse?: boolean;
+  /** Key `knownHosts` records this host under (default: the URL's `host:port`). */
+  hostLabel?: string;
+  /** Sees the verified key before any credential is sent; return `false` (or throw) to refuse. */
+  onHostKey?: (hostKey: WshHostKey) => boolean | void | Promise<boolean | void>;
+}
+
 /** Options for WshClient.connect(). */
-export interface WshConnectOptions {
+export interface WshConnectOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
   password?: string;
@@ -1561,6 +1612,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(). */
@@ -1591,6 +1649,11 @@ export interface WshConnectReverseOptions {
   password?: string;
   /** Forwarded to the underlying `connect()` -- see `WshConnectOptions`. */
   webTransport?: WshWebTransportOptions;
+  expectHostKey?: WshHostKeyOptions['expectHostKey'];
+  knownHosts?: WshKnownHosts;
+  trustOnFirstUse?: boolean;
+  hostLabel?: string;
+  onHostKey?: WshHostKeyOptions['onHostKey'];
   expose?: {
     shell?: boolean;
     exec?: boolean;
@@ -1606,11 +1669,13 @@ export interface WshConnectReverseOptions {
 }
 
 /** Options for WshClient.exec(). */
-export interface WshExecOptions {
+export interface WshExecOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
   password?: string;
   timeout?: number;
+  /** See {@link WshOpenSessionOptions.primer}. */
+  primer?: boolean;
 }
 
 /** Result from WshClient.exec(). */
@@ -1756,6 +1821,15 @@ export class WshClient {
    */
   hasFeature(name: string): boolean;
 
+  /**
+   * The host's Ed25519 identity once it has proven it holds the key for this
+   * connection; `null` if the server advertised none (e.g. the Rust server).
+   */
+  readonly hostKey: WshHostKey | null;
+
+  /** Default `onHostKey` for `connect()` (a per-call option wins). */
+  onHostKey: ((hostKey: WshHostKey) => boolean | void | Promise<boolean | void>) | null;
+
   /**
    * Connect to a wsh server, authenticate, and return the session ID.
    */
@@ -1814,6 +1888,20 @@ export class WshClient {
    */
   fileList(path: string, timeout?: number): Promise<WshFileOperationResult>;
 
+  /**
+   * Write bytes to a remote file. `offset` omitted replaces the file; given,
+   * writes in place at that offset. Needs the host feature `file-write`
+   * (`@johnhenry/wsh/server` with `fs` has it); throws against a host without
+   * it. Failure is reported as `success: false` in the result.
+   */
+  fileWrite(path: string, data: Uint8Array | string, offset?: number, timeout?: number): Promise<WshFileOperationResult>;
+
+  /**
+   * Rename/move a remote file or directory. Needs the host feature
+   * `file-rename`; throws against a host without it. Refuses to overwrite.
+   */
+  fileRename(oldPath: string, newPath: string, timeout?: number): Promise<WshFileOperationResult>;
+
   /**
    * Remove a remote file or directory (`FileOp` op `"remove"`). Refused
    * today by every `wsh-server` release ("not yet implemented" -- see

package/src/index.mjs

@@ -73,13 +73,14 @@ 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';
 
 // Host identity (TOFU) -- wsh #59
 export { WshKnownHosts } from './known-hosts.mjs';
+export { HostKeyError } from './host-key.mjs';
 
 // File transfer
 export { WshFileTransfer } from './file-transfer.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,132 @@
+/**
+ * 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;
+  };
+}
+
+/**
+ * Whether `auth` allows public-key login at all (an allowlist and/or an
+ * `authorize` callback, or the function shorthand) and/or password login.
+ *
+ * @param {any} auth
+ * @returns {{ pubkey: boolean, password: ((user: string, pass: string) => boolean | Promise<boolean>) | null }}
+ */
+export function authMethods(auth) {
+  if (typeof auth === 'function') return { pubkey: true, password: null };
+  if (!auth) return { pubkey: false, password: null };
+  if (auth.password !== undefined && typeof auth.password !== 'function') {
+    throw new TypeError('createWshServer: auth.password must be a function (user, pass) => boolean | Promise<boolean>');
+  }
+  return {
+    pubkey: auth.authorizedKeys !== undefined || typeof auth.authorize === 'function',
+    password: auth.password ?? null,
+  };
+}
+
+/**
+ * Failure throttle for password logins, keyed (by default) on the peer's
+ * address. After `maxFailures` failures inside `windowMs` the key is locked
+ * for `lockoutMs`, during which the password callback is not even called.
+ * A success clears the key. In-memory and per-process, by design.
+ */
+export class FailureLimiter {
+  #entries = new Map();
+  #now;
+  constructor({ maxFailures = 5, windowMs = 60_000, lockoutMs = 60_000, now = Date.now } = {}) {
+    this.maxFailures = maxFailures;
+    this.windowMs = windowMs;
+    this.lockoutMs = lockoutMs;
+    this.#now = now;
+  }
+
+  /** @returns {number} ms the key is still locked out (0 = free to try) */
+  lockedFor(key) {
+    const e = this.#entries.get(key);
+    if (!e) return 0;
+    const t = this.#now();
+    if (e.lockedUntil > t) return e.lockedUntil - t;
+    if (t - e.first > this.windowMs) this.#entries.delete(key);
+    return 0;
+  }
+
+  fail(key) {
+    const t = this.#now();
+    let e = this.#entries.get(key);
+    if (!e || t - e.first > this.windowMs) { e = { count: 0, first: t, lockedUntil: 0 }; this.#entries.set(key, e); }
+    e.count++;
+    if (e.count >= this.maxFailures) e.lockedUntil = t + this.lockoutMs;
+    if (this.#entries.size > 10_000) this.#entries.delete(this.#entries.keys().next().value);
+  }
+
+  succeed(key) { this.#entries.delete(key); }
+}