@johnhenry/wsh 0.16.1 → 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
@@ -28,14 +53,28 @@ Or via CDN:
 
 - **Ed25519 authentication** -- challenge-response via Web Crypto API with a transcript binding username and session id, SSH key format support
 - **Dual transport** -- WebTransport (native streams) and WebSocket (QMux-multiplexed streams) with identical API
+- **Self-signed certificate pinning** -- `serverCertificateHashes` on the WebTransport path, so page JavaScript can reach a server whose certificate no certificate authority signed
 - **CBOR encoding** -- compact binary wire format with length-prefixed framing
 - **Session management** -- open, attach, resume, detach, rename PTY/exec sessions, with session-scoped resume tokens and per-principal access grants
 - **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
 
@@ -127,6 +166,67 @@ await client.detach(session.sessionId);   // leave it running server-side
 await client.listRemoteSessions();        // sessions this key can see
 ```
 
+## Pinning a Self-Signed Certificate
+
+Both transports normally need a certificate a public certificate authority
+signed. On a LAN -- a phone talking to a desktop on `192.168.x.x`, a
+browser talking to a device on the same Wi-Fi -- there is no such
+certificate to be had, and a plaintext `ws://` from an `https://` page is
+blocked as mixed content.
+
+WebTransport is the one place in the web platform with an answer:
+`serverCertificateHashes` lets the page pin a specific certificate by
+SHA-256 digest, no certificate authority involved.
+
+```js
+// The digest can be raw bytes, base64, plain hex, or the colon-separated
+// hex `openssl x509 -fingerprint -sha256 -noout -in cert.pem` prints --
+// the whole `SHA256 Fingerprint=AB:CD:...` line is accepted as-is.
+await client.connect('https://192.168.1.20:4433/wsh', {
+  username: 'alice',
+  keyPair,
+  transport: 'wt',
+  webTransport: {
+    serverCertificateHashes: [
+      'SHA256 Fingerprint=A1:B2:C3:...',
+    ],
+  },
+});
+```
+
+`WebTransportTransport` also takes the same options directly, for use with
+`connectWithTransport()`:
+
+```js
+const transport = new WebTransportTransport({
+  serverCertificateHashes: [certDigestBytes],
+});
+```
+
+A malformed digest throws locally (`RangeError` for the wrong length,
+`TypeError` for an unrecognised shape) before any connection is
+attempted -- a wrong hash otherwise surfaces only as an opaque
+`WebTransportError` from `wt.ready`.
+
+The constraints are the platform's, not wsh's:
+
+- The URL must be `https:`; pinning is HTTP/3 only, with no HTTP/2 fallback.
+- The certificate must use an **ECDSA P-256** key and be valid for **at most
+  14 days**, so it has to be reissued on a schedule.
+- Connection pooling is disabled for a pinned connection.
+- Only `sha-256` is accepted as the algorithm.
+
+The option applies to the WebTransport rung of the transport ladder only.
+If the WebTransport attempt fails and the client falls back to WebSocket,
+that `wss:` connection is subject to the ordinary certificate-authority
+check again -- there is no WebSocket equivalent of certificate pinning.
+Pass `transport: 'wt'` if you would rather fail than fall back.
+
+Any other key in `webTransport` is forwarded to the `WebTransport`
+constructor verbatim (`congestionControl`, `allowPooling`,
+`requireUnreliable`, the `anticipatedConcurrentIncoming*Streams` hints),
+so options the platform gains later need no change here.
+
 ## API Overview
 
 ### Core Classes
@@ -136,7 +236,7 @@ await client.listRemoteSessions();        // sessions this key can see
 | `WshClient` | Full lifecycle client: connect, auth, sessions, reverse mode, MCP |
 | `WshSession` | Single PTY or exec channel with read/write/resize/signal |
 | `WshTransport` | Abstract transport base class |
-| `WebTransportTransport` | WebTransport implementation (native streams) |
+| `WebTransportTransport` | WebTransport implementation (native streams); takes `serverCertificateHashes` and other `WebTransport` options |
 | `WebSocketTransport` | WebSocket implementation (multiplexed virtual streams) |
 
 ### Utilities
