@johnhenry/wsh 0.30.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
 
@@ -201,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://`;
@@ -936,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 |
@@ -1003,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.30.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;

package/src/memory-host.mjs

@@ -0,0 +1,175 @@
+/**
+ * `@johnhenry/wsh/memory` -- a wsh host that lives in the same JavaScript realm as its clients, with no sockets, no
+ * ports and no Node. Browser-safe (a page, a Worker, Deno, Bun, Node): it imports nothing from `node:*`, and a test
+ * (`test/memory-host.test.mjs`) keeps it that way. For demos, docs and tests of an application that talks wsh.
+ *
+ * It is the real protocol end to end -- the same connection handler `createWshServer` runs (handshake, Ed25519 or
+ * password auth, exec channels, MCP tools, extensions), speaking QMux over a pair of in-memory WebSocket-like
+ * sockets -- so what a client does here is what it does against a server. It serves what a browser can: `exec` as a
+ * function you provide (there is no shell), `mcp` tools, `extensions`. Not available: `pty`, `fs`, `gateway`, `relay`,
+ * `sessions`, `rpc`, `hostKey`, WebTransport (they need Node; use `@johnhenry/wsh/server`).
+ *
+ * ```js
+ * import { createMemoryHost } from '@johnhenry/wsh/memory';
+ * const host = createMemoryHost({
+ *   auth: { authorizedKeys: [rawPublicKey] },
+ *   exec: async (command, io) => { await io.write(`you ran: ${command}\n`); return 0; },
+ * });
+ * const client = await host.connect({ username: 'demo', keyPair });
+ * ```
+ */
+
+import { WshClient } from './client.mjs';
+import { WebSocketTransport } from './transport-ws.mjs';
+import { createConnectionFactory } from './server/connection.mjs';
+import { buildAuthorizer, authMethods, FailureLimiter } from './server/auth.mjs';
+import { createMcpHost } from './server/mcp.mjs';
+import { bindSocket } from './server/socket.mjs';
+
+const CONNECTING = 0;
+const OPEN = 1;
+const CLOSING = 2;
+const CLOSED = 3;
+
+/** The URL to hand `client.connect()` (the host ignores it; it only has to look like a WebSocket URL). */
+const MEMORY_URL = 'ws://memory.invalid/';
+
+function event(type, props) {
+  const ev = new Event(type);
+  Object.assign(ev, props);
+  return ev;
+}
+
+/** One end of an in-memory socket pair: just enough WebSocket for `WebSocketTransport` and `bindSocket`. */
+class MemorySocket extends EventTarget {
+  static CONNECTING = CONNECTING;
+  static OPEN = OPEN;
+  static CLOSING = CLOSING;
+  static CLOSED = CLOSED;
+
+  readyState = CONNECTING;
+  binaryType = 'arraybuffer';
+  /** @type {MemorySocket | null} */
+  peer = null;
+
+  send(data) {
+    if (this.readyState !== OPEN) throw new Error('WebSocket is not open');
+    if (typeof data === 'string') return; // wsh frames are binary
+    const view = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const copy = view.slice().buffer;
+    const peer = this.peer;
+    queueMicrotask(() => { if (peer.readyState === OPEN) peer.dispatchEvent(event('message', { data: copy })); });
+  }
+
+  close(code = 1000, reason = '') {
+    if (this.readyState >= CLOSING) return;
+    this.readyState = CLOSING;
+    const peer = this.peer;
+    queueMicrotask(() => {
+      for (const s of [this, peer]) {
+        if (s.readyState === CLOSED) continue;
+        s.readyState = CLOSED;
+        s.dispatchEvent(event('close', { code, reason, wasClean: true }));
+      }
+    });
+  }
+}
+
+/**
+ * Two connected sockets: what one sends, the other receives (asynchronously, in order). Both are open after a tick.
+ * @returns {[MemorySocket, MemorySocket]}
+ */
+export function createSocketPair() {
+  const a = new MemorySocket();
+  const b = new MemorySocket();
+  a.peer = b;
+  b.peer = a;
+  queueMicrotask(() => {
+    for (const s of [a, b]) { s.readyState = OPEN; s.dispatchEvent(new Event('open')); }
+  });
+  return [a, b];
+}
+
+/**
+ * @param {object} [options]
+ * @param {object | Function} [options.auth] - As for `createWshServer`. Omitted = refuse everyone.
+ * @param {Function | { run: Function, timeoutMs?: number, clientEnv?: boolean }} [options.exec]
+ *   `run(command, io) => Promise<exitCode>` (see `ExecIo` in `server/exec.mjs`): the host has no shell, so there is no `true`.
+ * @param {{ tools?: object[] | object, client?: object, authorize?: Function, maxConcurrent?: number, timeoutMs?: number }} [options.mcp]
+ * @param {Record<string, Function>} [options.extensions] - Handlers for application-defined messages, as for `createWshServer`.
+ * @param {number} [options.bindTimeoutMs=3000]
+ * @param {(line: string) => void} [options.onLog]
+ */
+export function createMemoryHost({ auth, exec, mcp, extensions, bindTimeoutMs = 3000, onLog = () => {} } = {}) {
+  if (exec === true) throw new TypeError('createMemoryHost: exec must be a function (run(command, io)); there is no shell to run `true` with');
+  if (exec !== undefined && typeof exec !== 'function' && typeof exec?.run !== 'function') {
+    throw new TypeError('createMemoryHost: exec must be a function or { run }');
+  }
+  if (extensions !== undefined && (extensions === null || typeof extensions !== 'object')) throw new TypeError('createMemoryHost: extensions must be an object of handlers');
+  const execOptions = typeof exec === 'function' || !exec ? {} : exec;
+  const execRunner = typeof exec === 'function' ? exec : exec?.run ?? null;
+  const rl = auth?.rateLimit ?? {};
+  const rateLimit = {
+    limiter: new FailureLimiter(rl),
+    key: typeof rl.key === 'function' ? rl.key : ({ address }) => String(address ?? 'unknown'),
+    failureDelayMs: rl.failureDelayMs ?? 250,
+  };
+  const methods = authMethods(auth);
+  const mcpHost = mcp ? createMcpHost(mcp) : null;
+
+  const ready = buildAuthorizer(auth).then((authorize) => createConnectionFactory({
+    authorize, execRunner, execOptions, pty: null, files: null, bindTimeoutMs, log: onLog,
+    methods, hostKey: null, rateLimit, extensions, mcp: mcpHost, rpc: null, gateway: null, sessions: null, relay: null,
+  }));
+  ready.catch(() => {});
+
+  const accepted = new Set();
+  let closed = false;
+
+  async function accept(socket, options) {
+    if (closed) throw new Error('createMemoryHost: host is closed');
+    const handle = await bindSocket(socket, ready, options);
+    accepted.add(handle);
+    return handle;
+  }
+
+  /** A `WebSocket` constructor that dials this host: `new host.WebSocket(url)` ignores the URL. */
+  class HostWebSocket extends MemorySocket {
+    constructor() {
+      super();
+      const [client, server] = createSocketPair();
+      void accept(server, { remote: { address: 'memory' } }).catch(onLog);
+      return client;
+    }
+  }
+
+  const host = {
+    /** Pass to `client.connect()`. */
+    url: MEMORY_URL,
+    WebSocket: HostWebSocket,
+    accept,
+    socketPair: createSocketPair,
+    /** A `WshClient` whose transport is this host (`await client.connect(host.url, ...)`). */
+    createClient(clientOptions = {}) {
+      return new WshClient({
+        ...clientOptions,
+        transportFactories: {
+          ws: () => new WebSocketTransport({ WebSocket: HostWebSocket }),
+          wt: () => { throw new Error('createMemoryHost: WebTransport is not available in memory'); },
+        },
+      });
+    },
+    /** `createClient()` and `connect()` in one: resolves to a connected client. */
+    async connect(credentials) {
+      const client = host.createClient();
+      await client.connect(MEMORY_URL, { transport: 'ws', ...credentials });
+      return client;
+    },
+    async close() {
+      closed = true;
+      for (const handle of accepted) handle.close();
+      accepted.clear();
+    },
+  };
+  return host;
+}

