@johnhenry/wsh 0.16.1 → 0.17.0

package/README.md

@@ -28,6 +28,7 @@ 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
@@ -127,6 +128,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 +198,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
@@ -152,6 +214,8 @@ await client.listRemoteSessions();        // sessions this key can see
 | `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
 
@@ -172,6 +236,77 @@ The `spec/` directory contains the protocol definition:
 - `wsh-v1.md` -- human-readable protocol specification
 - `codegen.mjs` -- generates `messages.gen.mjs` from the YAML spec
 
+## 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 |
+
+### 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
 
 - **Auth transcript binding** -- challenge signatures cover
@@ -193,17 +328,80 @@ The `spec/` directory contains the protocol definition:
 
 ## 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.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Web Shell — browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
@@ -16,8 +16,16 @@
   "optionalDependencies": {
     "@noble/post-quantum": "^0.7.0"
   },
+  "devDependencies": {
+    "@fails-components/webtransport": "^1.6.4",
+    "@fails-components/webtransport-transport-http3-quiche": "^1.6.4",
+    "ws": "^8.21.0"
+  },
   "scripts": {
     "test": "node --test test/*.test.mjs",
+    "test:rust": "node --test test/rust/*.test.mjs",
+    "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",

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 ───────────────────────────────────────────────────