@@ -146,18 +246,20 @@ await client.listRemoteSessions();        // sessions this key can see
 | `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 |
 | `signPeerRecord()` / `verifyPeerRecord()` | Sign / verify reverse-mode peer records |
 | `fingerprint()` | SHA-256 hex fingerprint of a public key |
+| `parseCertificateHash()` | Decode a certificate digest from hex / base64 / bytes |
+| `normalizeWebTransportOptions()` | Build a `WebTransportOptions` dictionary from loose input |
 
 ### Protocol
 
 | 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) |
@@ -172,38 +274,257 @@ The `spec/` directory contains the protocol definition:
 - `wsh-v1.md` -- human-readable protocol specification
 - `codegen.mjs` -- generates `messages.gen.mjs` from the YAML spec
 
-## Security
+## Rust implementation
+
+`crates/` is a native Rust implementation of the wsh protocol, moved into
+this repo from erisera-code/clawser on 2026-09-06 (with history, via `git
+subtree`) so it lives next to the JS client whose wire spec it implements
+instead of dragging its own toolchain and CI job into an unrelated
+browser-app repo. It was previously deleted from clawser by accident
+(2026-03-14) and restored (2026-07-05) before this move.
+
+Four crates, workspace-versioned at `0.1.0`:
+
+| Crate | Kind | Description |
+|-------|------|--------------|
+| `wsh-core` | library | Shared protocol types -- CBOR messages (generated, see below), codec, identity, auth, QMux |
+| `wsh-client` | library | Native Rust client -- WebTransport/WebSocket transports, sessions, file transfer, E2E |
+| `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
+cargo build --workspace
+cargo test --workspace
+```
+
+The Node-to-Rust cross-implementation tests (`test/rust/*.test.mjs`) spawn
+the real `wsh-server` binary and drive it with this repo's own JS client --
+they're kept out of the default `npm test` glob so JS-only contributors
+never need a Rust toolchain. Build the release binary first (or set
+`WSH_SERVER_BIN` to point at one), then:
+
+```sh
+cargo build --release -p wsh-server
+npm run test:rust
+```
+
+### Codegen: regenerate, don't hand-edit
+
+`crates/wsh-core/src/messages.gen.rs` is generated from `spec/wsh-v1.yaml`
+by `spec/codegen.mjs`, alongside the JS (`src/messages.gen.mjs`) and
+Markdown (`spec/wsh-v1.md`) outputs -- all three come from the same schema
+and must never be hand-edited. After changing `wsh-v1.yaml`:
+
+```sh
+npm run codegen        # regenerate all three outputs
+npm run codegen:check  # CI check: fails if any output has drifted from the schema
+```
+
+### Release binaries
+
+Tagging `rust-vX.Y.Z` (or running the `Release Rust binaries` workflow
+manually with a tag input) builds and publishes prebuilt `wsh-server` and
+`wsh-cli` binaries for four targets to a GitHub Release:
+
+- `x86_64-unknown-linux-gnu`
+- `aarch64-apple-darwin`
+- `x86_64-apple-darwin`
+- `i686-unknown-linux-musl` (the target clawser's demo-linux guest image needs)
+
+Each target produces two archives, each containing a single binary at the
+archive root:
+
+```
+wsh-server-<target>.tar.gz   # binary: wsh-server
+wsh-cli-<target>.tar.gz      # binary: wsh
+```
+
+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 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.
 
-- **Auth transcript binding** -- challenge signatures cover
+**What wsh guarantees:**
+
+- **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
 
-Requires a browser (or Node.js 24+) with:
+Requires a browser (or Node.js 24+) with `TextEncoder`/`TextDecoder`,
+`ReadableStream`/`WritableStream`, `WebSocket` (universal), and:
+
+### WebCrypto Ed25519 -- the real floor
 
-- Web Crypto API with Ed25519 support
-- WebSocket (all browsers)
-- WebTransport (Chrome 97+, Edge 97+, Firefox 114+)
-- TextEncoder/TextDecoder
-- ReadableStream/WritableStream
+This is what actually gates the library, because pubkey auth is not
+optional to the protocol. Roughly: **Safari 17+, Chrome/Edge 137+,
+Firefox 130+, Node 20+**.
+
+There is deliberately **no pure-JS fallback**. A JS Ed25519 needs the
+private scalar as ordinary bytes, which would give up the property
+`WshKeyStore` is built around -- keys are non-extractable `CryptoKey`
+objects by default, so a compromised page can *use* a key but cannot
+exfiltrate it. Trading that away on exactly the oldest, least-patched
+engines is the wrong direction, and doing it silently would be worse.
+
+Ask before you commit to pubkey auth:
+
+```js
+import { isEd25519Supported } from '@johnhenry/wsh';
+
+if (await isEd25519Supported()) {
+  await client.connect(url, { username, keyPair });
+} else {
+  await client.connect(url, { username, password });
+}
+```
 
-Hybrid ML-KEM-768 key exchange prefers native WebCrypto ML-KEM (Node 24.7+,
-some browsers); elsewhere the optional `@noble/post-quantum` dependency is
-loaded dynamically.
+`isEd25519Supported()` measures by generating a key rather than sniffing a
+version string, and memoizes. `generateKeyPair()` throws with an
+actionable message where support is missing, rather than passing the
+platform's "Unrecognized name" straight through.
+
+### WebTransport
+
+WebTransport is optional -- the transport ladder falls back to WebSocket.
+It matters if you want `serverCertificateHashes` (see [Pinning a
+Self-Signed Certificate](#pinning-a-self-signed-certificate)), which has
+no WebSocket equivalent.
+
+**Safari supports WebTransport, and more of it than Chromium does.**
+That is the opposite of the usual assumption, and the earlier version of
+this section propagated the assumption by listing only Chrome, Edge and
+Firefox. Measured on 2026-09-04, both engines on a `localhost` secure
+context:
+
+| | `WebTransport.prototype` members | Ed25519 | X25519 | ML-KEM-768 |
+|---|---|---|---|---|
+| WebKit -- Safari 26.5, iOS 26.5 simulator | **17** | OK | OK | fails (`TypeError`) |
+| Chromium 148, macOS | 10 | OK | OK | fails (`NotSupportedError`) |
+
+WebKit's extra seven are `congestionControl`, `reliability`, `draining`,
+`getStats`, `createSendGroup`, and the two
+`anticipatedConcurrentIncoming*Streams` hints; both engines have
+`datagrams`, both bidirectional and unidirectional stream creation, and
+`ready`/`closed`.
+
+Approximate first-support versions, which are *not* measured here: Chrome
+and Edge 97, Firefox 114, Safari 26. Below Safari 26, the ladder falls
+back to WebSocket.
+
+Both engines accept a `serverCertificateHashes` entry without a
+synchronous throw, but that is weak evidence on its own -- unknown WebIDL
+dictionary members are silently ignored, so acceptance does not prove the
+option is honoured. Confirming it needs a real HTTP/3 server presenting a
+matching short-lived certificate.
+
+### ML-KEM-768
+
+The hybrid post-quantum path prefers native WebCrypto ML-KEM (Node 24.7+).
+**No browser tested has it** -- it failed on both engines above -- so in a
+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
 

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.16.1",
+  "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": [
@@ -16,8 +19,18 @@
   "optionalDependencies": {
     "@noble/post-quantum": "^0.7.0"
   },
+  "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",
     "example:01": "node examples/01-frames-survive-fragmented-transport.mjs",
     "example:02": "node examples/02-tampered-challenge-fails-authentication.mjs",
@@ -45,7 +58,7 @@
   },
   "author": "John Henry",
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=26.0.0"
   },
   "homepage": "https://opensource.johnhenry.me/wsh/"
 }

package/src/auth.mjs

@@ -5,15 +5,77 @@
 
 import { PROTOCOL_VERSION } from './messages.mjs';
 
+// ── Capability detection ──────────────────────────────────────────────
+
+/** @type {Promise<boolean>|null} Memoized: the answer cannot change at runtime. */
+let ed25519Support = null;
+
+/**
+ * Whether this runtime's WebCrypto implements Ed25519.
+ *
+ * There is deliberately no pure-JS fallback behind this. A JS
+ * implementation needs the private scalar as ordinary bytes, which would
+ * quietly give up the property `WshKeyStore` is built around -- keys are
+ * non-extractable `CryptoKey` objects by default, so a compromised page
+ * can use a key but cannot exfiltrate it. Trading that away on exactly
+ * the oldest, least-patched engines is the wrong direction, and doing it
+ * silently is worse. So wsh's floor is WebCrypto Ed25519, and this is how
+ * an application asks about it before committing to pubkey auth:
+ *
+ * ```js
+ * if (await isEd25519Supported()) {
+ *   await client.connect(url, { username, keyPair });
+ * } else {
+ *   await client.connect(url, { username, password });   // AUTH_METHOD.PASSWORD
+ * }
+ * ```
+ *
+ * Measured directly rather than sniffed from a version string: `'Ed25519'`
+ * is accepted as an algorithm name by some engines that then fail at
+ * `generateKey`, so nothing short of generating a key is conclusive.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function isEd25519Supported() {
+  if (ed25519Support === null) {
+    ed25519Support = (async () => {
+      try {
+        await crypto.subtle.generateKey('Ed25519', false, ['sign', 'verify']);
+        return true;
+      } catch {
+        return false;
+      }
+    })();
+  }
+  return ed25519Support;
+}
+
 // ── Key Generation ────────────────────────────────────────────────────
 
 /**
  * Generate a new Ed25519 key pair.
+ *
+ * Throws where WebCrypto has no Ed25519 -- see `isEd25519Supported()` for
+ * why there is no fallback, and for how to check before you get here.
+ *
  * @param {boolean} [extractable=false] - Whether private key can be exported
  * @returns {Promise<CryptoKeyPair>} { publicKey, privateKey }
  */
 export async function generateKeyPair(extractable = false) {
-  return crypto.subtle.generateKey('Ed25519', extractable, ['sign', 'verify']);
+  try {
+    return await crypto.subtle.generateKey('Ed25519', extractable, ['sign', 'verify']);
+  } catch (err) {
+    // The platform's own message is typically "Unrecognized name" or a
+    // bare "Type error", neither of which says which algorithm, which
+    // library wanted it, or what a caller might do instead.
+    throw new Error(
+      'wsh requires WebCrypto Ed25519, which this runtime does not implement ' +
+      '(Safari 17+, Chrome/Edge 137+, Firefox 130+, Node 20+). Check ' +
+      'isEd25519Supported() first and fall back to password auth, or supply ' +
+      `a CryptoKeyPair from elsewhere. (${err?.message || err})`,
+      { cause: err }
+    );
+  }
 }
 
 // ── Export / Import ───────────────────────────────────────────────────