@johnhenry/wsh 0.16.1 → 0.17.1

package/src/index.d.ts

@@ -228,6 +228,16 @@ export const AUTH_METHOD: {
 /** Protocol version string. */
 export const PROTOCOL_VERSION: 'wsh-v1';
 
+/**
+ * ServerHello feature advertising that McpResult echoes McpCall's call_id.
+ *
+ * Compare against `WshClient.hasFeature()` before setting `callId`:
+ * McpCallPayload is `deny_unknown_fields` server-side, so sending the field
+ * to a server predating it makes the server reject the call rather than
+ * ignore the field.
+ */
+export const MCP_CALL_ID_FEATURE: 'mcp-call-id';
+
 /** A wsh protocol control message (all messages have a numeric `type`). */
 export interface WshMessage {
   type: number;
@@ -396,10 +406,14 @@ export function mcpTools(opts?: {
 export function mcpCall(opts?: {
   tool?: string;
   arguments?: Record<string, unknown>;
+  /** Correlates this call with its McpResult. Omitted from the message entirely when undefined. */
+  callId?: string;
 }): WshMessage;
 
 export function mcpResult(opts?: {
   result?: unknown;
+  /** Echoed verbatim from the McpCall this answers. */
+  callId?: string;
 }): WshMessage;
 
 // -- Message constructors (reverse) --
@@ -764,6 +778,14 @@ export function fileResult(opts?: {
   channelId?: number;
   success?: boolean;
   metadata?: Record<string, unknown>;
+  /** wsh #59: typed directory entries for a "list" op (see WshFileListEntry-shaped wire fields). */
+  entries?: Array<{
+    name: string;
+    size: number;
+    modified: number;
+    type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+    symlink_target?: string;
+  }>;
   errorMessage?: string;
 }): WshMessage;
 
@@ -775,6 +797,18 @@ export function fileChunk(opts?: {
   totalSize?: number;
 }): WshMessage;
 
+/** wsh #59: install a public key into the remote's authorized_keys (see WshClient.addAuthorizedKey). */
+export function authorizedKeyAdd(opts?: {
+  publicKey?: Uint8Array;
+  comment?: string;
+}): WshMessage;
+
+export function authorizedKeyResult(opts?: {
+  success?: boolean;
+  added?: boolean;
+  errorMessage?: string;
+}): WshMessage;
+
 export function policyEval(opts?: {
   requestId?: string;
   action?: string;
@@ -817,7 +851,19 @@ export function isValidMessage(msg: unknown): boolean;
 // ============================================================================
 
 /**
- * Generate a new Ed25519 key pair.
+ * Whether this runtime's WebCrypto implements Ed25519, measured by
+ * generating a key rather than sniffed from a version string.
+ *
+ * There is no pure-JS fallback: one would need the private scalar as
+ * ordinary bytes, giving up the non-extractable `CryptoKey` property
+ * `WshKeyStore` is built around. Check this before committing to pubkey
+ * auth and fall back to password auth where it returns false.
+ */
+export function isEd25519Supported(): Promise<boolean>;
+
+/**
+ * Generate a new Ed25519 key pair. Throws with an actionable message
+ * where WebCrypto has no Ed25519 -- see `isEd25519Supported()`.
  * @param extractable - Whether private key can be exported (default false)
  */
 export function generateKeyPair(extractable?: boolean): Promise<CryptoKeyPair>;
@@ -1017,7 +1063,7 @@ export class WshTransport {
   readonly state: 'disconnected' | 'connecting' | 'connected' | 'closed';
 
   /** Connect to a wsh server. */
-  connect(url: string): Promise<void>;
+  connect(url: string, options?: object): Promise<void>;
 
   /** Gracefully close the transport. */
   close(): Promise<void>;
@@ -1044,7 +1090,7 @@ export class WshTransport {
   protected _emitError(err: Error): void;
 
   /** @protected Must be overridden by subclasses. */
-  protected _doConnect(url: string): Promise<void>;
+  protected _doConnect(url: string, options?: object): Promise<void>;
 
   /** @protected Must be overridden by subclasses. */
   protected _doClose(): Promise<void>;
@@ -1064,7 +1110,65 @@ export class WshTransport {
  * - Subsequent streams carry raw byte data (no framing).
  * - Server-initiated streams are surfaced via onStreamOpen.
  */
-export class WebTransportTransport extends WshTransport {}
+export class WebTransportTransport extends WshTransport {
+  /**
+   * @param options Forwarded to the `WebTransport` constructor. Options
+   *   passed to `connect()` override these per call.
+   */
+  constructor(options?: WshWebTransportOptions);
+
+  connect(url: string, options?: WshWebTransportOptions): Promise<void>;
+}
+
+/**
+ * One entry of `serverCertificateHashes`. The digest may be given as raw
+ * bytes, as hex (with or without `:` separators -- what
+ * `openssl x509 -fingerprint -sha256` prints), or as base64/base64url.
+ */
+export interface WshCertificateHash {
+  /** Defaults to `'sha-256'`, the only algorithm the platform accepts today. */
+  algorithm?: string;
+  value: BufferSource | string;
+}
+
+/**
+ * Options forwarded to the `WebTransport` constructor.
+ *
+ * `serverCertificateHashes` is the interesting one: it pins a specific
+ * self-signed certificate by digest, which is the only mechanism in the
+ * web platform that lets page JavaScript reach a server whose certificate
+ * no certificate authority signed. The platform's own constraints apply --
+ * `https:` URL, HTTP/3 only, ECDSA P-256 key, at most 14 days validity,
+ * no connection pooling.
+ *
+ * Every other key is forwarded verbatim, so platform options not listed
+ * here still work.
+ */
+export interface WshWebTransportOptions {
+  serverCertificateHashes?: Array<WshCertificateHash | BufferSource | string>;
+  allowPooling?: boolean;
+  requireUnreliable?: boolean;
+  congestionControl?: 'default' | 'throughput' | 'low-latency';
+  anticipatedConcurrentIncomingUnidirectionalStreams?: number | null;
+  anticipatedConcurrentIncomingBidirectionalStreams?: number | null;
+  protocols?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Decode one `serverCertificateHashes` digest into bytes. Accepts a
+ * `BufferSource`, hex (separators and an `... Fingerprint=` prefix are
+ * stripped), or base64/base64url. Throws a `TypeError` on an
+ * unrecognised shape and a `RangeError` on a digest of the wrong length
+ * for the algorithm.
+ */
+export function parseCertificateHash(value: BufferSource | string, algorithm?: string): Uint8Array;
+
+/**
+ * Normalise a caller-supplied options bag into a `WebTransportOptions`
+ * dictionary, or `undefined` when there is nothing to pass.
+ */
+export function normalizeWebTransportOptions(options?: WshWebTransportOptions): object | undefined;
 
 /**
  * Dispatch a fixed, already-available batch of items one at a time,
@@ -1307,8 +1411,21 @@ export class WshSession {
   /** Called when the remote process exits. */
   onExit: ((code: number) => void) | null;
 
-  /** Called when the session is fully closed. */
-  onClose: (() => void) | null;
+  /**
+   * Called when the session is fully closed.
+   *
+   * Receives the same value as `closeReason`: an Error for a torn-down
+   * session, null for an ordinary close.
+   */
+  onClose: ((reason: Error | null) => void) | null;
+
+  /**
+   * Why the session closed, or null for an ordinary close.
+   *
+   * A torn-down session and a clean exit are otherwise indistinguishable
+   * from the outside.
+   */
+  readonly closeReason: Error | null;
 
   /** Called when the remote peer acknowledges speculative local echo. */
   onEchoAck: ((payload: Record<string, unknown>) => void) | null;
@@ -1427,6 +1544,12 @@ export interface WshConnectOptions {
   keyPair?: CryptoKeyPair;
   password?: string;
   transport?: 'wt' | 'ws';
+  /**
+   * Forwarded to the `WebTransport` constructor when the WebTransport
+   * rung of the transport ladder is tried; ignored by the WebSocket rung,
+   * which has no `serverCertificateHashes` equivalent.
+   */
+  webTransport?: WshWebTransportOptions;
   timeout?: number;
 }
 
@@ -1466,6 +1589,8 @@ export interface WshConnectReverseOptions {
   username: string;
   keyPair?: CryptoKeyPair;
   password?: string;
+  /** Forwarded to the underlying `connect()` -- see `WshConnectOptions`. */
+  webTransport?: WshWebTransportOptions;
   expose?: {
     shell?: boolean;
     exec?: boolean;
@@ -1544,6 +1669,28 @@ export interface WshE2EResult {
   hybrid: boolean;
 }
 
+/**
+ * Raw `FileResult` response to a structured file-channel operation
+ * (`WshClient.fileList`/`fileRemove`/etc.), as received off the wire --
+ * wire field names (snake_case), not the camelCase shape the `fileResult()`
+ * message constructor takes as input. `entries` is only populated for a
+ * `"list"` op; `error_message` is only present on failure.
+ */
+export interface WshFileOperationResult {
+  type: number;
+  channel_id: number;
+  success: boolean;
+  metadata: Record<string, unknown>;
+  entries: Array<{
+    name: string;
+    size: number;
+    modified: number;
+    type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+    symlink_target?: string;
+  }>;
+  error_message?: string;
+}
+
 /**
  * WshClient -- manages a wsh connection, authentication, and multiple sessions.
  *
@@ -1659,6 +1806,36 @@ export class WshClient {
    */
   revokeSessionAccess(sessionId: string, principal: string, reason?: string): Promise<void>;
 
+  /**
+   * List a remote directory over the structured file channel (`FileOp`
+   * op `"list"`). Prefer `WshFileTransfer.list()` for a typed
+   * `WshFileListEntry[]` result (with `modified` as a `Date`) -- this is
+   * the raw wire-shaped `FileResult` response `fileOperation()` waits on.
+   */
+  fileList(path: 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
+   * README's file-op parity table); wired here so clients built against
+   * this SDK don't need to wait on the server to type-check against it.
+   */
+  fileRemove(path: string, timeout?: number): Promise<WshFileOperationResult>;
+
+  /**
+   * Install a raw 32-byte Ed25519 public key into the remote host's
+   * `~/.wsh/authorized_keys` (wsh #59's `AuthorizedKeyAdd` protocol
+   * message -- replaces `wsh copy-id`'s previous CLI-only shell-command
+   * approach with something every implementation, including this one,
+   * can call directly). Idempotent: installing an already-present key
+   * resolves `added: false` rather than duplicating the line or erroring.
+   */
+  addAuthorizedKey(
+    publicKeyRaw: Uint8Array,
+    comment?: string,
+    timeout?: number,
+  ): Promise<{ added: boolean }>;
+
   /**
    * Gracefully disconnect: close all sessions and the transport.
    */
@@ -1697,6 +1874,31 @@ export class WshClient {
    */
   sendRelayControl(msg: WshMessage): Promise<void>;
 
+  /**
+   * Send a raw control message on the authenticated connection.
+   *
+   * Prefer the typed methods. This is the hook `WshMcpBridge` and
+   * `WshFileTransfer` compose their own messages through.
+   */
+  sendControl(msg: WshMessage): Promise<void>;
+
+  /**
+   * Open a raw bidirectional stream on the underlying transport.
+   */
+  openStream(): Promise<WshStream>;
+
+  /**
+   * Observe every inbound control message this client handles. Listeners
+   * are called past the RelayForward trust gate, so a message from an
+   * unaccepted peer never reaches one.
+   */
+  addControlListener(fn: (msg: WshMessage) => void): void;
+
+  /**
+   * Stop observing inbound control messages.
+   */
+  removeControlListener(fn: (msg: WshMessage) => void): void;
+
   /**
    * Initiate end-to-end encryption for a session: `'X25519'` (default,
    * classical ECDH) or `'X25519+ML-KEM-768'` (hybrid, with automatic
@@ -1863,6 +2065,48 @@ export class WshKeyStore {
   restore(passphrase: string): Promise<WshRestoreResult>;
 }
 
+// ============================================================================
+// known-hosts.mjs -- WshKnownHosts (wsh #59)
+// ============================================================================
+
+/** Minimal storage interface `WshKnownHosts` needs -- `localStorage` already satisfies it. */
+export interface WshKnownHostsStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** Result of verifying a host's fingerprint against the stored record. */
+export interface WshHostVerifyResult {
+  status: 'known' | 'unknown' | 'changed';
+  /** Previously stored fingerprint, present only when status === 'changed'. */
+  expected?: string;
+}
+
+/**
+ * WshKnownHosts -- trust-on-first-use (TOFU) host-identity store, mirroring
+ * Rust's `KnownHosts`/`HostStatus` (`crates/wsh-client/src/known_hosts.rs`).
+ * Pins `ServerHello.host_fingerprint` (spec/wsh-v1.yaml, wsh #59) -- no
+ * `wsh-server` release populates that field yet, so this has nothing
+ * authoritative to verify against for any real server today. See the
+ * class doc comment in `known-hosts.mjs` for the full reasoning.
+ */
+export class WshKnownHosts {
+  constructor(opts?: { storage?: WshKnownHostsStorage; storageKey?: string });
+
+  /** Verify a host's fingerprint against the stored record. */
+  verifyHost(host: string, fingerprint: string): WshHostVerifyResult;
+
+  /** Add or update a host's fingerprint. */
+  addHost(host: string, fingerprint: string): void;
+
+  /** Remove a host entry. Returns true if an entry was removed. */
+  removeHost(host: string): boolean;
+
+  /** List all known hosts and their fingerprints. */
+  list(): Array<{ host: string; fingerprint: string }>;
+}
+
 // ============================================================================
 // file-transfer.mjs -- WshFileTransfer
 // ============================================================================
@@ -1885,12 +2129,21 @@ export interface WshFileUploadResult {
   bytesTransferred: number;
 }
 
-/** File listing entry. */
+/**
+ * File listing entry (wsh #59: generated from spec/wsh-v1.yaml's
+ * `FileEntry` nested type -- the same shape `crates/wsh-core`'s Rust
+ * `FileEntry` struct is generated from, so a directory entry can no longer
+ * describe a symlink as a plain file in one implementation and not the
+ * other). `modified` is converted from the wire's Unix epoch seconds into
+ * a `Date` for JS ergonomics. `symlinkTarget` is only present when
+ * `type === 'symlink'`.
+ */
 export interface WshFileListEntry {
   name: string;
   size: number;
-  modified: string;
+  modified: Date;
   type: 'file' | 'directory' | 'symlink' | 'device' | 'pipe' | 'socket';
+  symlinkTarget?: string;
 }
 
 /**

package/src/index.mjs

@@ -35,6 +35,7 @@ export {
   nodeAnnounce, nodeRedirect,
   sessionGrant, sessionRevoke,
   fileOp, fileResult, fileChunk,
+  authorizedKeyAdd, authorizedKeyResult,
   policyEval, policyResult, policyUpdate,
   terminalConfig,
   msgName, isValidMessage,
@@ -42,6 +43,7 @@ export {
 
 // Auth + crypto
 export {
+  isEd25519Supported,
   generateKeyPair, exportPublicKeyRaw, exportPublicKeySSH,
   importPublicKeyRaw, exportPrivateKeyPKCS8, importPrivateKeyPKCS8,
   sign, verify, buildTranscript, signChallenge, verifyChallenge,
@@ -51,7 +53,10 @@ export {
 } from './auth.mjs';
 
 // Transport
-export { WshTransport, WebTransportTransport, dispatchSerially, SerialQueue } from './transport.mjs';
+export {
+  WshTransport, WebTransportTransport, dispatchSerially, SerialQueue,
+  parseCertificateHash, normalizeWebTransportOptions,
+} from './transport.mjs';
 export { WebSocketTransport, WS_FRAME_TYPE } from './transport-ws.mjs';
 
 // QMux (QUIC-v1 frames over an ordered byte stream, draft-ietf-quic-qmux-02)
@@ -68,11 +73,14 @@ export {
 // Session + Client
 export { WshSession } from './session.mjs';
 export { WshVirtualSessionBackend, normalizeSessionData } from './virtual-session.mjs';
-export { WshClient } from './client.mjs';
+export { WshClient, MCP_CALL_ID_FEATURE } from './client.mjs';
 
 // Key storage
 export { WshKeyStore } from './keystore.mjs';
 
+// Host identity (TOFU) -- wsh #59
+export { WshKnownHosts } from './known-hosts.mjs';
+
 // File transfer
 export { WshFileTransfer } from './file-transfer.mjs';
 

package/src/known-hosts.mjs

@@ -0,0 +1,139 @@
+/**
+ * WshKnownHosts — trust-on-first-use (TOFU) host-identity store for the
+ * browser SDK (wsh #59).
+ *
+ * ## Why this exists, and why it is not yet load-bearing
+ *
+ * wsh #59 asked for a decision on host identity: TOFU *policy* (when to
+ * prompt, how long to trust) is legitimately per-implementation, but the
+ * *host identity record* -- what a fingerprint covers, how it is computed,
+ * what counts as "the same host" -- must not be invented twice. This class
+ * mirrors Rust's `KnownHosts`/`HostStatus`
+ * (`crates/wsh-client/src/known_hosts.rs`) in shape and semantics --
+ * `verifyHost`/`addHost`/`removeHost`/`list`, keyed by a host label,
+ * storing one fingerprint per host -- so the browser gets the same
+ * mechanism rather than a second, differently-shaped answer arrived at
+ * later under pressure.
+ *
+ * What it pins is `ServerHello.host_fingerprint` (spec/wsh-v1.yaml, added
+ * by this same change): the server's own persistent Ed25519 host-identity
+ * key, SHA-256-fingerprinted the same way `fingerprint()` in `auth.mjs`
+ * already fingerprints user/peer keys. That field is new spec surface,
+ * not new server behavior -- no `wsh-server` release populates it yet.
+ * Minting and persisting a server host keypair is a separate,
+ * security-sensitive feature this change does not implement (see the
+ * wsh #59 PR description for the full reasoning). Until a server
+ * populates it, `verifyHost()` has nothing authoritative to check for any
+ * real deployment -- exactly the same degraded state Rust's own
+ * `verify_host_key` is in today when it falls back to `fingerprints[0]`
+ * (an authorized *client* key, not a host identity -- see that fallback's
+ * comment in `client.rs`). This store does not paper over that; a caller
+ * that gets `'unknown'` back from every real server today is seeing the
+ * honest state of host verification in this protocol version, not a bug
+ * in this class.
+ *
+ * The README's `serverCertificateHashes` pinning
+ * (see "Pinning a Self-Signed Certificate") is a different mechanism: it
+ * pins a certificate supplied *per connection*, decided by the caller in
+ * advance -- it is not a persisted record of what a host presented last
+ * time, so it does not already solve TOFU. `WshKnownHosts` is the
+ * missing persisted-record half.
+ *
+ * ## Storage
+ *
+ * Pluggable (defaults to `localStorage` when available, else an
+ * in-memory `Map` that does not survive a page reload) since "persist
+ * trust across sessions" needs a browser storage API this package has
+ * never assumed before. Pass `{ storage }` with a `getItem`/`setItem`/
+ * `removeItem` interface (the `Storage` interface `localStorage`
+ * already implements) to use IndexedDB-via-adapter, `sessionStorage`,
+ * or anything else.
+ */
+
+const STORAGE_KEY = 'wsh:known-hosts:v1';
+
+/** In-memory fallback storage, used when no persistent storage is available or injected. */
+class MemoryStorage {
+  #map = new Map();
+  getItem(key) { return this.#map.has(key) ? this.#map.get(key) : null; }
+  setItem(key, value) { this.#map.set(key, value); }
+  removeItem(key) { this.#map.delete(key); }
+}
+
+function defaultStorage() {
+  if (typeof localStorage !== 'undefined' && localStorage) return localStorage;
+  return new MemoryStorage();
+}
+
+export class WshKnownHosts {
+  #storage;
+  #storageKey;
+
+  /**
+   * @param {object} [opts]
+   * @param {{getItem: function, setItem: function, removeItem: function}} [opts.storage]
+   *   Storage backend (defaults to `localStorage` if present, else an
+   *   in-memory `Map` scoped to this instance).
+   * @param {string} [opts.storageKey] - Override the storage key (useful
+   *   for isolating multiple instances/tests under one storage backend).
+   */
+  constructor({ storage, storageKey = STORAGE_KEY } = {}) {
+    this.#storage = storage || defaultStorage();
+    this.#storageKey = storageKey;
+  }
+
+  /**
+   * Verify a host's fingerprint against the stored record.
+   *
+   * @param {string} host - Host label (e.g. "example.com:4422")
+   * @param {string} fingerprint - Hex SHA-256 fingerprint to check
+   * @returns {{ status: 'known' | 'unknown' | 'changed', expected?: string }}
+   */
+  verifyHost(host, fingerprint) {
+    const entries = this.#load();
+    if (!(host in entries)) {
+      return { status: 'unknown' };
+    }
+    if (entries[host] === fingerprint) {
+      return { status: 'known' };
+    }
+    return { status: 'changed', expected: entries[host] };
+  }
+
+  /** Add or update a host's fingerprint. */
+  addHost(host, fingerprint) {
+    const entries = this.#load();
+    entries[host] = fingerprint;
+    this.#save(entries);
+  }
+
+  /** Remove a host entry. Returns true if an entry was removed. */
+  removeHost(host) {
+    const entries = this.#load();
+    if (!(host in entries)) return false;
+    delete entries[host];
+    this.#save(entries);
+    return true;
+  }
+
+  /** List all known hosts and their fingerprints. */
+  list() {
+    const entries = this.#load();
+    return Object.entries(entries).map(([host, fingerprint]) => ({ host, fingerprint }));
+  }
+
+  #load() {
+    const raw = this.#storage.getItem(this.#storageKey);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  #save(entries) {
+    this.#storage.setItem(this.#storageKey, JSON.stringify(entries));
+  }
+}