@johnhenry/wsh 0.17.0 → 0.18.0

package/README.md

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

package/package.json

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

package/src/client.mjs

@@ -29,6 +29,7 @@ import {
   keyExchange as keyExchangeMsg,
   fileOp as fileOpMsg,
   fileChunk as fileChunkMsg,
+  authorizedKeyAdd as authorizedKeyAddMsg,
   policyEval as policyEvalMsg, policyUpdate as policyUpdateMsg,
   detach as detachMsg,
   sessionListRequest as sessionListRequestMsg,
@@ -62,6 +63,13 @@ const DEFAULT_OPEN_TIMEOUT   = 10_000;  // ms
  */
 export const MCP_CALL_ID_FEATURE = 'mcp-call-id';
 
+/**
+ * ServerHello feature: the host discovers a client-opened exec data stream
+ * on its own (the transport announces it), so the client must NOT write the
+ * one-byte "primer" -- against such a host it would reach the process's stdin.
+ */
+export const STREAM_ANNOUNCE_FEATURE = 'stream-announce';
+
 /**
  * Reject a missing argument that maps to a `required: true` wire field.
  *
@@ -586,9 +594,14 @@ export class WshClient {
    * @param {number} [opts.rows=24] - Initial terminal rows
    * @param {object} [opts.env] - Environment variables
    * @param {number} [opts.timeout] - Timeout in ms
+   * @param {boolean} [opts.primer=true] - For stream-mode `exec` sessions: write
+   *   the one-byte "primer" some hosts need to discover the client-opened data
+   *   stream (without it they never bind the stream and drop all output).
+   *   Skipped automatically against a host advertising `stream-announce`; pass
+   *   `false` to never send it (e.g. a host that forwards stdin verbatim).
    * @returns {Promise<WshSession>}
    */
-  async openSession({ type = 'pty', command, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT } = {}) {
+  async openSession({ type = 'pty', command, cols = 80, rows = 24, env, timeout = DEFAULT_OPEN_TIMEOUT, primer = true } = {}) {
     this.#assertAuthenticated('openSession');
     const requestedChannelId = this._nextChannelId();
 
@@ -604,6 +617,7 @@ export class WshClient {
       const entry = {
         mode: 'session',
         kind: type,
+        primer,
         requestedChannelId,
         resolve,
         reject,
@@ -841,9 +855,10 @@ export class WshClient {
    * @param {CryptoKeyPair} [opts.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 } = {}) {
+  static async exec(url, command, { username, keyPair, password, timeout = DEFAULT_EXEC_TIMEOUT, primer = true } = {}) {
     const client = new WshClient();
     const chunks = [];
     let exitCode = -1;
@@ -851,7 +866,7 @@ export class WshClient {
     try {
       await client.connect(url, { username, keyPair, password });
 
-      const session = await client.openSession({ type: 'exec', command });
+      const session = await client.openSession({ type: 'exec', command, primer });
 
       await new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
@@ -1738,6 +1753,45 @@ export class WshClient {
   /** Rename a remote file or directory. */
   async fileRename(oldPath, newPath, timeout) { return this.fileOperation('rename', oldPath, {}, timeout); }
 
+  // ── Authorized-key management (wsh #59) ───────────────────────────
+
+  /**
+   * Install a raw 32-byte Ed25519 public key into the remote host's
+   * ~/.wsh/authorized_keys via the AuthorizedKeyAdd protocol message.
+   *
+   * Replaces `wsh copy-id`'s CLI-only, shell-command-built approach
+   * (`crates/wsh-cli/src/commands/copy_id.rs`) with a real protocol
+   * message every implementation can call -- including this one, the
+   * browser SDK, which previously had no way to install a key at all
+   * (no shell channel to build a command string for). See copy_id.rs's
+   * doc comment for the full security reasoning: an authenticated
+   * connection already has unrestricted exec/file access to this exact
+   * file, so this adds no new privilege boundary.
+   *
+   * Idempotent: installing an already-present key resolves
+   * `{ added: false }` rather than duplicating the line or erroring.
+   *
+   * @param {Uint8Array} publicKeyRaw - Raw 32-byte Ed25519 public key
+   * @param {string} [comment] - Trailing comment for the authorized_keys line
+   * @param {number} [timeout=10000]
+   * @returns {Promise<{ added: boolean }>}
+   */
+  async addAuthorizedKey(publicKeyRaw, comment, timeout = DEFAULT_OPEN_TIMEOUT) {
+    this.#assertAuthenticated('addAuthorizedKey');
+    await this.#transport.sendControl(
+      authorizedKeyAddMsg({ publicKey: publicKeyRaw, comment })
+    );
+    const result = await this.#waitForMessage(
+      [MSG.AUTHORIZED_KEY_RESULT],
+      timeout,
+      'Timed out waiting for authorized-key-add result'
+    );
+    if (!result.success) {
+      throw new Error(result.error_message || 'key installation refused');
+    }
+    return { added: !!result.added };
+  }
+
   // ── Policy Engine ─────────────────────────────────────────────────
 
   /**
@@ -2105,8 +2159,20 @@ export class WshClient {
       // so channel-scoped control messages arriving before the stream
       // finishes binding still route correctly.
       this.#transport.openStream().then(
-        (stream) => {
+        async (stream) => {
           session._bind(stream.readable, stream.writable);
+          // The transport has already announced the stream, which is all a
+          // current host needs. Older hosts only bind a stream on its first
+          // byte, so exec (which has no stdin to send) writes a one-byte
+          // primer they strip -- unless the host says it needs none.
+          if (pending.kind === 'exec' && pending.primer && !this.hasFeature(STREAM_ANNOUNCE_FEATURE)) {
+            try {
+              await session.write(new Uint8Array([0]));
+            } catch (err) {
+              pending.reject(err);
+              return;
+            }
+          }
           pending.resolve(session);
         },
         (err) => pending.reject(err)