@johnhenry/wsh 0.29.0 → 0.31.0

package/README.md

@@ -61,22 +61,39 @@ 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** -- own JSON schema (not asciicast v2 -- see note below) recording and playback with seek/pause/resume
+- **Session recording** -- own JSON schema (asciicast-v2-shaped, not a playable asciicast file -- see note below) recording and playback with seek/pause/resume
 - **Key management** -- IndexedDB storage with OPFS encrypted backup (PBKDF2 + AES-256-GCM)
 - **98 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.
+> **Session recording is asciicast-v2-shaped, but not an asciicast file.**
+> The JS `SessionRecorder.toJSON()` export borrows asciicast v2's vocabulary --
+> `version: 2`, `width`, `height`, `timestamp`, `env`, and events as
+> `[seconds, "o" | "i" | "r", data]` -- so it is easy to convert, but it is not
+> something `asciinema play` can read as-is:
+>
+> - it is **one JSON document** with an `events` array; asciicast v2 is
+>   newline-delimited JSON (a header line, then one event per line);
+> - the header carries wsh's own `sessionId`, and `width`/`height` follow the
+>   latest resize rather than the size at the start;
+> - session lifecycle events (`open`, `exit`) use codes asciicast v2 does not
+>   define (the Rust recorder also has `Start`/`Exit`/`Snapshot`, and uses a
+>   different, incompatible schema from the JS one);
+> - `RecordingExport`'s `format: "asciicast"` option is accepted on the wire but
+>   not implemented server-side -- it returns the same custom JSONL as
+>   `format: "jsonl"`.
+>
+> To play a JS recording in asciinema, write the header and the `o`/`i`/`r`
+> events out as lines (lossy: lifecycle events are dropped):
+>
+> ```js
+> const { version, width, height, timestamp, env, events } = recorder.toJSON();
+> const cast = [JSON.stringify({ version, width, height, timestamp, env }),
+>   ...events.filter((e) => 'oir'.includes(e[1])).map((e) => JSON.stringify(e))].join('\n') + '\n';
+> // write `cast` to session.cast, then: asciinema play session.cast
+> ```
+>
+> A first-class `.cast` exporter is not provided; the conversion above is the
+> supported path (it is covered by `test/recording-format.test.mjs`).
 
 ## Wire Protocol: QMux
 
@@ -186,6 +203,13 @@ restricted host with no shell. `fs.root` confines every path: `..`, absolute
 paths and symlinks pointing out of it are refused -- for `write` and `rename`
 (both paths) exactly as for `read`.
 