package/src/recording.mjs

@@ -2,8 +2,14 @@
  * Session recording and playback for wsh PTY sessions.
  *
  * Records all terminal I/O with timestamps for later replay.
- * The export format is compatible with the asciicast v2 structure
- * used by asciinema, enabling interop with standard terminal players.
+ * The export (`toJSON()`) is asciicast-v2-*shaped*, not an asciicast v2 file: the header
+ * fields (`version: 2`, `width`, `height`, `timestamp`, `env`) and the `[seconds, code, data]`
+ * events with the `o` / `i` / `r` codes are asciicast's, but it is one JSON document (asciicast
+ * v2 is newline-delimited JSON: a header line, then one event per line), the header carries
+ * wsh's own `sessionId`, `width`/`height` follow the latest resize rather than the start size,
+ * and the lifecycle events `open` / `exit` have no asciicast code. `asciinema play` therefore
+ * cannot read it as-is. The README ("Session recording") shows the short conversion to a real
+ * `.cast` file (header line + the `o`/`i`/`r` events); `fromJSON()` reads this document shape.
  */
 
 // ── SessionRecorder ──────────────────────────────────────────────────
@@ -66,16 +72,17 @@ export class SessionRecorder {
   /**
    * Export the recording as a JSON-serializable object.
    *
-   * The format is compatible with asciicast v2:
+   * The shape follows asciicast v2 but this is NOT a playable asciicast file (see the file header):
    *   - version: 2
-   *   - width, height: terminal dimensions at start
+   *   - width, height: terminal dimensions as of the latest resize (asciicast: at start)
    *   - timestamp: Unix epoch seconds when recording started
-   *   - env: optional environment metadata
-   *   - events: array of [time_seconds, event_type, data]
+   *   - env: environment metadata
+   *   - sessionId: wsh's own field
+   *   - events: array of [time_seconds, event_type, data] -- one JSON document, not one line per event
    *
-   * Event types in asciicast:
-   *   "o" = output, "i" = input, "r" = resize
-   * We extend with: "open", "exit" for session lifecycle.
+   * Event types from asciicast:
+   *   "o" = output, "i" = input, "r" = resize ("COLSxROWS")
+   * Not in asciicast, so dropped by the conversion in the README: "open", "exit" (session lifecycle).
    *
    * @returns {object}
    */
@@ -111,7 +118,8 @@ export class SessionRecorder {
   }
 
   /**
-   * Import a recording from JSON (as produced by toJSON or parsed from asciicast).
+   * Import a recording from the JSON document `toJSON()` produces. An asciicast v2 `.cast` file is not read directly:
+   * parse its lines and gather them into `{ ...header, events }` first.
    *
    * @param {object | string} json - Recording object or JSON string
    * @returns {SessionRecorder}

package/src/server/connection.mjs

@@ -13,7 +13,6 @@
  * dropped rather than forwarded to the process's stdin.
  */
 
-import { randomUUID } from 'node:crypto';
 import { QMuxConnection } from '../qmux-connection.mjs';
 import { FrameDecoder, frameEncode } from '../cbor.mjs';
 import {
@@ -24,8 +23,7 @@ import {
 import {
   generateNonce, verifyChallenge, fingerprint, importPublicKeyRaw,
 } from '../auth.mjs';
-import { FILE_CHUNK_BYTES } from './fs.mjs';
-import { MAX_ATTACHMENTS } from './sessions.mjs';
+import { FILE_CHUNK_BYTES, MAX_ATTACHMENTS } from './constants.mjs';
 import { MCP_CALL_ID_FEATURE } from '../client.mjs';
 import { RpcChannel, RPC_FEATURE, RPC_MAX_MESSAGE_PREFIX, rpcProtocolFeature } from '../rpc.mjs';
 import { sealFrame, openFrame, ROLE_TAGS } from '../e2e-frame.mjs';
@@ -70,6 +68,7 @@ const REPLAY_CHUNK_BYTES = 32 * 1024;
 const USERNAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
 const enc = new TextEncoder();
 
+const randomUUID = () => crypto.randomUUID();
 const randomBytes = (n) => crypto.getRandomValues(new Uint8Array(n));
 const toBytes = (d) => (typeof d === 'string' ? enc.encode(d) : d);
 
@@ -831,7 +830,7 @@ export function createConnectionFactory(cfg) {
         const args = m.command ? ['-c', String(m.command)] : [];
         proc = p.spawn(p.shell, args, {
           name: p.term, cols, rows, cwd: p.cwd,
-          env: { ...(p.env ?? process.env), TERM: p.term, ...(m.env && typeof m.env === 'object' ? m.env : {}) },
+          env: { ...(p.env ?? globalThis.process?.env), TERM: p.term, ...(m.env && typeof m.env === 'object' ? m.env : {}) },
         });
       } catch (e) {
         return send(openFail({ reason: `pty spawn failed: ${e.message}` }));

package/src/server/constants.mjs

@@ -0,0 +1,10 @@
+/**
+ * Limits shared by the connection handler and the Node-only modules that also export them
+ * (kept here so the connection handler imports nothing from `node:*` -- see `src/memory-host.mjs`).
+ */
+
+/** Size of one FileChunk when a file is streamed to the client. */
+export const FILE_CHUNK_BYTES = 64 * 1024;
+
+/** Most clients attached to one detached-session at once. */
+export const MAX_ATTACHMENTS = 16;

package/src/server/fs.mjs

@@ -14,7 +14,8 @@ import { constants as fsc } from 'node:fs';
 import path from 'node:path';
 
 export const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
-export const FILE_CHUNK_BYTES = 64 * 1024;
+import { FILE_CHUNK_BYTES } from './constants.mjs';
+export { FILE_CHUNK_BYTES };
 
 /**
  * @param {{ root: string, readOnly?: boolean, maxFileBytes?: number }} opts

package/src/server/gateway.mjs

@@ -22,10 +22,15 @@
  * the host would have to resolve the name itself.
  */
 
-import net from 'node:net';
-import dns from 'node:dns/promises';
 import { MSG, gatewayOk, gatewayFail, gatewayClose, gatewayData, dnsResult, listenFail } from '../messages.gen.mjs';
 
+// Loaded on first use so that importing the connection handler (which serves the gateway opcodes)
+// does not pull `node:net` into a browser bundle (see `src/memory-host.mjs`).
+let netModule = null;
+let dnsModule = null;
+const loadNet = async () => (netModule ??= (await import('node:net')).default);
+const loadDns = async () => (dnsModule ??= (await import('node:dns/promises')).default);
+
 /** Numeric codes of GatewayFail (the same table `@johnhenry/browsermesh-netway` decodes). */
 export const GATEWAY_FAIL = Object.freeze({
   CONNECTION_REFUSED: 1, HOST_UNREACHABLE: 2, DNS_FAILED: 3, POLICY_DENIED: 4, TIMEOUT: 5, CLOSED: 6, QUEUE_FULL: 7,
@@ -62,7 +67,8 @@ export function destinationAllowed(allow, host, port) {
  * Resolves with the connected socket, or rejects with an Error carrying `.code`
  * (a GATEWAY_FAIL value).
  */
-export function socksConnect(proxy, host, port, { timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS } = {}) {
+export async function socksConnect(proxy, host, port, { timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS } = {}) {
+  const net = await loadNet();
   return new Promise((resolve, reject) => {
     const name = Buffer.from(host, 'utf8');
     const fail = (code, message, sock) => { sock?.destroy(); const e = new Error(message); e.code = code; reject(e); };
@@ -161,6 +167,7 @@ export function createGatewaySession(cfg, send, log = () => {}) {
     pending.add(id);
     let sock;
     try {
+      const net = await loadNet();
       if (cfg.socks) sock = await socksConnect(cfg.socks, m.host, m.port, { timeoutMs: cfg.connectTimeoutMs });
       else {
         sock = await new Promise((resolve, reject) => {
@@ -202,7 +209,7 @@ export function createGatewaySession(cfg, send, log = () => {}) {
     try {
       const family = m.record_type === 'AAAA' ? 6 : m.record_type === 'A' || m.record_type === undefined ? 4 : 0;
       if (!family) return fail(id, GATEWAY_FAIL.DNS_FAILED, `unsupported record type ${String(m.record_type).slice(0, 8)}`);
-      const addresses = (await dns.lookup(m.name, { family, all: true })).map((a) => a.address);
+      const addresses = (await (await loadDns()).lookup(m.name, { family, all: true })).map((a) => a.address);
       return reply(dnsResult({ gatewayId: id, addresses }));
     } catch (e) {
       return fail(id, GATEWAY_FAIL.DNS_FAILED, String(e.code === 'ENOTFOUND' ? 'name not found' : e.message).slice(0, 200));

package/src/server/index.d.ts

@@ -402,9 +402,32 @@ export interface WshServerAddress {
   port: number;
 }
 
+/**
+ * An already-accepted WebSocket-like duplex: `send(bytes)`, `close(code?)`, `readyState` (1 = open), and either Node-style
+ * `on(event, fn)` or `addEventListener(event, fn)`. A `ws` socket, a browser/Worker `WebSocket`, or a test double.
+ */
+export interface WshAcceptableSocket {
+  send(data: Uint8Array): void;
+  close(code?: number): void;
+  readonly readyState: number;
+  on?(event: string, listener: (...args: any[]) => void): unknown;
+  addEventListener?(event: string, listener: (ev: any) => void): unknown;
+}
+
+export interface WshAcceptOptions {
+  /** What the embedder knows of the peer; `address` keys the password-failure throttle. */
+  remote?: { address?: string; headers?: Record<string, unknown> };
+}
+
 export interface WshServer {
   /** Start listening. Requires the `ws` package. */
   listen(): Promise<WshServerAddress>;
+  /**
+   * Serve a pre-upgraded transport -- a socket your own HTTP server, Worker or test already accepted -- with this
+   * server's auth, features and sessions, so no listener of wsh's own is needed (`listen()` is optional).
+   * Resolves once the connection is attached; the handle's `close()` drops it. `close()` of the server drops all of them.
+   */
+  accept(socket: WshAcceptableSocket, options?: WshAcceptOptions): Promise<{ close(): void }>;
   /** Drop every connection and stop listening. */
   close(): Promise<void>;
   /** The bound address, or `null` when not listening. */

package/src/server/index.mjs

@@ -17,6 +17,7 @@ import { startWebTransport } from './webtransport.mjs';
 import { createConnectionFactory, STREAM_ANNOUNCE } from './connection.mjs';
 import { normalizeGateway } from './gateway.mjs';
 import { createRpcHost, mcpServerAdapter } from './rpc.mjs';
+import { bindSocket } from './socket.mjs';
 
 export { parseAuthorizedKeys, STREAM_ANNOUNCE, mcpServerAdapter };
 export { createReverseHost } from './reverse-host.mjs';
@@ -74,7 +75,7 @@ export { generateSelfSignedCertificate } from './self-signed.mjs';
  *   through a SOCKS5 proxy (Tor) with the name unresolved. UDP and reverse tunnels are refused. Off unless given. See `gateway.mjs`.
  * @param {number} [options.bindTimeoutMs=3000]
  * @param {(line: string) => void} [options.onLog]
- * @returns {{ listen(): Promise<{address: string, port: number}>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
+ * @returns {{ listen(): Promise<{address: string, port: number}>, accept(socket: object, options?: object): Promise<{ close(): void }>, close(): Promise<void>, address(): ({address: string, port: number} | null) }}
  */
 export function createWshServer({
   host = '127.0.0.1', port = 0, tls, auth, exec, pty, fs, hostKey, mcp, rpc, rpcMaxMessageBytes, rpcMaxInflight, sessions, sessionSecret, relay, extensions, gateway, webTransport, bindTimeoutMs = 3000, onLog = () => {},
@@ -102,15 +103,13 @@ export function createWshServer({
   const gatewayCfg = gateway === undefined ? null : normalizeGateway(gateway);
   const sessionOptions = sessions ? (sessions === true ? {} : sessions) : null;
 
-  return {
-    async listen() {
-      if (wss) throw new Error('createWshServer: already listening');
-      let WebSocketServer;
-      try {
-        ({ WebSocketServer } = await import('ws'));
-      } catch (err) {
-        throw new Error('@johnhenry/wsh/server needs the "ws" package: npm install ws', { cause: err });
-      }
+  /** Sockets handed to `accept()` that are still open. */
+  const accepted = new Set();
+  /** The connection factory, built once on first use (`listen()` or `accept()`) and torn down by `close()`. */
+  let ready = null;
+
+  function start() {
+    ready ??= (async () => {
       const authorize = await buildAuthorizer(auth);
       host_ = hostKey ? await loadHostKey(hostKey) : null;
       if (sessionOptions) {
@@ -125,10 +124,25 @@ export function createWshServer({
       }
       if (relay) hub = new RelayHub({ ...relay, log: onLog });
       if (extensions !== undefined && (extensions === null || typeof extensions !== 'object')) throw new TypeError('createWshServer: extensions must be an object of handlers');
-      const attach = createConnectionFactory({
+      return createConnectionFactory({
         authorize, execRunner, execOptions, pty: ptyConfig, files, bindTimeoutMs, log: onLog,
         methods, hostKey: host_, rateLimit, extensions, mcp: mcpHost, rpc: rpcHost, gateway: gatewayCfg, sessions: registry, relay: hub,
       });
+    })();
+    ready.catch(() => { ready = null; });
+    return ready;
+  }
+
+  return {
+    async listen() {
+      if (wss) throw new Error('createWshServer: already listening');
+      let WebSocketServer;
+      try {
+        ({ WebSocketServer } = await import('ws'));
+      } catch (err) {
+        throw new Error('@johnhenry/wsh/server needs the "ws" package: npm install ws', { cause: err });
+      }
+      const attach = await start();
 
       if (tls) {
         const { createServer } = await import('node:https');
@@ -172,20 +186,45 @@ export function createWshServer({
       return bound;
     },
 
+    /**
+     * Serve a pre-upgraded transport: an already-accepted WebSocket-like duplex (see `socket.mjs`) that the embedder's
+     * own HTTP server, Worker or test upgraded. Same auth, features and session registry as `listen()`'s connections, and
+     * no listener of this server's own is needed -- `accept()` works without `listen()`, and with both.
+     * `remote: { address, headers }` is what the embedder knows of the peer (`address` keys the password-failure throttle).
+     * `close()` drops every accepted socket. Resolves once the connection is attached.
+     *
+     * @param {object} socket - `send`, `close`, `readyState`, and `on` or `addEventListener`
+     * @param {{ remote?: { address?: string, headers?: object } }} [options]
+     * @returns {Promise<{ close(): void }>}
+     */
+    async accept(socket, options = {}) {
+      const handle = await bindSocket(socket, start(), options);
+      const entry = { socket, handle };
+      accepted.add(entry);
+      const forget = () => accepted.delete(entry);
+      if (typeof socket.addEventListener === 'function') socket.addEventListener('close', forget);
+      else socket.on('close', forget);
+      return handle;
+    },
+
     async close() {
-      if (!wss) return;
+      for (const entry of [...accepted]) entry.handle.close();
+      accepted.clear();
       const server = wss;
       wss = null;
       bound = null;
-      for (const client of server.clients) client.terminate();
-      await wt?.close();
-      wt = null;
-      await new Promise((resolve) => server.close(resolve));
-      if (httpsServer) { const h = httpsServer; httpsServer = null; await new Promise((resolve) => h.close(resolve)); }
+      if (server) {
+        for (const client of server.clients) client.terminate();
+        await wt?.close();
+        wt = null;
+        await new Promise((resolve) => server.close(resolve));
+        if (httpsServer) { const h = httpsServer; httpsServer = null; await new Promise((resolve) => h.close(resolve)); }
+      }
       registry?.closeAll();
       registry = null;
       hub?.closeAll();
       hub = null;
+      ready = null;
     },
 
     address() {

package/src/server/pty.mjs

@@ -17,7 +17,7 @@ export function normalizePty(pty) {
   }
   return {
     spawn: pty.spawn,
-    shell: pty.shell ?? process.env.SHELL ?? '/bin/sh',
+    shell: pty.shell ?? globalThis.process?.env?.SHELL ?? '/bin/sh',
     cwd: pty.cwd,
     env: pty.env,
     term: pty.term ?? 'xterm-256color',

package/src/server/sessions.mjs

@@ -20,7 +20,8 @@ import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypt
 export const DEFAULT_RING_BYTES = 1024 * 1024;
 export const DEFAULT_DETACH_TTL_MS = 300_000;
 export const DEFAULT_MAX_DETACHED = 16;
-export const MAX_ATTACHMENTS = 16;
+import { MAX_ATTACHMENTS } from './constants.mjs';
+export { MAX_ATTACHMENTS };
 
 const NO_EXPIRY = Buffer.alloc(8, 0xff);
 

package/src/server/socket.mjs

@@ -0,0 +1,73 @@
+/**
+ * Serve a pre-upgraded transport: an already-accepted WebSocket-like duplex handed to a host by whoever did the
+ * upgrade (an HTTP server of the embedder's, a Worker, a message port wrapper, a test). Browser-safe -- it touches
+ * nothing but the object it is given -- and shared by `createWshServer().accept()` and `createMemoryHost()`.
+ *
+ * The duplex needs `send(bytes)`, `close(code?)`, `readyState` (1 = open) and either Node-style `on(event, fn)`
+ * (`ws`) or `addEventListener(event, fn)` (browsers, Workers, undici). Incoming frames must be binary; a text frame
+ * is ignored, as the QMux framing never carries one.
+ */
+
+const OPEN = 1;
+
+/** @param {unknown} data - a message payload as `ws` (Buffer, ArrayBuffer, Buffer[]) or a browser (ArrayBuffer, view, Blob) delivers it */
+async function toBytes(data) {
+  if (data instanceof Uint8Array) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (Array.isArray(data)) {
+    const parts = await Promise.all(data.map(toBytes));
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0));
+    let off = 0;
+    for (const p of parts) { out.set(p, off); off += p.byteLength; }
+    return out;
+  }
+  if (data && typeof data.arrayBuffer === 'function') return new Uint8Array(await data.arrayBuffer());
+  return null;
+}
+
+/**
+ * @param {object} socket - the WebSocket-like duplex
+ * @param {Promise<(opts: object) => { receive: Function, close: Function }>} ready - resolves to the connection factory's `attach`
+ * @param {{ remote?: { address?: string, headers?: object } }} [options] - what the host knows about the peer
+ *   (`address` keys the password-failure throttle; the default key is shared by every socket without one)
+ * @returns {Promise<{ close(): void }>} resolves once the connection is attached; `close()` drops it
+ */
+export function bindSocket(socket, ready, { remote = {} } = {}) {
+  if (!socket || typeof socket.send !== 'function' || typeof socket.close !== 'function') {
+    throw new TypeError('accept: socket must be a WebSocket-like duplex with send() and close()');
+  }
+  const listen = typeof socket.addEventListener === 'function'
+    ? (event, fn) => socket.addEventListener(event, (ev) => fn(event === 'message' ? ev?.data : ev))
+    : typeof socket.on === 'function'
+      ? (event, fn) => socket.on(event, fn)
+      : null;
+  if (!listen) throw new TypeError('accept: socket must support addEventListener() or on()');
+  try { socket.binaryType = 'arraybuffer'; } catch { /* read-only on some implementations; toBytes copes with any */ }
+
+  // Listeners are attached now, before the host has finished starting, and the frames they see are
+  // chained behind `ready`: a peer that speaks first (a client's QMux handshake) is not dropped.
+  let conn = null;
+  let closed = false;
+  let chain = ready.then((attach) => {
+    if (closed) return;
+    conn = attach({
+      send: (bytes) => { if (socket.readyState === OPEN) socket.send(bytes); },
+      remote: { address: remote.address, headers: remote.headers ?? {} },
+      closeTransport: () => { try { socket.close(1000); } catch { /* already closed */ } },
+    });
+  });
+  const drop = () => { if (closed) return; closed = true; chain = chain.then(() => conn?.close()).catch(() => {}); };
+  listen('message', (data) => {
+    chain = chain.then(async () => {
+      if (closed || !conn) return;
+      const bytes = await toBytes(data);
+      if (bytes && !closed) conn.receive(bytes);
+    }).catch(() => {});
+  });
+  listen('close', drop);
+  listen('error', () => {});
+  return chain.then(() => ({
+    close() { drop(); try { socket.close(1000); } catch { /* already closed */ } },
+  }));
+}

package/src/transport-ws.mjs

@@ -97,6 +97,9 @@ class QMuxStreamAdapter {
   }
 }
 
+/** `WebSocket.OPEN` (spelled out so a substitute constructor need not define it). */
+const WS_OPEN = 1;
+
 // ── WebSocket transport ──────────────────────────────────────────────
 
 /**
@@ -133,6 +136,19 @@ export class WebSocketTransport extends WshTransport {
    */
   #inbox = new SerialQueue((raw) => this.#handleControlBytes(raw));
 
+  /** @type {typeof WebSocket} */
+  #WebSocket;
+
+  /**
+   * @param {object} [options]
+   * @param {typeof WebSocket} [options.WebSocket] - A WebSocket constructor to dial with instead of the global one: a
+   *   test double, or the in-memory host's (`createMemoryHost().WebSocket`, see `memory-host.mjs`).
+   */
+  constructor({ WebSocket: Impl } = {}) {
+    super();
+    this.#WebSocket = Impl;
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────────────
 
   /** @override */
@@ -149,7 +165,7 @@ export class WebSocketTransport extends WshTransport {
         .replace(/^https:\/\//, 'wss://')
         .replace(/^http:\/\//, 'ws://');
 
-      const ws = new WebSocket(wsUrl);
+      const ws = new (this.#WebSocket ?? WebSocket)(wsUrl);
       ws.binaryType = 'arraybuffer';
       this.#ws = ws;
 
@@ -316,7 +332,7 @@ export class WebSocketTransport extends WshTransport {
    * @param {Uint8Array} data
    */
   #send(data) {
-    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+    if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
       throw new Error('WebSocket is not open');
     }
     this.#ws.send(data);