@peers-app/peers-sdk 0.25.5 → 0.25.7

package/dist/device/connection.js

@@ -6,8 +6,19 @@ const data_1 = require("../data");
 const keys_1 = require("../keys");
 const peer_device_1 = require("../types/peer-device");
 const utils_1 = require("../utils");
+const frame_cipher_1 = require("./frame-cipher");
 const socket_type_1 = require("./socket.type");
-/** Authenticated RPC connection between two Peers devices. */
+/**
+ * Authenticated RPC connection between two Peers devices.
+ *
+ * The handshake (`doHandshake` on the client, `completeHandshake` on the
+ * server) authenticates both identities with signed, boxed messages. When both
+ * sockets support it, the handshake also agrees on per-connection frame-cipher
+ * keys (`frame-cipher.ts`) and arms the socket, after which every frame on the
+ * wire is sealed and the legacy per-message sign+box envelope is skipped.
+ * Against a peer that does not advertise `frameCrypto` the connection falls
+ * back to the legacy behaviour and logs a warning.
+ */
 class Connection {
     localDevice;
     localDeviceServerAddresses;
@@ -19,19 +30,40 @@ class Connection {
         publicKey: "",
         publicBoxKey: "",
     };
+    /**
+     * @deprecated Legacy transport classification, only consulted when the frame
+     * cipher is not armed. Removed once legacy peers are no longer supported.
+     */
     secureLocal = false;
+    /** @deprecated See {@link Connection.secureLocal}. */
     secureRemote = false;
+    /**
+     * Legacy per-message encryption override. Ignored once the frame cipher is
+     * armed. `"dont-encrypt-traffic-after-handshake"` is honoured only under
+     * `NODE_ENV=test`.
+     * @deprecated Removed with the legacy path.
+     */
     overrideEncryption;
+    /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel = socket_type_1.TrustLevel.Unknown;
+    /** Server-side hook fired shortly after a successful handshake. */
     onHandshakeComplete;
+    /** RPC timeout for {@link Connection.emit}. */
     timeoutMs = 60_000; // 60 seconds
+    /** Preferred chunk size for callers streaming raw bytes over this connection. */
     maxChunkSize = socket_type_1.DEFAULT_MAX_CHUNK_SIZE;
+    /** Maximum accepted clock skew between the two devices' handshake timestamps. */
     handshakeTimestampToleranceMs = peer_device_1.PeerDeviceConsts.CLOCK_SKEW_TOLERANCE_MS;
     _connectionAddress;
+    /** Normalized server address this connection was established against. */
     get connectionAddress() {
         return this._connectionAddress;
     }
+    /** Underlying transport socket. */
     socket;
+    pendingClientHandshake;
+    /** Server side: keys to arm for sending right after the handshake response frame. */
+    pendingSendArm;
     constructor(socket, localDevice, localDeviceServerAddresses, getTrustLevel = () => Promise.resolve(socket_type_1.TrustLevel.Unknown)) {
         this.localDevice = localDevice;
         this.localDeviceServerAddresses = localDeviceServerAddresses;
@@ -42,6 +74,8 @@ class Connection {
         if (!socket.id) {
             socket.id = (0, utils_1.newid)();
         }
+        // Streams bypass RPC verification; hold them until the handshake decides.
+        socket.setPlaintextStreamsAllowed?.(false);
         // Only the server side of a connection should expose these methods
         this.exposeRPC("close", () => {
             (0, utils_1.sleep)(100).then(() => {
@@ -59,32 +93,40 @@ class Connection {
                 return trustLevel;
             });
             this.exposeRPC("requestDeviceInfo", this.localDevice.getDeviceInfo.bind(this.localDevice));
-            this.exposeRPC("completeHandshake", async (handshakeBox) => {
-                const handshakeResponse = await this.completeHandshake(handshakeBox);
-                return handshakeResponse;
-            });
+            // Registered directly on the socket rather than through `on()`: the
+            // response must always be signed and boxed by the handshake itself (it
+            // carries the server's ephemeral key), and the reply callback needs the
+            // transport hint that arms the send cipher after this exact frame.
+            this.socket.on("completeHandshake", this.handleCompleteHandshakeRPC);
             this.exposeRPC("requestSecure", () => {
                 this.secureRemote = true;
                 return !this.encryptTraffic;
             });
         }
     }
+    /** True once the remote identity has been authenticated by the handshake. */
     get verified() {
         return this._verified;
     }
+    /** True when every frame on this connection is sealed by the frame cipher. */
+    get frameCipherArmed() {
+        return this.socket.frameCipherArmed === true;
+    }
     /**
-     * Determines whether to apply application-level encryption (sign + box).
-     *
-     * Encryption is SKIPPED when:
-     * - Binary transports (wrtc): Set secureLocal=true & secureRemote=true
-     *   because transport-level encryption (DTLS-SRTP, noise) handles security
-     * - Secure WebSockets (wss/https): Both sides confirm secure protocol after handshake
+     * Whether to apply the legacy per-message envelope (sign + box) to RPC payloads.
      *
-     * Encryption is APPLIED when:
-     * - Insecure WebSockets (ws/http): Data travels over unencrypted channel
+     * Always false once the frame cipher is armed: the frame layer already gives
+     * confidentiality, integrity, and sender binding for every frame. Otherwise
+     * (legacy peer) the transport classification below applies:
+     * - skipped when both sides agreed the transport is secure (`secureLocal && secureRemote`)
+     * - applied on plain `ws` / `http`
      */
     get encryptTraffic() {
-        if (this.overrideEncryption === "dont-encrypt-traffic-after-handshake") {
+        if (this.socket.frameCipherArmed) {
+            return false;
+        }
+        if (this.overrideEncryption === "dont-encrypt-traffic-after-handshake" &&
+            process.env.NODE_ENV === "test") {
             return false;
         }
         if (this.overrideEncryption === "encrypt-traffic-regardless-of-protocol") {
@@ -93,12 +135,34 @@ class Connection {
         // Encrypt only if EITHER side is using an insecure protocol
         return !(this.secureLocal && this.secureRemote);
     }
+    /** Copy of the authenticated remote device identity (empty before the handshake). */
     get remoteDeviceInfo() {
         return { ...this._remoteDeviceInfo };
     }
+    /** Socket ID shared by both ends; also the frame-cipher AAD and HKDF salt. */
     get connectionId() {
         return this.socket.id || "";
     }
+    get supportsFrameCrypto() {
+        return typeof this.socket.armFrameCipher === "function";
+    }
+    warnLegacyPeer(deviceId) {
+        console.warn(`[Connection] Peer ${deviceId} does not support frame encryption; using legacy per-message encryption`, { connectionId: this.connectionId, transport: this.socket.transportType ?? "unknown" });
+    }
+    handleCompleteHandshakeRPC = async (args, callback) => {
+        try {
+            const [handshakeBox] = args;
+            const response = await this.completeHandshake(handshakeBox);
+            const boxed = this.localDevice.signAndBoxDataForDevice(response, this._remoteDeviceInfo);
+            const armAfter = this.pendingSendArm;
+            this.pendingSendArm = undefined;
+            callback(null, boxed, armAfter ? { armFrameCipherAfter: armAfter } : undefined);
+        }
+        catch (e) {
+            console.error("Error handling completeHandshake", e);
+            callback({ error: e?.message ?? String(e), errorType: "RPC_ERROR" });
+        }
+    };
     /**
      * Get connection throughput stats with calculated rates.
      * Returns bytes/messages sent/received and both average and recent rates.
@@ -171,11 +235,12 @@ class Connection {
             return fn(...args);
         });
     }
+    /** Calls a remote RPC handler and resolves with its result (rejects on error or timeout). */
     emit(eventName, ...args) {
         return new Promise((resolve, reject) => {
             try {
-                // Apply app-level encryption for insecure transports (ws/http)
-                // Skipped for secure transports (wss/https, wrtc)
+                // Legacy per-message envelope; skipped when the frame cipher is armed
+                // or both sides agreed the transport is secure.
                 if (this._verified && this.encryptTraffic) {
                     args = this.localDevice.signAndBoxDataForDevice(args, this._remoteDeviceInfo);
                 }
@@ -215,6 +280,11 @@ class Connection {
             }
         });
     }
+    /**
+     * Registers an RPC handler. Events other than the handshake set are rejected
+     * until the connection is verified; payloads use the legacy envelope only
+     * when {@link Connection.encryptTraffic} is true.
+     */
     on(eventName, handler) {
         const safeEvents = [
             "requestDeviceInfo",
@@ -230,13 +300,12 @@ class Connection {
             }
             let result;
             try {
-                // Decrypt incoming args for insecure transports (ws/http)
-                // Skipped for secure transports (wss/https, wrtc)
+                // Legacy per-message envelope; skipped when the frame cipher is armed
+                // or both sides agreed the transport is secure.
                 if (this._verified && this.encryptTraffic) {
                     args = this.localDevice.openBoxedAndSignedData(args);
                 }
                 result = await handler(...args);
-                // Encrypt outgoing result for insecure transports
                 if (this._verified && this.encryptTraffic) {
                     result = this.localDevice.signAndBoxDataForDevice(result, this._remoteDeviceInfo);
                 }
@@ -257,9 +326,15 @@ class Connection {
             }
         });
     }
+    /** Removes RPC handlers for `eventName`, or all handlers when omitted. */
     removeAllListeners(eventName) {
         this.socket.removeAllListeners(eventName);
     }
+    /**
+     * Clears the authenticated state so a new handshake can run. Does not disarm
+     * an already-armed frame cipher: the socket stays sealed with the current
+     * keys and a subsequent handshake replaces them.
+     */
     reset() {
         this._connectionAddress = undefined;
         this._remoteDeviceInfo = {
@@ -272,14 +347,46 @@ class Connection {
         this.secureLocal = false;
         this.secureRemote = false;
         this.trustLevel = socket_type_1.TrustLevel.Unknown;
+        this.pendingClientHandshake?.ephemeralSecretKey.fill(0);
+        this.pendingClientHandshake = undefined;
+        this.pendingSendArm = undefined;
+        this.socket.setPlaintextStreamsAllowed?.(false);
     }
+    /**
+     * Client side: builds the signed handshake (advertising frame-cipher support
+     * with a fresh ephemeral key when the socket can arm one) and boxes it to the
+     * remote device.
+     */
     initiateHandshake(serverAddress, remoteDeviceInfo) {
         if (remoteDeviceInfo) {
             this._remoteDeviceInfo = remoteDeviceInfo;
         }
-        const handshake = this.localDevice.getHandshake(this.connectionId, serverAddress);
+        let frameCrypto;
+        this.pendingClientHandshake?.ephemeralSecretKey.fill(0);
+        this.pendingClientHandshake = undefined;
+        let ephemeralSecretKey;
+        if (this.supportsFrameCrypto) {
+            const ephemeral = (0, keys_1.newEphemeralBoxKeyPair)();
+            ephemeralSecretKey = ephemeral.secretKey;
+            frameCrypto = { version: 1, ephemeralBoxKey: (0, keys_1.encodeBase64)(ephemeral.publicKey) };
+        }
+        const handshake = this.localDevice.getHandshake(this.connectionId, serverAddress, frameCrypto);
+        if (ephemeralSecretKey) {
+            this.pendingClientHandshake = {
+                ephemeralSecretKey,
+                timestamp: handshake.contents.timestamp,
+            };
+        }
         return this.localDevice.boxDataForDevice(handshake, this._remoteDeviceInfo);
     }
+    /**
+     * Server side: verifies the client's handshake, resolves trust, and returns
+     * the (unsigned) response for the caller to sign and box. When the client
+     * offered `frameCrypto` and this socket can arm a cipher, derives the frame
+     * keys, arms the receive direction immediately, and schedules the send
+     * direction to arm right after the response frame (see
+     * {@link Connection.handleCompleteHandshakeRPC}).
+     */
     async completeHandshake(boxedHandshake) {
         const signedHandshake = this.localDevice.openBoxWithSecretKey(boxedHandshake);
         const _handshake = data_1.deviceHandshakeSchema.parse((0, keys_1.openSignedObject)(signedHandshake));
@@ -291,11 +398,27 @@ class Connection {
         const thisServerAddress = this.localDeviceServerAddresses?.find((a) => a === clientServerAddress) ||
             this.localDeviceServerAddresses?.[0] ||
             "unknown";
-        // only set local secure if the server address matches the client's address and the address is using https
+        // Legacy classification: only meaningful when the frame cipher will not be armed.
         this.secureLocal =
             clientServerAddress === thisServerAddress && thisServerAddress.startsWith("https");
         this._connectionAddress = thisServerAddress;
-        const handshakeResponse = this.localDevice.handshakeResponse(signedHandshake, this.connectionId, thisServerAddress);
+        let frameCrypto;
+        let frameKeys;
+        if (_handshake.frameCrypto && this.supportsFrameCrypto) {
+            const ephemeral = (0, keys_1.newEphemeralBoxKeyPair)();
+            frameCrypto = { version: 1, ephemeralBoxKey: (0, keys_1.encodeBase64)(ephemeral.publicKey) };
+            const derived = this.localDevice.deriveFrameKeys({
+                remotePublicBoxKey: _handshake.publicBoxKey,
+                ephemeralSecretKey: ephemeral.secretKey,
+                remoteEphemeralBoxKey: _handshake.frameCrypto.ephemeralBoxKey,
+                connectionId: this.connectionId,
+                clientDeviceId: _handshake.deviceId,
+                serverDeviceId: this.localDevice.deviceId,
+                timestamp: _handshake.timestamp,
+            });
+            frameKeys = (0, frame_cipher_1.frameKeysForRole)(derived, "server");
+        }
+        const handshakeResponse = this.localDevice.handshakeResponse(signedHandshake, this.connectionId, thisServerAddress, frameCrypto);
         this._remoteDeviceInfo = {
             userId: _handshake.userId,
             deviceId: _handshake.deviceId,
@@ -310,8 +433,17 @@ class Connection {
             this.emit("reset");
             throw new Error("Untrusted connection");
         }
-        // console.log(`Connection ${this.connectionId} verified on server side with trust level ${this.trustLevel}`);
         this._verified = true;
+        if (frameKeys && this.socket.armFrameCipher) {
+            // The client seals everything after it reads our response, so receive
+            // can arm now; send arms after the response frame goes out.
+            this.socket.armFrameCipher(frameKeys, "receive");
+            this.pendingSendArm = frameKeys;
+        }
+        else {
+            this.warnLegacyPeer(_handshake.deviceId);
+            this.socket.setPlaintextStreamsAllowed?.(true);
+        }
         if (this.onHandshakeComplete) {
             setTimeout(() => {
                 this.onHandshakeComplete?.(this._remoteDeviceInfo);
@@ -319,6 +451,11 @@ class Connection {
         }
         return handshakeResponse;
     }
+    /**
+     * Client side: runs the full handshake against `remoteAddress`. On success
+     * the remote identity is verified and, if both sockets support it, the
+     * frame cipher is armed in both directions before this resolves.
+     */
     async doHandshake(remoteAddress) {
         remoteAddress = normalizeAddress(remoteAddress);
         this.reset();
@@ -354,12 +491,33 @@ class Connection {
         this._remoteDeviceInfo = currentRemoteDeviceInfo;
         this._verified = true;
         this._connectionAddress = remoteAddress;
+        const pending = this.pendingClientHandshake;
+        this.pendingClientHandshake = undefined;
+        if (pending && handshakeResponse.frameCrypto && this.socket.armFrameCipher) {
+            const derived = this.localDevice.deriveFrameKeys({
+                remotePublicBoxKey: handshakeResponse.publicBoxKey,
+                ephemeralSecretKey: pending.ephemeralSecretKey,
+                remoteEphemeralBoxKey: handshakeResponse.frameCrypto.ephemeralBoxKey,
+                connectionId: this.connectionId,
+                clientDeviceId: this.localDevice.deviceId,
+                serverDeviceId: handshakeResponse.deviceId,
+                timestamp: pending.timestamp,
+            });
+            // The server armed receive before replying and send right after; from
+            // here on both directions are sealed.
+            this.socket.armFrameCipher((0, frame_cipher_1.frameKeysForRole)(derived, "client"));
+        }
+        else {
+            pending?.ephemeralSecretKey.fill(0);
+            this.warnLegacyPeer(handshakeResponse.deviceId);
+            this.socket.setPlaintextStreamsAllowed?.(true);
+        }
+        // Legacy classification, only consulted when the frame cipher is not armed.
         const secureProtocols = ["https", "wss", "wrtc"];
-        // const secureProtocols = ['https', 'wss',]
         this.secureLocal =
             secureProtocols.some((s) => remoteAddress.startsWith(s)) &&
                 handshakeResponse.serverAddress === remoteAddress;
-        if (this.secureLocal) {
+        if (this.secureLocal && !this.socket.frameCipherArmed) {
             await this.emit("requestSecure");
         }
         this.trustLevel = await this.getTrustLevel(currentRemoteDeviceInfo, true);
@@ -368,7 +526,6 @@ class Connection {
             this.emit("reset");
             throw new Error("Untrusted connection");
         }
-        // console.log(`Connection ${this.connectionId} (${remoteAddress}) verified on client side with trust level ${this.trustLevel}`);
         return handshakeResponse;
     }
     closeLocal() {
@@ -376,6 +533,7 @@ class Connection {
         this.removeAllListeners();
         this.socket.disconnect(true);
     }
+    /** Round-trip time in milliseconds. @throws if the connection is not verified */
     async ping() {
         if (!this._verified) {
             throw new Error("Cannot ping unverified connection");
@@ -385,6 +543,7 @@ class Connection {
         return Date.now() - startTime;
     }
     closed = false;
+    /** Notifies the peer (best effort, 100 ms) then tears down the local side. */
     async close() {
         if (this.closed)
             return;

package/dist/device/connection.test.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const nacl = require("tweetnacl");
 const keys_1 = require("../keys");
 const utils_1 = require("../utils");
+const binary_peer_connection_v2_1 = require("./binary-peer-connection-v2");
 const connection_1 = require("./connection");
 const device_1 = require("./device");
+const frame_cipher_1 = require("./frame-cipher");
 function createTestSocket(localHandlers, remoteHandlers) {
     const socket = {
         id: (0, utils_1.newid)(),
@@ -357,4 +360,225 @@ describe(connection_1.Connection, () => {
             expect(serverConnection.verified).toBe(false);
         });
     });
+    // ─── Frame cipher ──────────────────────────────────────────────────────────
+    //
+    // These run over real binary peer sockets (the production framing) so the
+    // handshake actually arms the cipher and the wire can be inspected.
+    describe("frame cipher", () => {
+        class TapPeer {
+            other;
+            sent = [];
+            destroyed = false;
+            dataHandlers = [];
+            closeHandlers = [];
+            on(event, handler) {
+                if (event === "data")
+                    this.dataHandlers.push(handler);
+                if (event === "close")
+                    this.closeHandlers.push(handler);
+            }
+            send(data) {
+                const bytes = Buffer.from(data);
+                this.sent.push(bytes);
+                const target = this.other;
+                if (target) {
+                    setImmediate(() => {
+                        for (const h of target.dataHandlers)
+                            h(bytes);
+                    });
+                }
+            }
+            destroy() {
+                this.destroyed = true;
+                for (const h of this.closeHandlers)
+                    h();
+            }
+        }
+        function pair(protocol, opts = {}) {
+            const clientPeer = new TapPeer();
+            const serverPeer = new TapPeer();
+            clientPeer.other = serverPeer;
+            serverPeer.other = clientPeer;
+            const connectionId = (0, utils_1.newid)();
+            const userId = (0, utils_1.newid)();
+            const clientDevice = new device_1.Device(userId, (0, utils_1.newid)(), (0, keys_1.newKeys)());
+            const serverDevice = new device_1.Device(userId, (0, utils_1.newid)(), (0, keys_1.newKeys)());
+            const client = (0, binary_peer_connection_v2_1.wrapBinaryPeer)(connectionId, clientPeer, clientDevice, true, { protocol });
+            const server = (0, binary_peer_connection_v2_1.wrapBinaryPeer)(connectionId, serverPeer, serverDevice, false, { protocol });
+            // A "legacy" peer is one whose socket cannot arm a cipher, so it never advertises frameCrypto.
+            if (opts.legacyClient)
+                delete client.socket.armFrameCipher;
+            if (opts.legacyServer)
+                delete server.socket.armFrameCipher;
+            return {
+                clientPeer,
+                serverPeer,
+                client,
+                server,
+                clientDevice,
+                serverDevice,
+                address: `${protocol}://${connectionId}`,
+            };
+        }
+        function wire(...peers) {
+            return peers.flatMap((p) => p.sent);
+        }
+        for (const protocol of ["ws", "wrtc"]) {
+            it(`arms both sides after the handshake on ${protocol} and stops boxing RPC`, async () => {
+                const { client, server, clientDevice, serverDevice, clientPeer, serverPeer, address } = pair(protocol);
+                const clientBox = jest.spyOn(clientDevice, "signAndBoxDataForDevice");
+                const serverBox = jest.spyOn(serverDevice, "signAndBoxDataForDevice");
+                const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+                try {
+                    await client.doHandshake(address);
+                    expect(client.frameCipherArmed).toBe(true);
+                    expect(server.frameCipherArmed).toBe(true);
+                    expect(client.verified).toBe(true);
+                    expect(server.verified).toBe(true);
+                    expect(client.encryptTraffic).toBe(false);
+                    expect(server.encryptTraffic).toBe(false);
+                    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("does not support frame encryption"), expect.anything());
+                    // The only box+sign so far is the server's handshake response.
+                    expect(serverBox).toHaveBeenCalledTimes(1);
+                    expect(clientBox).toHaveBeenCalledTimes(0);
+                    // Application RPC: no envelope, but sealed on the wire.
+                    const marker = `marker-${(0, utils_1.newid)()}`;
+                    server.exposeRPC("echo", async (s) => `${s}!`);
+                    const clientBefore = clientPeer.sent.length;
+                    const serverBefore = serverPeer.sent.length;
+                    expect(await client.emit("echo", marker)).toBe(`${marker}!`);
+                    expect(clientBox).toHaveBeenCalledTimes(0);
+                    expect(serverBox).toHaveBeenCalledTimes(1);
+                    const rpcFrames = [
+                        ...clientPeer.sent.slice(clientBefore),
+                        ...serverPeer.sent.slice(serverBefore),
+                    ];
+                    expect(rpcFrames.length).toBe(2);
+                    for (const frame of rpcFrames) {
+                        expect(frame[0]).toBe(frame_cipher_1.FRAME_ENC);
+                        expect(frame.indexOf(Buffer.from(marker))).toBe(-1);
+                    }
+                    // Streams: delivered and sealed.
+                    const payload = nacl.randomBytes(48);
+                    const received = new Promise((resolve) => server.socket.onRawBytes?.("s", (d) => resolve(d)));
+                    await client.socket.sendRawBytes?.("s", payload);
+                    expect(Buffer.from(await received)).toEqual(Buffer.from(payload));
+                    const last = clientPeer.sent[clientPeer.sent.length - 1];
+                    expect(last[0]).toBe(frame_cipher_1.FRAME_ENC);
+                    expect(last.indexOf(Buffer.from(payload))).toBe(-1);
+                }
+                finally {
+                    warn.mockRestore();
+                    clientPeer.destroy();
+                    serverPeer.destroy();
+                }
+            });
+        }
+        it("no longer double-encrypts over wrtc (finding 2)", async () => {
+            const { client, server, clientPeer, serverPeer, address } = pair("wrtc");
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+            try {
+                await client.doHandshake(address);
+                // Before: client {secureLocal: true, secureRemote: false}, server the
+                // reverse, encryptTraffic true on both. Now the cipher decides.
+                expect(client.encryptTraffic).toBe(false);
+                expect(server.encryptTraffic).toBe(false);
+                expect(client.frameCipherArmed).toBe(true);
+                // requestSecure is never sent when the cipher is armed.
+                const plaintextFrames = wire(clientPeer, serverPeer).filter((f) => f[0] !== frame_cipher_1.FRAME_ENC);
+                for (const frame of plaintextFrames) {
+                    expect(frame.indexOf(Buffer.from("requestSecure"))).toBe(-1);
+                }
+            }
+            finally {
+                warn.mockRestore();
+                clientPeer.destroy();
+                serverPeer.destroy();
+            }
+        });
+        it("only the handshake frames are plaintext, and the ephemeral keys are never in the clear", async () => {
+            const { client, clientPeer, serverPeer, address } = pair("ws");
+            await client.doHandshake(address);
+            const frames = wire(clientPeer, serverPeer);
+            // reset, requestDeviceInfo, completeHandshake: 3 requests + 3 replies in the clear.
+            const plaintext = frames.filter((f) => f[0] !== frame_cipher_1.FRAME_ENC);
+            expect(plaintext.length).toBe(6);
+            for (const frame of plaintext) {
+                expect(frame.indexOf(Buffer.from("ephemeralBoxKey"))).toBe(-1);
+            }
+            clientPeer.destroy();
+            serverPeer.destroy();
+        });
+        it("drops plaintext stream frames before the handshake completes", async () => {
+            const { client, server, clientPeer, serverPeer, address } = pair("ws");
+            let delivered = 0;
+            server.socket.onRawBytes?.("early", () => delivered++);
+            await client.socket.sendRawBytes?.("early", new Uint8Array([1, 2, 3]));
+            await (0, utils_1.sleep)(20);
+            expect(delivered).toBe(0);
+            expect(serverPeer.destroyed).toBe(false);
+            await client.doHandshake(address);
+            await client.socket.sendRawBytes?.("early", new Uint8Array([4]));
+            await (0, utils_1.sleep)(20);
+            expect(delivered).toBe(1);
+            clientPeer.destroy();
+            serverPeer.destroy();
+        });
+        for (const [label, opts] of [
+            ["legacy client", { legacyClient: true }],
+            ["legacy server", { legacyServer: true }],
+        ]) {
+            it(`falls back to the legacy envelope and warns against a ${label}`, async () => {
+                const { client, server, clientDevice, clientPeer, serverPeer, address } = pair("ws", opts);
+                const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+                const clientBox = jest.spyOn(clientDevice, "signAndBoxDataForDevice");
+                try {
+                    await client.doHandshake(address);
+                    expect(client.verified).toBe(true);
+                    expect(server.verified).toBe(true);
+                    expect(client.frameCipherArmed).toBe(false);
+                    expect(server.frameCipherArmed).toBe(false);
+                    // ws://: legacy classification says encrypt per message.
+                    expect(client.encryptTraffic).toBe(true);
+                    expect(server.encryptTraffic).toBe(true);
+                    expect(warn).toHaveBeenCalledWith(expect.stringContaining("does not support frame encryption"), expect.objectContaining({ transport: "ws" }));
+                    server.exposeRPC("echo", async (s) => `${s}!`);
+                    expect(await client.emit("echo", "hi")).toBe("hi!");
+                    expect(clientBox).toHaveBeenCalled();
+                    for (const frame of wire(clientPeer, serverPeer)) {
+                        expect(frame[0]).not.toBe(frame_cipher_1.FRAME_ENC);
+                    }
+                    // Plaintext streams are delivered once the legacy handshake verified the peer.
+                    let delivered = 0;
+                    server.socket.onRawBytes?.("legacy", () => delivered++);
+                    await client.socket.sendRawBytes?.("legacy", new Uint8Array([1]));
+                    await (0, utils_1.sleep)(20);
+                    expect(delivered).toBe(1);
+                }
+                finally {
+                    warn.mockRestore();
+                    clientPeer.destroy();
+                    serverPeer.destroy();
+                }
+            });
+        }
+        it("ignores dont-encrypt-traffic-after-handshake outside NODE_ENV=test", async () => {
+            const { client, clientPeer, serverPeer, address } = pair("ws", { legacyServer: true });
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+            const previous = process.env.NODE_ENV;
+            try {
+                await client.doHandshake(address);
+                client.overrideEncryption = "dont-encrypt-traffic-after-handshake";
+                expect(client.encryptTraffic).toBe(false);
+                process.env.NODE_ENV = "production";
+                expect(client.encryptTraffic).toBe(true);
+            }
+            finally {
+                process.env.NODE_ENV = previous;
+                warn.mockRestore();
+                clientPeer.destroy();
+                serverPeer.destroy();
+            }
+        });
+    });
 });