@peers-app/peers-sdk 0.25.5 → 0.25.7

package/dist/device/binary-peer-connection-v2.test.js

@@ -1,9 +1,11 @@
 "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 device_1 = require("./device");
+const frame_cipher_1 = require("./frame-cipher");
 // Mock binary peer for testing - simulates WebRTC peers
 class MockBinaryPeer {
     dataHandlers = [];
@@ -12,6 +14,8 @@ class MockBinaryPeer {
     otherPeer;
     _bufferedAmount = 0;
     destroyed = false;
+    /** Every frame handed to send(), in order (the "wire tap"). */
+    sent = [];
     on(event, handler) {
         if (event === "data") {
             this.dataHandlers.push(handler);
@@ -24,12 +28,13 @@ class MockBinaryPeer {
         }
     }
     send(data) {
+        const bytes = typeof data === "string"
+            ? Buffer.from(data)
+            : Buffer.isBuffer(data)
+                ? data
+                : Buffer.from(data);
+        this.sent.push(bytes);
         if (this.otherPeer) {
-            const bytes = typeof data === "string"
-                ? Buffer.from(data)
-                : Buffer.isBuffer(data)
-                    ? data
-                    : Buffer.from(data);
             // Simulate async delivery
             setImmediate(() => {
                 const handlers = this.otherPeer?.dataHandlers;
@@ -410,6 +415,213 @@ describe("binary-peer-connection-v2", () => {
             rPeer.destroy();
         });
     });
+    describe("frame cipher", () => {
+        function keyPair() {
+            const ab = nacl.randomBytes(32);
+            const ba = nacl.randomBytes(32);
+            return {
+                a: { sendKey: ab.slice(), receiveKey: ba.slice() },
+                b: { sendKey: ba.slice(), receiveKey: ab.slice() },
+            };
+        }
+        async function armedPair(protocol, connectionId = "conn") {
+            const { iPeer, rPeer } = await getMockPeerPair();
+            const socketA = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)(connectionId, iPeer, protocol);
+            const socketB = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)(connectionId, rPeer, protocol);
+            const keys = keyPair();
+            socketA.armFrameCipher?.(keys.a);
+            socketB.armFrameCipher?.(keys.b);
+            return { iPeer, rPeer, socketA, socketB };
+        }
+        function emit(socket, eventName, args) {
+            return new Promise((resolve, reject) => {
+                socket.emit(eventName, args, (err, res) => (err ? reject(err) : resolve(res)));
+            });
+        }
+        for (const protocol of ["ws", "wrtc"]) {
+            it(`round-trips RPC and streams when armed on ${protocol}, sealing every frame`, async () => {
+                const { iPeer, rPeer, socketA, socketB } = await armedPair(protocol);
+                expect(socketA.frameCipherArmed).toBe(true);
+                expect(socketB.frameCipherArmed).toBe(true);
+                const marker = `RPC-MARKER-${(0, utils_1.newid)()}`;
+                socketB.on("echo", (args, callback) => {
+                    callback(null, { got: args.marker, reply: `${marker}-reply` });
+                });
+                const result = await emit(socketA, "echo", { marker });
+                expect(result).toEqual({ got: marker, reply: `${marker}-reply` });
+                const streamMarker = nacl.randomBytes(64);
+                const received = new Promise((resolve) => socketB.onRawBytes?.("s", (d) => resolve(d)));
+                await socketA.sendRawBytes?.("s", streamMarker);
+                expect(Buffer.from(await received)).toEqual(Buffer.from(streamMarker));
+                // Wire tap: every frame is FRAME_ENC and neither marker appears on the wire.
+                const wire = [...iPeer.sent, ...rPeer.sent];
+                expect(wire.length).toBeGreaterThanOrEqual(3);
+                for (const frame of wire) {
+                    expect(frame[0]).toBe(frame_cipher_1.FRAME_ENC);
+                    expect(frame.indexOf(Buffer.from(marker))).toBe(-1);
+                    expect(frame.indexOf(Buffer.from(streamMarker))).toBe(-1);
+                }
+                iPeer.destroy();
+                rPeer.destroy();
+            });
+        }
+        it("seals an RPC reply that is sent after the local peer has already closed", async () => {
+            const { iPeer, rPeer, socketA, socketB } = await armedPair("wrtc");
+            const sentBefore = rPeer.sent.length;
+            socketB.on("echo", async (_args, callback) => {
+                // Tear down before the reply, as a handshake failure does when the
+                // confirmation handler resumes in a later microtask.
+                rPeer.destroy();
+                expect(socketB.connected).toBe(false);
+                await Promise.resolve();
+                callback(null, { ok: true });
+            });
+            await expect(emit(socketA, "echo", { n: 1 })).resolves.toEqual({ ok: true });
+            const replies = rPeer.sent.slice(sentBefore);
+            expect(replies.length).toBeGreaterThan(0);
+            for (const frame of replies) {
+                expect(frame[0]).toBe(frame_cipher_1.FRAME_ENC);
+            }
+            expect(socketB.frameCipherArmed).toBe(false);
+            iPeer.destroy();
+        });
+        it("keeps chunked RPC and stream frames within maxFramePayload including overhead", async () => {
+            const { iPeer, rPeer, socketA, socketB } = await armedPair("wrtc");
+            const maxFrame = 64 * 1024;
+            const large = new Uint8Array(200 * 1024);
+            for (let i = 0; i < large.length; i++)
+                large[i] = i % 256;
+            socketB.on("big", (args, callback) => {
+                callback(null, args.length);
+            });
+            expect(await emit(socketA, "big", large)).toBe(large.length);
+            const received = new Promise((resolve) => socketB.onRawBytes?.("big-stream", (d) => resolve(d)));
+            await socketA.sendRawBytes?.("big-stream", large);
+            expect((await received).length).toBe(large.length);
+            expect(iPeer.sent.length).toBeGreaterThan(6);
+            for (const frame of iPeer.sent) {
+                expect(frame.length).toBeLessThanOrEqual(maxFrame);
+                expect(frame[0]).toBe(frame_cipher_1.FRAME_ENC);
+            }
+            // Bytes the sealed frames are budgeted for are actually used: at least one full frame.
+            expect(iPeer.sent.some((f) => f.length === maxFrame)).toBe(true);
+            iPeer.destroy();
+            rPeer.destroy();
+        });
+        it("closes the connection when a plaintext frame arrives after arming", async () => {
+            const { iPeer } = await getMockPeerPair();
+            const socket = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", iPeer, "ws");
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+            try {
+                socket.armFrameCipher?.(keyPair().a);
+                iPeer.receive(new Uint8Array([0x00, 0, 0, 0, 0]));
+                expect(iPeer.destroyed).toBe(true);
+                expect(socket.connected).toBe(false);
+                expect(warn).toHaveBeenCalledWith(expect.stringContaining("plaintext frame"));
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it("closes the connection when a sealed frame arrives before arming", async () => {
+            const { iPeer } = await getMockPeerPair();
+            (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", iPeer, "ws");
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+            try {
+                iPeer.receive(new Uint8Array([frame_cipher_1.FRAME_ENC, ...new Uint8Array(20)]));
+                expect(iPeer.destroyed).toBe(true);
+                expect(warn).toHaveBeenCalledWith(expect.stringContaining("before frame cipher"));
+            }
+            finally {
+                warn.mockRestore();
+            }
+        });
+        it("closes the connection when a sealed frame fails authentication", async () => {
+            const { iPeer, rPeer, socketA } = await armedPair("ws");
+            const warn = jest.spyOn(console, "warn").mockImplementation(() => { });
+            try {
+                // Re-arm B with unrelated keys so A's frames fail to open.
+                const socketB = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", rPeer, "ws");
+                socketB.armFrameCipher?.(keyPair().b);
+                socketA.emit("x", {}, () => { });
+                await (0, utils_1.sleep)(20);
+                expect(rPeer.destroyed).toBe(true);
+                expect(warn).toHaveBeenCalledWith(expect.stringContaining("failed authentication"));
+            }
+            finally {
+                warn.mockRestore();
+                iPeer.destroy();
+            }
+        });
+        it("drops plaintext stream frames when plaintext streams are disallowed and not armed", async () => {
+            const { iPeer, rPeer } = await getMockPeerPair();
+            const socketA = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", iPeer, "ws");
+            const socketB = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", rPeer, "ws");
+            socketB.setPlaintextStreamsAllowed?.(false);
+            let delivered = 0;
+            socketB.onRawBytes?.("gated", () => delivered++);
+            await socketA.sendRawBytes?.("gated", new Uint8Array([1, 2, 3]));
+            await (0, utils_1.sleep)(20);
+            expect(delivered).toBe(0);
+            expect(rPeer.destroyed).toBe(false);
+            // Plaintext RPC still works before the handshake.
+            socketB.on("ping", (_a, cb) => cb(null, "pong"));
+            expect(await emit(socketA, "ping", {})).toBe("pong");
+            // Re-allowing (legacy peer path) delivers again.
+            socketB.setPlaintextStreamsAllowed?.(true);
+            await socketA.sendRawBytes?.("gated", new Uint8Array([4]));
+            await (0, utils_1.sleep)(20);
+            expect(delivered).toBe(1);
+            iPeer.destroy();
+            rPeer.destroy();
+        });
+        it("arms send after the reply frame when the callback carries armFrameCipherAfter", async () => {
+            const { iPeer, rPeer } = await getMockPeerPair();
+            const client = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", iPeer, "ws");
+            const server = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", rPeer, "ws");
+            const keys = keyPair();
+            server.on("completeHandshake", (_args, callback) => {
+                // Server: arm receive now, send after this reply (as Connection does).
+                server.armFrameCipher?.(keys.b, "receive");
+                expect(server.frameCipherArmed).toBe(false);
+                callback(null, { ok: true }, { armFrameCipherAfter: keys.b });
+            });
+            server.on("afterwards", (args, cb) => cb(null, `sealed:${args}`));
+            const reply = await emit(client, "completeHandshake", {});
+            expect(reply).toEqual({ ok: true });
+            // The reply itself was plaintext...
+            expect(rPeer.sent.length).toBe(1);
+            expect(rPeer.sent[0][0]).not.toBe(frame_cipher_1.FRAME_ENC);
+            // ...and the server is now fully armed.
+            expect(server.frameCipherArmed).toBe(true);
+            // Client arms both on receipt and everything after is sealed both ways.
+            client.armFrameCipher?.(keys.a);
+            expect(await emit(client, "afterwards", "x")).toBe("sealed:x");
+            expect(iPeer.sent[iPeer.sent.length - 1][0]).toBe(frame_cipher_1.FRAME_ENC);
+            expect(rPeer.sent[rPeer.sent.length - 1][0]).toBe(frame_cipher_1.FRAME_ENC);
+            iPeer.destroy();
+            rPeer.destroy();
+        });
+        it("arms send after the last chunk of a chunked reply", async () => {
+            const { iPeer, rPeer } = await getMockPeerPair();
+            const client = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", iPeer, "wrtc");
+            const server = (0, binary_peer_connection_v2_1.createBinaryPeerSocket)("conn", rPeer, "wrtc");
+            const keys = keyPair();
+            const bigReply = new Uint8Array(150 * 1024);
+            server.on("hs", (_args, callback) => {
+                server.armFrameCipher?.(keys.b, "receive");
+                callback(null, bigReply, { armFrameCipherAfter: keys.b });
+            });
+            const reply = await emit(client, "hs", {});
+            expect(reply.length).toBe(bigReply.length);
+            expect(rPeer.sent.length).toBeGreaterThan(1);
+            for (const frame of rPeer.sent)
+                expect(frame[0]).not.toBe(frame_cipher_1.FRAME_ENC);
+            expect(server.frameCipherArmed).toBe(true);
+            iPeer.destroy();
+            rPeer.destroy();
+        });
+    });
     describe("stats tracking", () => {
         it("should track bytes sent and received", async () => {
             const { iPeer, rPeer } = await getMockPeerPair();

package/dist/device/connection.d.ts

@@ -4,38 +4,71 @@ import type { Device } from "./device";
 import { type ISocket, TrustLevel } from "./socket.type";
 /** Resolves the trust assigned to an authenticated remote device identity. */
 export type GetTrustLevel = (deviceInfo: IDeviceInfo, registerNew?: boolean) => Promise<TrustLevel>;
-/** 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.
+ */
 export declare class Connection {
     readonly localDevice: Device;
     readonly localDeviceServerAddresses?: string[] | undefined;
     protected readonly getTrustLevel: GetTrustLevel;
     private _verified;
     private _remoteDeviceInfo;
+    /**
+     * @deprecated Legacy transport classification, only consulted when the frame
+     * cipher is not armed. Removed once legacy peers are no longer supported.
+     */
     secureLocal: boolean;
+    /** @deprecated See {@link Connection.secureLocal}. */
     secureRemote: boolean;
+    /**
+     * 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?: "encrypt-traffic-regardless-of-protocol" | "dont-encrypt-traffic-after-handshake";
+    /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel: TrustLevel;
+    /** Server-side hook fired shortly after a successful handshake. */
     onHandshakeComplete: ((deviceInfo: IDeviceInfo) => void) | undefined;
+    /** RPC timeout for {@link Connection.emit}. */
     timeoutMs: number;
+    /** Preferred chunk size for callers streaming raw bytes over this connection. */
     maxChunkSize: number;
+    /** Maximum accepted clock skew between the two devices' handshake timestamps. */
     handshakeTimestampToleranceMs: number;
     private _connectionAddress;
+    /** Normalized server address this connection was established against. */
     get connectionAddress(): string | undefined;
+    /** Underlying transport socket. */
     readonly socket: ISocket;
+    private pendingClientHandshake;
+    /** Server side: keys to arm for sending right after the handshake response frame. */
+    private pendingSendArm;
     constructor(socket: ISocket, localDevice: Device, localDeviceServerAddresses?: string[] | undefined, getTrustLevel?: GetTrustLevel);
+    /** True once the remote identity has been authenticated by the handshake. */
     get verified(): boolean;
+    /** True when every frame on this connection is sealed by the frame cipher. */
+    get frameCipherArmed(): boolean;
     /**
-     * Determines whether to apply application-level encryption (sign + box).
+     * Whether to apply the legacy per-message envelope (sign + box) to RPC payloads.
      *
-     * 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
-     *
-     * 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(): boolean;
+    /** Copy of the authenticated remote device identity (empty before the handshake). */
     get remoteDeviceInfo(): {
         publicKey: string;
         publicBoxKey: string;
@@ -44,7 +77,11 @@ export declare class Connection {
         userName?: string | undefined;
         deviceName?: string | undefined;
     };
+    /** Socket ID shared by both ends; also the frame-cipher AAD and HKDF salt. */
     get connectionId(): string;
+    private get supportsFrameCrypto();
+    private warnLegacyPeer;
+    private readonly handleCompleteHandshakeRPC;
     /**
      * Get connection throughput stats with calculated rates.
      * Returns bytes/messages sent/received and both average and recent rates.
@@ -63,18 +100,51 @@ export declare class Connection {
         sendRateMBps: number;
         receiveRateMBps: number;
     } | null;
+    /** Registers `fn` as an RPC handler under `name` (defaults to `fn.name`). */
     exposeRPC<T extends Function>(name: string, fn: T): void;
     exposeRPC<T extends Function>(fn: T): void;
+    /** Calls a remote RPC handler and resolves with its result (rejects on error or timeout). */
     emit<T = any>(eventName: string, ...args: any): Promise<T>;
+    /**
+     * 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: string, handler: Function): void;
+    /** Removes RPC handlers for `eventName`, or all handlers when omitted. */
     removeAllListeners(eventName?: string): void;
+    /**
+     * 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(): void;
+    /**
+     * 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: string, remoteDeviceInfo?: IDeviceInfo): IDataBox;
+    /**
+     * 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}).
+     */
     completeHandshake(boxedHandshake: IDataBox): Promise<IDeviceHandshake>;
+    /**
+     * 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.
+     */
     doHandshake(remoteAddress: string): Promise<IDeviceHandshake>;
     private closeLocal;
+    /** Round-trip time in milliseconds. @throws if the connection is not verified */
     ping(): Promise<number>;
     private closed;
+    /** Notifies the peer (best effort, 100 ms) then tears down the local side. */
     close(): Promise<void>;
 }
 /** Normalizes a peer address for transport and security comparisons. */