@johnhenry/wsh 0.17.0 → 0.17.1

package/README.md

@@ -1,15 +1,40 @@
 # @johnhenry/wsh
 
-Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.me/wsh/)
-
 > Previously published as `wsh-upon-star` (last release: 0.1.1, now deprecated).
-> Renamed to `@johnhenry/wsh` and restarted at 0.0.0 on import into the
-> @johnhenry family — a new name and era, not a maturity signal.
+> Renamed to `@johnhenry/wsh` on import into the @johnhenry family. Unlike
+> other packages in this family, wsh did **not** restart its version at
+> `0.0.0` on adoption — it was already a mature, actively-depended-upon
+> release, so versioning continued forward and now stands at `0.17.0`. This
+> is a deliberate, permanent exception to the family's usual 0.0.0-restart
+> convention, not an oversight.
+
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fwsh.svg)](https://www.npmjs.com/package/@johnhenry/wsh)
+[![CI](https://github.com/johnhenry/wsh/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/wsh/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fwsh.svg)](LICENSE)
+
+Full documentation: [opensource.johnhenry.me/wsh](https://opensource.johnhenry.me/wsh/)
 
 Browser-native remote command execution over WebTransport/WebSocket with Ed25519 authentication.
 
 wsh is a pure-JS client library that connects browsers to remote shells. It implements its own binary protocol — CBOR messages over QMux-multiplexed WebSocket or native WebTransport streams — with Ed25519 challenge-response auth, session management, and MCP tool bridging.
 
+## Contents
+
+- [Install](#install)
+- [Features](#features)
+- [Wire Protocol: QMux](#wire-protocol-qmux)
+- [Quick Start](#quick-start)
+- [One-Shot Command Execution](#one-shot-command-execution)
+- [Attach and Resume](#attach-and-resume)
+- [Pinning a Self-Signed Certificate](#pinning-a-self-signed-certificate)
+- [API Overview](#api-overview)
+- [Protocol Specification](#protocol-specification)
+- [Rust implementation](#rust-implementation)
+- [Security model](#security-model)
+- [Browser Compatibility](#browser-compatibility)
+- [Family](#family)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -34,9 +59,22 @@ Or via CDN:
 - **Reverse mode** -- register as a peer (via a signed peer record) and accept incoming connections through a relay
 - **File transfer** -- scp-like upload/download as `FileChunk` control messages in 64KB chunks
 - **MCP bridge** -- discover and invoke remote MCP tools through the control channel
-- **Session recording** -- asciicast v2 compatible recording and playback with seek/pause/resume
+- **Session recording** -- own JSON schema (not asciicast v2 -- see note below) recording and playback with seek/pause/resume
 - **Key management** -- IndexedDB storage with OPFS encrypted backup (PBKDF2 + AES-256-GCM)
-- **95 message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, and more
+- **97 message types** -- handshake, channel, gateway, guest sharing, compression negotiation, copilot, policy, authorized-key management, and more
+
+> **Session recording is not asciicast v2.** Both `SessionRecorder`
+> implementations capture more than asciicast v2's three event codes
+> (`o`/`i`/`r`) can represent -- session lifecycle events (`open`/`exit` in
+> JS; `Start`/`Exit`/`Snapshot` in Rust) have no asciicast v2 equivalent,
+> and dropping them wasn't worth it just to match the format. The JS and
+> Rust recorders also use two different, mutually incompatible schemas from
+> each other (neither is asciicast v2's newline-delimited-JSON shape).
+> `RecordingExport`'s `format: "asciicast"` option is accepted on the wire
+> but not yet implemented server-side -- requesting it currently returns
+> the same custom JSONL as `format: "jsonl"`. If interop with standard
+> asciicast players (`asciinema play`, etc.) is wanted, that needs a real
+> (lossy -- lifecycle events would be dropped) export path, not a rename.
 
 ## Wire Protocol: QMux
 
@@ -208,7 +246,7 @@ so options the platform gains later need no change here.
 | `WshKeyStore` | Ed25519 key management via IndexedDB + OPFS encrypted backup |
 | `WshFileTransfer` | File upload/download over dedicated streams |
 | `WshMcpBridge` | Remote MCP tool discovery and invocation |
-| `SessionRecorder` | Record PTY I/O with timestamps (asciicast v2) |
+| `SessionRecorder` | Record PTY I/O with timestamps (own schema, not asciicast v2) |
 | `SessionPlayer` | Replay recordings with original timing |
 | `generateKeyPair()` | Create Ed25519 key pair via Web Crypto |
 | `signChallenge()` | Build transcript + sign for auth handshake |
@@ -221,7 +259,7 @@ so options the platform gains later need no change here.
 
 | Export | Description |
 |--------|-------------|
-| `MSG` | 95 message type constants (hex opcodes) |
+| `MSG` | 97 message type constants (hex opcodes) |
 | `CHANNEL_KIND` | Channel types: `pty`, `exec`, `meta`, `file`, `tcp`, `udp`, `job` |
 | `AUTH_METHOD` | Auth methods: `pubkey`, `password` |
 | `cborEncode` / `cborDecode` | CBOR codec (maps, arrays, strings, ints, bytes, bools, null, floats) |
@@ -254,6 +292,26 @@ Four crates, workspace-versioned at `0.1.0`:
 | `wsh-cli` | binary (`wsh`) | SSH-like CLI: connect, exec, scp-style copy, reverse tunnels, key management |
 | `wsh-server` | binary (`wsh-server`) | Server: WebTransport/WebSocket listener, real PTY sessions (`portable-pty`), relay/reverse-connect, WISP bridging |
 
+### Capability matrix: JS SDK vs Rust CLI/client
+
+Two implementations of one protocol will always have *some* asymmetry --
+the question wsh #59 asks is whether it is visible and deliberate, or
+discovered by accident. This table is that answer, made explicit rather
+than left to be found.
+
+| Capability | JS SDK (browser) | Rust CLI/client | Unified via |
+|---|---|---|---|
+| Directory listing (`list`) | `WshFileTransfer.list()` | `wsh_client::file_transfer::list()`, `wsh ls`, `wsh sftp` | **Wire-unified**: `FileOp`/`FileResult` with the generated `FileEntry` type (wsh #59) -- both languages decode the same shape, including symlink targets |
+| Upload/download | `WshClient.upload()`/`.download()` | `file_transfer::upload()`/`download()`, `wsh scp` | **Wire-unified**: `FileChunk` over a `'file'`-kind channel (wsh #13) |
+| Remove a remote file | `WshClient.fileRemove()` | `file_transfer::remove()`, `wsh sftp`'s `rm` | **Wire-unified**: `FileOp`/`FileResult` (`op: "remove"`) -- refused today by every `wsh-server` release ("not yet implemented"), the same refusal on both sides |
+| Install an authorized key | `WshClient.addAuthorizedKey()` | `wsh_client::WshClient::add_authorized_key()`, `wsh copy-id` | **Wire-unified** (wsh #59): `AuthorizedKeyAdd`/`AuthorizedKeyResult`, replacing a Rust-CLI-only shell command with a message every implementation can send |
+| Host identity / TOFU | `WshKnownHosts` (localStorage-backed) | `KnownHosts`/`HostStatus` (`~/.wsh/known_hosts`-backed) | **Record unified, policy is not** (wsh #59): both pin `ServerHello.host_fingerprint`, a field no `wsh-server` release populates yet (see [Security](#security)). *When* to trust, prompt, or persist is deliberately left per-implementation -- a browser and a CLI have different UX for "first time seeing this host" |
+| Interactive shell UI | none -- this SDK is a protocol client, not a terminal emulator; pair with xterm.js/ghostty-web | `wsh connect`, `wsh sftp` (line-oriented REPL) | **Deliberately not unified** -- a browser embeds a terminal widget the host page owns; a CLI process owns its own TTY |
+| Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()` | `wsh reverse`, `wsh agent` (persistent, with startup-unit install) | **Wire-unified** (registration, discovery, signed peer records); **daemonization is CLI-only** -- a browser tab cannot be a background OS service |
+| Post-quantum E2E (experimental) | `initiateE2E()` (WebCrypto ML-KEM-768 or `@noble/post-quantum` fallback) | `E2eKeyExchange` (`ml-kem` crate) | **Wire-unified** algorithm and transcript; key material backends differ by platform necessity |
+| Session recording/replay | `SessionRecorder`/`SessionPlayer` (asciicast v2) | none | **JS-only** -- no current Rust consumer needs playback; the format itself (asciicast v2) is not proprietary if one is added later |
+| Self-signed cert pinning | `serverCertificateHashes` (WebTransport option) | N/A -- Rust dials a cert its own TLS stack already trusts, or `--generate-cert`'s self-signed cert out of band | **Deliberately not unified** -- this is a browser-specific WebTransport API shape, not a wire-protocol concept |
+
 ### Build and test
 
 ```sh
@@ -307,24 +365,71 @@ plus one `SHA256SUMS` file covering every archive in the release. These
 names are a stable contract other repos (clawser) pin and download by --
 do not change them without coordinating downstream.
 
-## Security
+## Security model
+
+wsh's protocol draws its line at authentication and message integrity: what
+it guarantees is that a handshake and its messages are who and what they
+claim to be. It does not guarantee confidentiality of every auth method, or
+that a server's identity has actually been pinned yet -- both are called
+out explicitly below rather than left to be discovered.
+
+**What wsh guarantees:**
 
-- **Auth transcript binding** -- challenge signatures cover
+- **Auth transcript binding.** Challenge signatures cover
   `SHA-256("wsh-v1\0" || lp(username) || lp(session_id) || nonce || channel_binding)`,
   so a signature can't be replayed against a different session or relabeled
   to a different username.
-- **Signed peer records** -- reverse-mode registration is self-signed by the
+- **Signed peer records.** Reverse-mode registration is self-signed by the
   peer's identity key (the libp2p RFC 0002/0003 pattern), in a signing
   domain separate from the auth challenge. `listPeers()` verifies every
   entry client-side and reports a `verified` boolean, independent of
   trusting the relay.
-- **Hybrid post-quantum E2E (experimental)** --
-  `initiateE2E(sessionId, 'X25519+ML-KEM-768')` combines X25519 ECDH with
-  ML-KEM-768 via HKDF-SHA256, preferring native WebCrypto ML-KEM-768 (Node
-  24.7+) with the optional `@noble/post-quantum` pure-JS fallback, and
-  falling back to classical X25519 automatically when the peer can't do
-  hybrid (check the returned `hybrid` flag). The derived AES-256-GCM key is
-  not yet wired to actual frame encryption.
+
+**What is still yours:**
+
+- **Hybrid post-quantum E2E is experimental and not fully wired (in
+  progress).** `initiateE2E(sessionId, 'X25519+ML-KEM-768')` combines
+  X25519 ECDH with ML-KEM-768 via HKDF-SHA256, preferring native WebCrypto
+  ML-KEM-768 (Node 24.7+) with the optional `@noble/post-quantum` pure-JS
+  fallback, and falling back to classical X25519 automatically when the
+  peer can't do hybrid (check the returned `hybrid` flag). The derived
+  AES-256-GCM key is not yet wired to actual frame encryption by default --
+  treat `initiateE2E` as key agreement, not confidentiality, unless you've
+  separately confirmed the session has sealing enabled.
+- **Host identity (TOFU) has a known, named gap (wsh #59).**
+  `ServerHello.host_fingerprint` is the spec's formal host-identity slot:
+  the SHA-256 fingerprint of a server's persistent Ed25519 host key, meant
+  to be pinned across connections the way SSH pins a host key. **No
+  `wsh-server` release populates this field yet** -- minting and
+  persisting a server host keypair is a separate, security-sensitive
+  feature, deliberately not bundled into this change. Both clients ship
+  the store this field is for: `WshKnownHosts` (JS, `localStorage`-backed)
+  and `KnownHosts` (Rust, `~/.wsh/known_hosts`-backed) have matching
+  verify/add/remove/list semantics. Today, against every real server,
+  both report every host as unverified for host-identity purposes; the
+  Rust client additionally still falls back to `fingerprints[0]` (an
+  *authorized client key* this server happens to have, not this server's
+  own identity -- see `ServerHello.fingerprints`' doc comment in
+  `spec/wsh-v1.yaml`) with a logged warning, for backward compatibility.
+  Do not treat either store as a MITM defense until a server actually
+  populates `host_fingerprint`. `serverCertificateHashes` (below) is a
+  different, narrower mechanism -- it pins a certificate supplied *per
+  connection*, not a persisted record of what a host presented last time.
+- **Password auth has no confidentiality of its own -- it relies entirely
+  on the transport.** `AUTH_METHOD.PASSWORD` sends the password as a plain
+  string inside the `auth` control message (`client.mjs`'s `#performAuth()`
+  calls `sendControl(authMsg({ method: AUTH_METHOD.PASSWORD, password }))`)
+  -- there is no client-side hashing, salting, or key derivation before it
+  goes on the wire. Its confidentiality is entirely a function of whether
+  the underlying connection is encrypted: fine over `wss:`/WebTransport
+  against a certificate the client actually trusts (CA-signed, or pinned
+  via `serverCertificateHashes`), but sent in the clear if the connection
+  is a plain, unencrypted `ws:`. Browsers block that combination from an
+  `https:` page as mixed content (see "Pinning a Self-Signed Certificate"
+  above), but nothing in this protocol or client stops a non-browser
+  caller (Node, the Rust CLI) from dialing `ws://` directly. Prefer pubkey
+  auth, or make sure the transport is actually encrypted, before sending a
+  password.
 
 ## Browser Compatibility
 
@@ -403,6 +508,24 @@ browser the optional `@noble/post-quantum` dependency is what actually
 runs, loaded dynamically by `src/mlkem.mjs`. Treat it as required, not
 optional, if you want the hybrid handshake on the web today.
 
+## Family
+
+wsh isn't just a standalone remote-shell client -- its `WshClient` is the
+designed transport backing one sibling package's network gateway, and
+`WshClient`'s connected/authenticated shape is a drop-in for that sibling's
+injected-client extension point.
+
+- **[`@johnhenry/browsermesh-netway`](https://github.com/johnhenry/browsermesh)**
+  -- browsermesh-netway's `GatewayBackend` takes a `wshClient` in its
+  constructor and proxies every network operation (socket open/send/close)
+  through it via `sendControl()`, once the client reaches the
+  `'authenticated'` state (`isReady()` checks exactly that). This is a real,
+  verified dependency on wsh's client shape -- `GatewayBackend` is
+  duck-typed against a `WshClient` instance, not declared as an npm
+  dependency -- not a thematic pairing; see
+  `packages/browsermesh-netway/src/gateway-backend.mjs` in the browsermesh
+  repo. wsh itself has no dependency in the other direction.
+
 ## License
 
 MIT

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Web Shell — browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    }
   },
   "types": "./src/index.d.ts",
   "files": [
@@ -19,11 +22,13 @@
   "devDependencies": {
     "@fails-components/webtransport": "^1.6.4",
     "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",
+    "typescript": "^7.0.0",
     "ws": "^8.21.0"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "test:rust": "node --test test/rust/*.test.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "codegen": "node spec/codegen.mjs",
     "codegen:check": "node scripts/codegen-check.mjs",
     "examples": "for f in examples/0*.mjs; do echo \"== $f\" && node \"$f\" || exit 1; done",
@@ -53,7 +58,7 @@
   },
   "author": "John Henry",
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=26.0.0"
   },
   "homepage": "https://opensource.johnhenry.me/wsh/"
 }

package/src/client.mjs

@@ -29,6 +29,7 @@ import {
   keyExchange as keyExchangeMsg,
   fileOp as fileOpMsg,
   fileChunk as fileChunkMsg,
+  authorizedKeyAdd as authorizedKeyAddMsg,
   policyEval as policyEvalMsg, policyUpdate as policyUpdateMsg,
   detach as detachMsg,
   sessionListRequest as sessionListRequestMsg,
@@ -1738,6 +1739,45 @@ export class WshClient {
   /** Rename a remote file or directory. */
   async fileRename(oldPath, newPath, timeout) { return this.fileOperation('rename', oldPath, {}, timeout); }
 
+  // ── Authorized-key management (wsh #59) ───────────────────────────
+
+  /**
+   * Install a raw 32-byte Ed25519 public key into the remote host's
+   * ~/.wsh/authorized_keys via the AuthorizedKeyAdd protocol message.
+   *
+   * Replaces `wsh copy-id`'s CLI-only, shell-command-built approach
+   * (`crates/wsh-cli/src/commands/copy_id.rs`) with a real protocol
+   * message every implementation can call -- including this one, the
+   * browser SDK, which previously had no way to install a key at all
+   * (no shell channel to build a command string for). See copy_id.rs's
+   * doc comment for the full security reasoning: an authenticated
+   * connection already has unrestricted exec/file access to this exact
+   * file, so this adds no new privilege boundary.
+   *
+   * Idempotent: installing an already-present key resolves
+   * `{ added: false }` rather than duplicating the line or erroring.
+   *
+   * @param {Uint8Array} publicKeyRaw - Raw 32-byte Ed25519 public key
+   * @param {string} [comment] - Trailing comment for the authorized_keys line
+   * @param {number} [timeout=10000]
+   * @returns {Promise<{ added: boolean }>}
+   */
+  async addAuthorizedKey(publicKeyRaw, comment, timeout = DEFAULT_OPEN_TIMEOUT) {
+    this.#assertAuthenticated('addAuthorizedKey');
+    await this.#transport.sendControl(
+      authorizedKeyAddMsg({ publicKey: publicKeyRaw, comment })
+    );
+    const result = await this.#waitForMessage(
+      [MSG.AUTHORIZED_KEY_RESULT],
+      timeout,
+      'Timed out waiting for authorized-key-add result'
+    );
+    if (!result.success) {
+      throw new Error(result.error_message || 'key installation refused');
+    }
+    return { added: !!result.added };
+  }
+
   // ── Policy Engine ─────────────────────────────────────────────────
 
   /**

package/src/file-transfer.mjs

@@ -3,38 +3,36 @@
  *
  * Uploads and downloads delegate to the underlying client's upload()/
  * download() (FileChunk control messages over a 'file'-kind channel —
- * see client.mjs). list() is a separate helper that runs `ls -la` over
- * a plain exec channel.
+ * see client.mjs). list() (wsh #59) delegates to the client's fileList(),
+ * which sends a structured FileOp{op:"list"} and reads the typed
+ * FileResult.entries -- the same wire path upload/download already use
+ * for moving bytes, now extended to directory listings.
+ *
+ * Before wsh #59, list() ran `ls -la` over a plain exec channel and
+ * parsed the text output client-side -- a private, JS-only convention
+ * the Rust client had no equivalent of at all (see wsh #58/#59, and the
+ * FileEntry nested type in spec/wsh-v1.yaml this now shares with Rust).
  */
 
-import { MSG, open, CHANNEL_KIND } from './messages.mjs';
-import { waitForControlMessage } from './control-listener.mjs';
-
 /** Default timeout for waiting on control messages (30 seconds). */
 const RESPONSE_TIMEOUT_MS = 30_000;
 
 export class WshFileTransfer {
   /**
    * @type {{
-   *   upload: function, download: function,
-   *   sendControl: function, openStream: function, onControl: function,
+   *   upload: function, download: function, fileList: function,
    * }}
    */
   #client;
 
   /**
-   * @param {object} client - A WshClient (or any object exposing upload()/
-   *   download() with the same signatures — those are used directly for
-   *   upload/download). list() additionally needs, for the underlying exec
-   *   channel it runs `ls -la` over:
-   *   - sendControl(msg): send a control message
-   *   - openStream(): open a new bidirectional stream
-   *   - onControl: settable callback for incoming control messages
-   *     (or a method to add a listener — see _waitForMessage)
-   *
-   *   Only `list()` needs the control-channel members, so they are checked
-   *   there rather than here: uploading and downloading through a client
-   *   that has `upload()`/`download()` and nothing else stays valid.
+   * @param {object} client - A WshClient (or any object exposing the same
+   *   methods used below). `upload()`/`download()` are used directly for
+   *   file transfer; `list()` uses `fileList()` (the structured
+   *   FileOp/FileResult request-response helper already on WshClient).
+   *   Each method checks for the members it specifically needs, so a
+   *   client exposing only `upload()`/`download()` (and nothing else)
+   *   stays valid for those two calls.
    */
   constructor(client) {
     if (!client) throw new Error('WshFileTransfer requires a client');
@@ -97,156 +95,47 @@ export class WshFileTransfer {
   }
 
   /**
-   * List files at a remote path by executing `ls -la` via the client.
+   * List files at a remote path over the structured file channel (wsh #59):
+   * sends `FileOp{op:"list"}` via the client's `fileList()` and reads the
+   * typed `FileResult.entries` -- the same `FileEntry` shape
+   * `crates/wsh-core`'s Rust client is generated from, so a symlink can't
+   * be reported as a plain file here and correctly here-and-there.
    *
-   * This uses a standard exec channel rather than the file transfer protocol,
-   * parsing the output of `ls -la` into structured entries.
+   * A refusal (unimplemented op, unauthorized fs capability, no such
+   * directory) throws -- it is never coerced into an empty array, so a
+   * caller can't mistake "refused" for "empty directory" (wsh #58).
    *
    * @param {string} remotePath - Directory path on the remote host
-   * @returns {Promise<Array<{ name: string, size: number, modified: string, type: string }>>}
+   * @param {object} [opts]
+   * @param {number} [opts.timeout] - Timeout in ms for the server response
+   * @returns {Promise<Array<{
+   *   name: string, size: number, modified: Date,
+   *   type: 'file'|'directory'|'symlink'|'device'|'pipe'|'socket',
+   *   symlinkTarget?: string,
+   * }>>}
    */
-  async list(remotePath) {
+  async list(remotePath, { timeout = RESPONSE_TIMEOUT_MS } = {}) {
     if (!remotePath || typeof remotePath !== 'string') {
       throw new Error('remotePath is required');
     }
-    if (typeof this.#client.sendControl !== 'function' || typeof this.#client.openStream !== 'function') {
+    if (typeof this.#client.fileList !== 'function') {
       throw new TypeError(
-        'WshFileTransfer.list() requires a client exposing sendControl() and openStream() (e.g. WshClient)'
+        'WshFileTransfer.list() requires a client exposing fileList() (e.g. WshClient)'
       );
     }
 
-    // Use an exec channel to run ls
-    const openMsg = open({
-      kind: CHANNEL_KIND.EXEC,
-      command: `ls -la ${this._shellEscape(remotePath)}`,
-    });
-
-    await this.#client.sendControl(openMsg);
-
-    const response = await this._waitForMessage(
-      (msg) => msg.type === MSG.OPEN_OK || msg.type === MSG.OPEN_FAIL,
-      RESPONSE_TIMEOUT_MS
-    );
-
-    if (response.type === MSG.OPEN_FAIL) {
-      throw new Error(`List failed: ${response.reason || 'unknown reason'}`);
-    }
-
-    // Read the output stream
-    const stream = await this.#client.openStream();
-    const reader = stream.readable.getReader();
-    const chunks = [];
-
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-      }
-    } finally {
-      reader.releaseLock();
-    }
-
-    const output = new TextDecoder().decode(this._concatChunks(chunks));
-    return this._parseLsOutput(output);
-  }
-
-  // ── Internal helpers ──────────────────────────────────────────────
-
-  /**
-   * Wait for a control message matching a predicate.
-   *
-   * Temporarily hooks into the client's control message flow and resolves
-   * when a matching message arrives (or rejects on timeout).
-   *
-   * @param {function(object): boolean} predicate
-   * @param {number} timeoutMs
-   * @returns {Promise<object>}
-   */
-  _waitForMessage(predicate, timeoutMs) {
-    return waitForControlMessage(this.#client, predicate, timeoutMs, 'File transfer response');
-  }
-
-  /**
-   * Concatenate an array of Uint8Arrays into one.
-   *
-   * @param {Uint8Array[]} chunks
-   * @param {number} [totalLength] - Pre-computed total, avoids re-summing
-   * @returns {Uint8Array}
-   */
-  _concatChunks(chunks, totalLength) {
-    if (chunks.length === 0) return new Uint8Array(0);
-    if (chunks.length === 1) return chunks[0];
-
-    const total = totalLength ?? chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return result;
-  }
-
-  /**
-   * Parse the output of `ls -la` into structured entries.
-   *
-   * Expected format per line:
-   *   drwxr-xr-x 2 user group  4096 Jan 15 12:00 dirname
-   *   -rw-r--r-- 1 user group 12345 Jan 15 12:00 filename.txt
-   *
-   * @param {string} output
-   * @returns {Array<{ name: string, size: number, modified: string, type: string }>}
-   */
-  _parseLsOutput(output) {
-    const lines = output.split('\n').filter((l) => l.trim());
-    const entries = [];
-
-    for (const line of lines) {
-      // Skip the "total" header line
-      if (line.startsWith('total ')) continue;
-
-      // ls -la columns: perms links owner group size month day time name
-      const parts = line.split(/\s+/);
-      if (parts.length < 9) continue;
-
-      const perms = parts[0];
-      const size = parseInt(parts[4], 10) || 0;
-      const month = parts[5];
-      const day = parts[6];
-      const time = parts[7];
-      // Name may contain spaces — rejoin everything from column 8 onward
-      const name = parts.slice(8).join(' ');
-
-      // Skip . and .. entries
-      if (name === '.' || name === '..') continue;
+    const result = await this.#client.fileList(remotePath, timeout);
 
-      // Determine type from permission string first character
-      let type = 'file';
-      if (perms.startsWith('d')) type = 'directory';
-      else if (perms.startsWith('l')) type = 'symlink';
-      else if (perms.startsWith('c') || perms.startsWith('b')) type = 'device';
-      else if (perms.startsWith('p')) type = 'pipe';
-      else if (perms.startsWith('s')) type = 'socket';
-
-      entries.push({
-        name,
-        size,
-        modified: `${month} ${day} ${time}`,
-        type,
-      });
+    if (!result.success) {
+      throw new Error(result.error_message || `List failed: refused for ${remotePath}`);
     }
 
-    return entries;
-  }
-
-  /**
-   * Basic shell escaping for a path argument.
-   * @param {string} str
-   * @returns {string}
-   */
-  _shellEscape(str) {
-    // Wrap in single quotes, escaping any embedded single quotes
-    return "'" + str.replace(/'/g, "'\\''") + "'";
+    return (result.entries || []).map((entry) => ({
+      name: entry.name,
+      size: entry.size,
+      modified: new Date(entry.modified * 1000),
+      type: entry.type,
+      ...(entry.symlink_target !== undefined ? { symlinkTarget: entry.symlink_target } : {}),
+    }));
   }
 }

package/src/index.d.ts

@@ -778,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;
 
@@ -789,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;
@@ -1649,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.
  *
@@ -1764,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.
    */
@@ -1993,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
 // ============================================================================
@@ -2015,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,
@@ -77,6 +78,9 @@ 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));
+  }
+}

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.