+### Gateway (TCP and DNS egress from the host)
+
+`gateway: { allow: ['broker.lan:1883'], socks: '127.0.0.1:9050' }` makes the Node server answer the gateway opcodes, so a
+client (a browser tab via netway's `GatewayBackend`) can open TCP connections and resolve names from the host. Default
+deny; `allow` takes `"*"`, `"host"` or `"host:port"`. `socks` routes every dial through a SOCKS5 proxy (Tor) with the name
+unresolved. UDP and reverse tunnels are refused.
+
 ### TLS (`wss://`) and host extensions
 
 `tls: { cert, key }` (PEM, the options of `https.createServer`) serves the WebSocket listener over TLS on the same
@@ -194,6 +218,50 @@ messages whose `type` is a string, from authenticated connections only. On a rel
 `relay: { onUnreachable(from, targetFingerprint, request) }` is told when an operator asked for a peer that is not
 registered (the operator still gets `no such peer`), so the host can reach that peer another way, such as a Web Push.
 
+### Pre-upgraded transports: `accept()`
+
+`createWshServer()` normally opens its own listener. If your application already owns the HTTP server (or Worker, or
+test harness) and has upgraded the connection itself, hand the socket over instead of bridging it to a per-session
+loopback listener (which any local process could also connect to):
+
+```js
+const wsh = createWshServer({ auth: { authorizedKeys }, exec: true });   // no listen()
+wss.on('connection', (ws, req) => wsh.accept(ws, { remote: { address: req.socket.remoteAddress } }));
+```
+
+`accept(socket, { remote })` takes any WebSocket-like duplex (`send`, `close`, `readyState`, and `on` or
+`addEventListener`): a `ws` socket, a browser/Worker `WebSocket`, a test double. It applies the same auth, features,
+rate limit and session registry as `listen()`'s connections, may be mixed with `listen()`, and resolves to
+`{ close() }`. `remote.address` keys the password-failure throttle (sockets without one share a key). `server.close()`
+drops every accepted socket.
+
+### In-memory host (`@johnhenry/wsh/memory`)
+
+A browser-safe host for demos and tests: no sockets, no ports, no Node (nothing in its import graph is `node:*` or `ws`).
+
+```js
+import { createMemoryHost } from '@johnhenry/wsh/memory';
+
+const host = createMemoryHost({
+  auth: { authorizedKeys: [rawPublicKey] },                       // same shapes as createWshServer
+  exec: async (command, io) => { await io.write(`ran ${command}\n`); return 0; },
+});
+const client = await host.connect({ username: 'demo', keyPair });   // or { signer } / { password }
+const session = await client.openSession({ type: 'exec', command: 'hi' });
+session.onData = (d) => console.log(new TextDecoder().decode(d));   // "ran hi"
+```
+
+It is the real connection handler speaking QMux over an in-memory socket pair, so the client code you test is the code
+you ship. `host.createClient()` / `host.WebSocket` / `host.accept(socket)` / `createSocketPair()` are the lower-level pieces.
+Supported: `auth`, `exec` (a function; there is no shell), `mcp`, `extensions`. Not available in memory: `pty`, `fs`,
+`gateway`, `relay`, `sessions`, `rpc`, `hostKey` and WebTransport (use `@johnhenry/wsh/server`).
+
+### Signing with a page-held signer
+
+`connect()`, `WshClient.exec()` and `connectReverse()` take `signer: { publicKey, sign(data) }` instead of `keyPair`
+(not both): `publicKey` is the raw 32-byte Ed25519 key or a public `CryptoKey`, `sign` returns the 64-byte signature
+(sync or async). For keys that live in a wallet, a hardware token or another realm and are not a `CryptoKeyPair`.
+
 ### WebTransport listener
 
 The client's ladder prefers WebTransport (`https://`) and falls back to `wss://`;
@@ -929,7 +997,7 @@ so options the platform gains later need no change here.
 | `WshMcpBridge` | Remote MCP tool discovery and invocation |
 | `RpcChannel` / `RpcError` | Typed RPC channel (JSON-RPC 2.0 over a CBOR sequence): `client.openRpc(protocol)`; `RPC_FEATURE`, `rpcProtocolFeature(name)`, `RPC_ERROR`, `CborSequenceDecoder` |
 | `mcpClientTransport()` / `mcpServerAdapter()` (`/server`) | MCP SDK `Transport` over an `rpc` channel |
-| `SessionRecorder` | Record PTY I/O with timestamps (own schema, not asciicast v2) |
+| `SessionRecorder` | Record PTY I/O with timestamps (asciicast-v2-shaped JSON; convert to play in asciinema, see the note under Session recording) |
 | `SessionPlayer` | Replay recordings with original timing |
 | `generateKeyPair()` | Create Ed25519 key pair via Web Crypto |
 | `sign(privateKey, message)` / `verify(publicKey, signature, message)` | Raw Ed25519 sign / verify. This positional order (WebCrypto's) is the one canonical form across wsh, raijin and browsermesh |
@@ -996,7 +1064,7 @@ than left to be found.
 | Attach / resume | `attachSession()`, `resumeSession()`, `WshSession.seq` | `attach_session()`, `resume_session()` | **Wire-unified** (`Attach`/`Resume`/`Presence`); `seq` = cumulative output bytes. `@johnhenry/wsh/server` honours `last_seq` (bounded ring, gap errors) and answers Presence with `channel_id`/`seq`; the Rust `wsh-server` does the same (`rust-v0.2.0`+; fixed 256 KiB ring) |
 | Reverse-connect / relay peer | `connectReverse()`, `trustRelayPeer()`; `@johnhenry/wsh/server`: `relay` option and `createReverseHost()` | `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. The Node relay is default-deny and bridges one operator per peer unless `maxOperatorsPerPeer` is raised (`busy:` reasons say so); E2E and bridged feature gates need `rust-v0.3.0`+ on the Rust side; several operators per peer and the signed `KeyExchange` are JS-relay only for now |
 | 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 |
+| Session recording/replay | `SessionRecorder`/`SessionPlayer` (asciicast-v2-shaped JSON) | none | **JS-only** -- no current Rust consumer needs playback; the vocabulary is asciicast v2's, so a Rust port could share it |
 | 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",
@@ -12,6 +12,10 @@
     "./server": {
       "types": "./src/server/index.d.ts",
       "import": "./src/server/index.mjs"
+    },
+    "./memory": {
+      "types": "./src/memory-host.d.ts",
+      "import": "./src/memory-host.mjs"
     }
   },
   "types": "./src/index.d.ts",

package/src/auth.mjs

@@ -159,6 +159,65 @@ export async function sign(privateKey, data) {
   return new Uint8Array(sig);
 }
 
+/**
+ * A page-held signer: an object that can sign but need not expose a private key.
+ * `publicKey` is the raw 32-byte Ed25519 key (or a `CryptoKey`); `sign(data)` returns the
+ * 64-byte signature, synchronously or not. For keys held by a wallet, a hardware token, a
+ * Worker, or anything else that is not a `CryptoKeyPair`.
+ *
+ * @typedef {{ publicKey: Uint8Array | CryptoKey, sign: (data: Uint8Array) => Uint8Array | Promise<Uint8Array> }} WshSigner
+ */
+
+/**
+ * Turn `{ keyPair }` or `{ signer }` into one `{ publicKeyRaw, sign }` pair, or `null` when neither is given.
+ * Throws a TypeError for both together or for a malformed signer.
+ *
+ * @param {{ keyPair?: CryptoKeyPair, signer?: WshSigner }} credentials
+ * @returns {Promise<{ publicKeyRaw: Uint8Array, sign: (data: Uint8Array) => Promise<Uint8Array> } | null>}
+ */
+export async function resolveSigner({ keyPair, signer } = {}) {
+  if (keyPair && signer) throw new TypeError('pass either keyPair or signer, not both');
+  if (keyPair) {
+    return { publicKeyRaw: await exportPublicKeyRaw(keyPair.publicKey), sign: (data) => sign(keyPair.privateKey, data) };
+  }
+  if (!signer) return null;
+  if (typeof signer !== 'object' || typeof signer.sign !== 'function') {
+    throw new TypeError('signer must be { publicKey, sign(data) }');
+  }
+  let publicKeyRaw;
+  if (signer.publicKey instanceof Uint8Array) publicKeyRaw = signer.publicKey;
+  else if (signer.publicKey && typeof signer.publicKey === 'object' && signer.publicKey.type === 'public') publicKeyRaw = await exportPublicKeyRaw(signer.publicKey);
+  if (!publicKeyRaw || publicKeyRaw.byteLength !== 32) {
+    throw new TypeError('signer.publicKey must be a raw 32-byte Ed25519 key or a public CryptoKey');
+  }
+  return {
+    publicKeyRaw,
+    sign: async (data) => {
+      const sig = await signer.sign(data);
+      if (!(sig instanceof Uint8Array) || sig.byteLength !== 64) throw new TypeError('signer.sign() must return a 64-byte Ed25519 signature');
+      return sig;
+    },
+  };
+}
+
+/**
+ * `signChallenge` for a resolved signer (see `resolveSigner`).
+ * @returns {Promise<{ signature: Uint8Array, publicKeyRaw: Uint8Array }>}
+ */
+export async function signChallengeWith(signer, sessionId, nonce, opts) {
+  const transcript = await buildTranscript(sessionId, nonce, opts);
+  return { signature: await signer.sign(transcript), publicKeyRaw: signer.publicKeyRaw };
+}
+
+/**
+ * `signPeerRecord` for a resolved signer (see `resolveSigner`).
+ * @returns {Promise<{ signature: Uint8Array, publicKeyRaw: Uint8Array }>}
+ */
+export async function signPeerRecordWith(signer, record) {
+  const transcript = await buildPeerRecordTranscript(record);
+  return { signature: await signer.sign(transcript), publicKeyRaw: signer.publicKeyRaw };
+}
+
 /**
  * Verify an Ed25519 signature.
  * @param {CryptoKey} publicKey

package/src/client.mjs

@@ -37,7 +37,7 @@ import {
   sessionGrant as sessionGrantMsg, sessionRevoke as sessionRevokeMsg,
   isRelayForwardable,
 } from './messages.mjs';
-import { signChallenge, exportPublicKeyRaw, signPeerRecord, verifyPeerRecord, importPublicKeyRaw, fingerprint as computeFingerprint } from './auth.mjs';
+import { resolveSigner, signChallengeWith, signPeerRecordWith, verifyPeerRecord, importPublicKeyRaw, fingerprint as computeFingerprint } from './auth.mjs';
 import { generateMlKemKeyPair, mlKemEncapsulate, mlKemDecapsulate } from './mlkem.mjs';
 import { compareBytes, combineHybridSecret, verifyKeyExchangeSignature } from './e2e-exchange.mjs';
 import { WshSession } from './session.mjs';
@@ -467,7 +467,8 @@ export class WshClient {
    * @param {string} url - Server URL (https:// for WebTransport, wss:// or ws:// for WebSocket)
    * @param {object} opts
    * @param {string} opts.username - Username for authentication
-   * @param {CryptoKeyPair} [opts.keyPair] - Ed25519 key pair for pubkey auth
+   * @param {CryptoKeyPair} [opts.keyPair]
+   * @param {import('./auth.mjs').WshSigner} [opts.signer] - Page-held signer `{ publicKey, sign(data) }` instead of `keyPair`.
    * @param {string} [opts.password] - Password for password auth
    * @param {'wt'|'ws'|'auto'} [opts.transport] - Force a specific transport
    * @param {object} [opts.webTransport] - Options forwarded to the
@@ -493,15 +494,16 @@ export class WshClient {
    * @param {Function} [opts.onHostKey] - Per-connect `onHostKey`.
    * @returns {Promise<string>} The server-assigned session ID
    */
-  async connect(url, { username, keyPair, password, transport: transportHint, webTransport, timeout = DEFAULT_AUTH_TIMEOUT, ...hostKeyOpts } = {}) {
+  async connect(url, { username, keyPair, signer, password, transport: transportHint, webTransport, timeout = DEFAULT_AUTH_TIMEOUT, ...hostKeyOpts } = {}) {
     if (this.#state !== STATE_DISCONNECTED && this.#state !== STATE_CLOSED) {
       throw new Error(`Client already ${this.#state}`);
     }
     if (!username) {
       throw new Error('username is required');
     }
-    if (!keyPair && !password) {
-      throw new Error('Either keyPair or password is required for authentication');
+    const cred = await resolveSigner({ keyPair, signer });
+    if (!cred && !password) {
+      throw new Error('Either keyPair, signer or password is required for authentication');
     }
 
     this.#state = STATE_CONNECTING;
@@ -519,7 +521,7 @@ export class WshClient {
       this.#state = STATE_CONNECTED;
 
       // ── Auth handshake ────────────────────────────────────────────
-      const authMethod = keyPair ? AUTH_METHOD.PUBKEY : AUTH_METHOD.PASSWORD;
+      const authMethod = cred ? AUTH_METHOD.PUBKEY : AUTH_METHOD.PASSWORD;
       const hostKeyNonce = newHostKeyNonce();
       await transport.sendControl(
         hello({ username, authMethod, features: [HOST_KEY_NONCE_PREFIX + hostKeyNonce] })
@@ -568,9 +570,8 @@ export class WshClient {
           // Sign the challenge. Challenge.session_id (not the one from
           // ServerHello) is authoritative for the transcript — see the
           // comment in the CHALLENGE-first branch below for why.
-          const { signature, publicKeyRaw } = await signChallenge(
-            keyPair.privateKey,
-            keyPair.publicKey,
+          const { signature, publicKeyRaw } = await signChallengeWith(
+            cred,
             challengeMsg.session_id,
             challengeMsg.nonce,
             { username }
@@ -595,7 +596,7 @@ export class WshClient {
       } else if (firstResponse.type === MSG.CHALLENGE) {
         // Some servers skip SERVER_HELLO and go straight to CHALLENGE.
         await this.#verifyHostKey(null, hostCtx);
-        if (authMethod !== AUTH_METHOD.PUBKEY || !keyPair) {
+        if (authMethod !== AUTH_METHOD.PUBKEY || !cred) {
           throw new Error('Server sent CHALLENGE but no key pair was provided');
         }
 
@@ -607,9 +608,8 @@ export class WshClient {
         // tempSessionId as a fallback for this.#sessionId below in case
         // AUTH_OK's own session_id is ever absent.
         tempSessionId = firstResponse.session_id;
-        const { signature, publicKeyRaw } = await signChallenge(
-          keyPair.privateKey,
-          keyPair.publicKey,
+        const { signature, publicKeyRaw } = await signChallengeWith(
+          cred,
           firstResponse.session_id,
           firstResponse.nonce,
           { username }
@@ -996,18 +996,19 @@ export class WshClient {
    * @param {object} opts
    * @param {string} opts.username
    * @param {CryptoKeyPair} [opts.keyPair]
+   * @param {import('./auth.mjs').WshSigner} [opts.signer] - Page-held signer `{ publicKey, sign(data) }` instead of `keyPair`.
    * @param {string} [opts.password]
    * @param {number} [opts.timeout=60000] - Overall timeout in ms
    * @param {boolean} [opts.primer=true] - See `openSession({ primer })`
    * @returns {Promise<{stdout: Uint8Array, exitCode: number}>}
    */
-  static async exec(url, command, { username, keyPair, password, timeout = DEFAULT_EXEC_TIMEOUT, primer = true, ...hostKeyOpts } = {}) {
+  static async exec(url, command, { username, keyPair, signer, password, timeout = DEFAULT_EXEC_TIMEOUT, primer = true, ...hostKeyOpts } = {}) {
     const client = new WshClient();
     const chunks = [];
     let exitCode = -1;
 
     try {
-      await client.connect(url, { username, keyPair, password, ...hostKeyOpts });
+      await client.connect(url, { username, keyPair, signer, password, ...hostKeyOpts });
 
       const session = await client.openSession({ type: 'exec', command, primer });
 
@@ -1056,6 +1057,7 @@ export class WshClient {
    * @param {object} opts
    * @param {string} opts.username
    * @param {CryptoKeyPair} [opts.keyPair]
+   * @param {import('./auth.mjs').WshSigner} [opts.signer] - Page-held signer `{ publicKey, sign(data) }` instead of `keyPair`.
    * @param {string} [opts.password]
    * @param {object} [opts.expose] - Capabilities to expose { shell, exec, fs, tools }
    * @param {string} [opts.peerType]
@@ -1069,6 +1071,7 @@ export class WshClient {
   async connectReverse(url, {
     username,
     keyPair,
+    signer,
     password,
     webTransport,
     expose = {},
@@ -1081,7 +1084,7 @@ export class WshClient {
     ...hostKeyOpts
   } = {}) {
     // Authenticate normally first.
-    const sessionId = await this.connect(url, { username, keyPair, password, webTransport, ...hostKeyOpts });
+    const sessionId = await this.connect(url, { username, keyPair, signer, password, webTransport, ...hostKeyOpts });
 
     // Build capabilities list from expose options.
     const capabilities = [];
@@ -1091,10 +1094,9 @@ export class WshClient {
     if (expose.tools) capabilities.push('tools');
 
     // Export public key for peer identification.
+    const cred = await resolveSigner({ keyPair, signer });
     let publicKey = null;
-    if (keyPair) {
-      publicKey = await exportPublicKeyRaw(keyPair.publicKey);
-    }
+    if (cred) publicKey = cred.publicKeyRaw;
 
     const effectiveShellBackend = shellBackend || (expose.shell ? 'virtual-shell' : 'exec-only');
     const record = {
@@ -1118,8 +1120,8 @@ export class WshClient {
     // (see auth.mjs's "Signed peer records" section). Only possible with
     // a real identity key, same precondition `publicKey` already had.
     let recordSignature;
-    if (keyPair) {
-      ({ signature: recordSignature } = await signPeerRecord(keyPair.privateKey, keyPair.publicKey, record));
+    if (cred) {
+      ({ signature: recordSignature } = await signPeerRecordWith(cred, record));
     }
 
     // Register as a reverse peer.
@@ -2360,18 +2362,20 @@ export class WshClient {
    * @param {object} opts
    * @param {string} opts.username
    * @param {CryptoKeyPair} [opts.keyPair]
+   * @param {import('./auth.mjs').WshSigner} [opts.signer] - Page-held signer `{ publicKey, sign(data) }` instead of `keyPair`.
    * @param {string} [opts.password]
    * @param {number} [opts.timeout]
    * @returns {Promise<string>} Session ID
    * @private
    */
-  async #performAuth({ username, keyPair, password, timeout = DEFAULT_AUTH_TIMEOUT, url, ...hostKeyOpts } = {}) {
+  async #performAuth({ username, keyPair, signer, password, timeout = DEFAULT_AUTH_TIMEOUT, url, ...hostKeyOpts } = {}) {
     if (!username) throw new Error('username is required');
-    if (!keyPair && !password) throw new Error('Either keyPair or password is required');
+    const cred = await resolveSigner({ keyPair, signer });
+    if (!cred && !password) throw new Error('Either keyPair, signer or password is required');
 
     this.#hostKey = null;
     try {
-      const authMethod = keyPair ? AUTH_METHOD.PUBKEY : AUTH_METHOD.PASSWORD;
+      const authMethod = cred ? AUTH_METHOD.PUBKEY : AUTH_METHOD.PASSWORD;
       const hostKeyNonce = newHostKeyNonce();
       await this.#transport.sendControl(hello({ username, authMethod, features: [HOST_KEY_NONCE_PREFIX + hostKeyNonce] }));
       const hostCtx = { ...hostKeyOpts, url, username, nonce: hostKeyNonce };
@@ -2409,8 +2413,8 @@ export class WshClient {
             return this.#sessionId;
           }
 
-          const { signature, publicKeyRaw } = await signChallenge(
-            keyPair.privateKey, keyPair.publicKey, challengeMsg.session_id, challengeMsg.nonce, { username }
+          const { signature, publicKeyRaw } = await signChallengeWith(
+            cred, challengeMsg.session_id, challengeMsg.nonce, { username }
           );
 
           await this.#transport.sendControl(authMsg({
@@ -2422,7 +2426,7 @@ export class WshClient {
           }));
         }
       } else if (firstResponse.type === MSG.CHALLENGE) {
-        if (!keyPair) throw new Error('Server sent CHALLENGE but no key pair provided');
+        if (!cred) throw new Error('Server sent CHALLENGE but no key pair provided');
         await this.#verifyHostKey(null, hostCtx);
 
         // Challenge carries session_id directly — see connect()'s
@@ -2430,8 +2434,8 @@ export class WshClient {
         // this.#sessionId below in case AUTH_OK's own session_id is ever
         // absent.
         tempSessionId = firstResponse.session_id;
-        const { signature, publicKeyRaw } = await signChallenge(
-          keyPair.privateKey, keyPair.publicKey, firstResponse.session_id, firstResponse.nonce, { username }
+        const { signature, publicKeyRaw } = await signChallengeWith(
+          cred, firstResponse.session_id, firstResponse.nonce, { username }
         );
 
         await this.#transport.sendControl(authMsg({

package/src/index.d.ts

@@ -1108,6 +1108,38 @@ export function signChallenge(
   opts?: WshTranscriptOptions,
 ): Promise<{ signature: Uint8Array; publicKeyRaw: Uint8Array }>;
 
+/**
+ * A signer that need not expose a private key: a wallet, a hardware token, a Worker.
+ * `publicKey` is the raw 32-byte Ed25519 key or a public `CryptoKey`; `sign` returns the 64-byte signature.
+ */
+export interface WshSigner {
+  publicKey: Uint8Array | CryptoKey;
+  sign(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
+
+/** A `keyPair` or `signer` normalized to a raw public key and an async `sign`; `null` when neither is given. */
+export interface WshResolvedSigner {
+  publicKeyRaw: Uint8Array;
+  sign(data: Uint8Array): Promise<Uint8Array>;
+}
+
+/** Normalize `{ keyPair }` or `{ signer }`. Throws a TypeError for both together or a malformed signer. */
+export function resolveSigner(credentials?: { keyPair?: CryptoKeyPair; signer?: WshSigner }): Promise<WshResolvedSigner | null>;
+
+/** `signChallenge` for a signer resolved by `resolveSigner`. */
+export function signChallengeWith(
+  signer: WshResolvedSigner,
+  sessionId: string,
+  nonce: Uint8Array,
+  opts?: WshTranscriptOptions,
+): Promise<{ signature: Uint8Array; publicKeyRaw: Uint8Array }>;
+
+/** `signPeerRecord` for a signer resolved by `resolveSigner`. */
+export function signPeerRecordWith(
+  signer: WshResolvedSigner,
+  record: WshPeerRecord,
+): Promise<{ signature: Uint8Array; publicKeyRaw: Uint8Array }>;
+
 /**
  * Server-side: verify a client's challenge response.
  */
@@ -1385,7 +1417,10 @@ export class SerialQueue<T = unknown> {
  * Provides the same interface as WebTransportTransport so that upper
  * layers (session, client) work identically over either transport.
  */
-export class WebSocketTransport extends WshTransport {}
+export class WebSocketTransport extends WshTransport {
+  /** `WebSocket`: a constructor to dial with instead of the global one (a test double, `createMemoryHost().WebSocket`). */
+  constructor(options?: { WebSocket?: new (url: string) => any });
+}
 
 /**
  * @deprecated The old hand-rolled 5-byte mux's frame-type byte values.
@@ -1772,6 +1807,8 @@ export interface WshHostKeyOptions {
 export interface WshConnectOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
+  /** A page-held signer instead of `keyPair` (not both). */
+  signer?: WshSigner;
   password?: string;
   transport?: 'wt' | 'ws';
   /**
@@ -1845,6 +1882,8 @@ export interface WshResumeSessionOptions {
 export interface WshConnectReverseOptions {
   username: string;
   keyPair?: CryptoKeyPair;
+  /** A page-held signer instead of `keyPair` (not both). */
+  signer?: WshSigner;
   password?: string;
   /** Forwarded to the underlying `connect()` -- see `WshConnectOptions`. */
   webTransport?: WshWebTransportOptions;
@@ -1871,6 +1910,8 @@ export interface WshConnectReverseOptions {
 export interface WshExecOptions extends WshHostKeyOptions {
   username: string;
   keyPair?: CryptoKeyPair;
+  /** A page-held signer instead of `keyPair` (not both). */
+  signer?: WshSigner;
   password?: string;
   timeout?: number;
   /** See {@link WshOpenSessionOptions.primer}. */
@@ -2542,7 +2583,7 @@ export interface SessionRecordingEntry {
   data: unknown;
 }
 
-/** Asciicast v2 export format. */
+/** The `toJSON()` export: asciicast-v2-shaped (not a playable asciicast file -- one JSON document, plus `sessionId` and `open`/`exit` events). */
 export interface SessionRecordingJSON {
   version: 2;
   width: number;
@@ -2580,7 +2621,7 @@ export class SessionRecorder {
   record(type: SessionRecordingEventType | string, data: unknown): void;
 
   /**
-   * Export the recording as a JSON-serializable object (asciicast v2 format).
+   * Export the recording as a JSON-serializable object (asciicast-v2-shaped; see the README for converting it to a `.cast` file).
    */
   toJSON(): SessionRecordingJSON;
 

package/src/index.mjs

@@ -47,6 +47,7 @@ export {
   generateKeyPair, exportPublicKeyRaw, exportPublicKeySSH,
   importPublicKeyRaw, exportPrivateKeyPKCS8, importPrivateKeyPKCS8,
   sign, verify, buildTranscript, signChallenge, verifyChallenge,
+  resolveSigner, signChallengeWith, signPeerRecordWith,
   buildPeerRecordTranscript, signPeerRecord, verifyPeerRecord,
   fingerprint, shortFingerprint, generateNonce,
   podId, fingerprintToPodId, podIdToFingerprint,

package/src/memory-host.d.ts

@@ -0,0 +1,48 @@
+import type { WshClient } from './index.js';
+import type { WshSigner } from './index.js';
+import type {
+  WshServerAuthOptions, WshServerPrincipal, WshServerMcpOptions, WshExecRunner, WshServerOptions,
+  WshAcceptableSocket, WshAcceptOptions,
+} from './server/index.js';
+
+export interface WshMemoryHostOptions {
+  /** As for `createWshServer`. Omitted = refuse everyone. */
+  auth?: WshServerAuthOptions | ((who: WshServerPrincipal) => boolean | Promise<boolean>);
+  /** `run(command, io)`; there is no shell in memory, so there is no `true`. */
+  exec?: WshExecRunner | { run: WshExecRunner; timeoutMs?: number; clientEnv?: boolean };
+  mcp?: WshServerMcpOptions;
+  extensions?: WshServerOptions['extensions'];
+  bindTimeoutMs?: number;
+  onLog?: (line: string) => void;
+}
+
+/** Credentials for `host.connect()`: the options of `WshClient.connect()` minus the URL. */
+export interface WshMemoryConnectOptions {
+  username: string;
+  keyPair?: CryptoKeyPair;
+  signer?: WshSigner;
+  password?: string;
+  timeout?: number;
+}
+
+export interface WshMemoryHost {
+  /** The URL to give `client.connect()`; the host ignores it. */
+  readonly url: string;
+  /** A `WebSocket` constructor that dials this host. */
+  readonly WebSocket: new (url?: string) => any;
+  /** Serve any pre-upgraded socket (see `createSocketPair()`). */
+  accept(socket: WshAcceptableSocket, options?: WshAcceptOptions): Promise<{ close(): void }>;
+  socketPair: typeof createSocketPair;
+  /** A `WshClient` whose transport is this host: `await client.connect(host.url, { username, keyPair, transport: 'ws' })`. */
+  createClient(options?: ConstructorParameters<typeof WshClient>[0]): WshClient;
+  /** `createClient()` and `connect()` in one. */
+  connect(credentials: WshMemoryConnectOptions): Promise<WshClient>;
+  /** Drop every connection. */
+  close(): Promise<void>;
+}
+
+/** Two connected in-memory WebSocket-like sockets. */
+export function createSocketPair(): [WshAcceptableSocket & EventTarget, WshAcceptableSocket & EventTarget];
+
+/** A browser-safe wsh host in this JavaScript realm: no sockets, no Node. */
+export function createMemoryHost(options?: WshMemoryHostOptions): WshMemoryHost;