@peers-app/peers-sdk 0.25.6 → 0.25.7

package/dist/data/devices.d.ts

@@ -61,6 +61,28 @@ export declare const deviceInfoSchema: z.ZodObject<{
 }>;
 /** Signed identity and optional presentation hints advertised by a device. */
 export type IDeviceInfo = z.infer<typeof deviceInfoSchema>;
+/**
+ * Frame-cipher capability advertised inside a signed handshake.
+ *
+ * Present when the sender can arm the per-connection frame cipher
+ * (`peers-sdk/src/device/frame-cipher.ts`). Because it travels inside the
+ * signed and boxed handshake, an on-path attacker cannot strip it without
+ * breaking the signature; a missing field means a genuinely legacy peer.
+ */
+export declare const handshakeFrameCryptoSchema: z.ZodObject<{
+    /** Key-derivation and wire-format version. Only `1` exists. */
+    version: z.ZodLiteral<1>;
+    /** Ephemeral X25519 public key for this connection, base64url. */
+    ephemeralBoxKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    ephemeralBoxKey: string;
+}, {
+    version: 1;
+    ephemeralBoxKey: string;
+}>;
+/** Frame-cipher capability block carried in a handshake. */
+export type IHandshakeFrameCrypto = z.infer<typeof handshakeFrameCryptoSchema>;
 /** Schema for connection-bound device handshake contents. */
 export declare const deviceHandshakeSchema: z.ZodObject<{
     userId: z.ZodEffects<z.ZodString, string, string>;
@@ -73,26 +95,46 @@ export declare const deviceHandshakeSchema: z.ZodObject<{
     connectionId: z.ZodString;
     serverAddress: z.ZodString;
     timestamp: z.ZodNumber;
+    frameCrypto: z.ZodOptional<z.ZodObject<{
+        /** Key-derivation and wire-format version. Only `1` exists. */
+        version: z.ZodLiteral<1>;
+        /** Ephemeral X25519 public key for this connection, base64url. */
+        ephemeralBoxKey: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        version: 1;
+        ephemeralBoxKey: string;
+    }, {
+        version: 1;
+        ephemeralBoxKey: string;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     timestamp: number;
     publicKey: string;
     publicBoxKey: string;
     userId: string;
-    deviceId: string;
     connectionId: string;
+    deviceId: string;
     serverAddress: string;
     userName?: string | undefined;
     deviceName?: string | undefined;
+    frameCrypto?: {
+        version: 1;
+        ephemeralBoxKey: string;
+    } | undefined;
 }, {
     timestamp: number;
     publicKey: string;
     publicBoxKey: string;
     userId: string;
-    deviceId: string;
     connectionId: string;
+    deviceId: string;
     serverAddress: string;
     userName?: string | undefined;
     deviceName?: string | undefined;
+    frameCrypto?: {
+        version: 1;
+        ephemeralBoxKey: string;
+    } | undefined;
 }>;
 /** Signed device information bound to one connection handshake. */
 export type IDeviceHandshake = z.infer<typeof deviceHandshakeSchema>;

package/dist/data/devices.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.thisDeviceId = exports.trustedServers = exports.deviceHandshakeSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
+exports.thisDeviceId = exports.trustedServers = exports.deviceHandshakeSchema = exports.handshakeFrameCryptoSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
 exports.Devices = Devices;
 const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
@@ -33,11 +33,26 @@ exports.deviceInfoSchema = zod_1.z.object({
     userName: exports.displayNameSchema.optional(),
     deviceName: exports.displayNameSchema.optional(),
 });
+/**
+ * Frame-cipher capability advertised inside a signed handshake.
+ *
+ * Present when the sender can arm the per-connection frame cipher
+ * (`peers-sdk/src/device/frame-cipher.ts`). Because it travels inside the
+ * signed and boxed handshake, an on-path attacker cannot strip it without
+ * breaking the signature; a missing field means a genuinely legacy peer.
+ */
+exports.handshakeFrameCryptoSchema = zod_1.z.object({
+    /** Key-derivation and wire-format version. Only `1` exists. */
+    version: zod_1.z.literal(1),
+    /** Ephemeral X25519 public key for this connection, base64url. */
+    ephemeralBoxKey: zod_1.z.string(),
+});
 /** Schema for connection-bound device handshake contents. */
 exports.deviceHandshakeSchema = exports.deviceInfoSchema.extend({
     connectionId: zod_1.z.string(),
     serverAddress: zod_1.z.string(),
     timestamp: zod_1.z.number(),
+    frameCrypto: exports.handshakeFrameCryptoSchema.optional(),
 });
 const metaData = {
     name: "Devices",

package/dist/device/binary-peer-connection-v2.d.ts

@@ -14,6 +14,11 @@
  *
  * Both modes share a single sendFrame() function that handles backpressure
  * and event-loop yielding (critical for Go sidecar WebRTC pipeline).
+ *
+ * 3. **Frame cipher**: once `armFrameCipher` is called (by `Connection` after
+ *    the handshake), every outbound frame is sealed as `FRAME_ENC` and every
+ *    inbound frame must be sealed. See `frame-cipher.ts` and
+ *    `working/transport-security.md`.
  */
 import { Connection } from "./connection";
 import type { Device } from "./device";
@@ -58,7 +63,9 @@ export interface WrapBinaryPeerOptions {
     protocol: "wrtc" | "ws";
     /**
      * Mark the transport as already secure (encrypted at transport layer).
-     * When true, sets secureLocal and secureRemote to skip application-level encryption.
+     * When true, sets secureLocal and secureRemote to skip the legacy per-message
+     * envelope against a legacy peer. Irrelevant once the frame cipher is armed.
+     * @deprecated Removed with the legacy path.
      */
     markTransportSecure?: boolean;
     /** Optional hard limits for untrusted inbound messages. */
@@ -76,7 +83,9 @@ export declare function createBinaryPeerSocket(connectionId: string, peer: IBina
 export declare function wrapBinaryPeer(connectionId: string, peer: IBinaryPeer, localDevice: Device, initiator: boolean, options: WrapBinaryPeerOptions, getTrustLevel?: ITrustLevelFn): Connection;
 /**
  * Wraps a WebRTC peer into a Connection.
- * WebRTC is encrypted at the transport layer (DTLS-SRTP).
+ * WebRTC is encrypted at the transport layer (DTLS-SRTP); the frame cipher is
+ * armed on top of it by the handshake so no code path depends on transport
+ * classification.
  */
 export declare function wrapWrtc(connectionId: string, peer: IWebRTCPeer, localDevice: Device, initiator: boolean, getTrustLevel?: ITrustLevelFn, receiveLimits?: Partial<BinaryPeerReceiveLimits>): Connection;
 export {};

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

@@ -15,6 +15,11 @@
  *
  * Both modes share a single sendFrame() function that handles backpressure
  * and event-loop yielding (critical for Go sidecar WebRTC pipeline).
+ *
+ * 3. **Frame cipher**: once `armFrameCipher` is called (by `Connection` after
+ *    the handshake), every outbound frame is sealed as `FRAME_ENC` and every
+ *    inbound frame must be sealed. See `frame-cipher.ts` and
+ *    `working/transport-security.md`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BINARY_PEER_RECEIVE_LIMITS = void 0;
@@ -24,6 +29,7 @@ exports.wrapWrtc = wrapWrtc;
 const msgpack_1 = require("@msgpack/msgpack");
 const utils_1 = require("../utils");
 const connection_1 = require("./connection");
+const frame_cipher_1 = require("./frame-cipher");
 const get_trust_level_fn_1 = require("./get-trust-level-fn");
 const socket_type_1 = require("./socket.type");
 const tx_encoding_1 = require("./tx-encoding");
@@ -253,6 +259,71 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
             throw new Error(`Invalid binary peer receive limit ${name}: ${value}`);
         }
     }
+    // ─── Frame Cipher ────────────────────────────────────────────────
+    // Sealing happens at peer.send() time, so a frame that was built before the
+    // cipher was armed but is still waiting on backpressure goes out sealed.
+    let sendSealer = null;
+    let receiveOpener = null;
+    // Bare sockets (no Connection) deliver plaintext streams; Connection turns
+    // this off and re-enables it only for a verified legacy peer.
+    let plaintextStreamsAllowed = true;
+    // Every inner frame must leave room for the cipher's 17 bytes so a sealed
+    // frame never exceeds the transport limit (64 KB SCTP on WebRTC). Reserved
+    // unconditionally: 17 bytes per frame is nothing and it removes any race
+    // between chunk sizing and arming.
+    const maxInnerFrame = config.maxFramePayload - frame_cipher_1.FRAME_CIPHER_OVERHEAD;
+    /** True once a send cipher has been installed, so a later send cannot fall back to plaintext. */
+    let sendCipherWasArmed = false;
+    let cipherReleaseTimer;
+    function armSend(sendKey) {
+        sendCipherWasArmed = true;
+        sendSealer?.destroy();
+        sendSealer = new frame_cipher_1.FrameSealer(sendKey, connectionId);
+    }
+    function armReceive(receiveKey) {
+        receiveOpener?.destroy();
+        receiveOpener = new frame_cipher_1.FrameOpener(receiveKey, connectionId);
+    }
+    function armFrameCipher(keys, direction = "both") {
+        if (isClosed)
+            return;
+        if (direction !== "send")
+            armReceive(keys.receiveKey);
+        if (direction !== "receive")
+            armSend(keys.sendKey);
+    }
+    function destroyFrameCipher() {
+        if (cipherReleaseTimer) {
+            clearImmediate(cipherReleaseTimer);
+            cipherReleaseTimer = undefined;
+        }
+        sendSealer?.destroy();
+        receiveOpener?.destroy();
+        sendSealer = null;
+        receiveOpener = null;
+    }
+    /**
+     * Drop the cipher on a later turn. A close may happen while an inbound RPC
+     * handler is awaiting an already-resolved promise; releasing on `setImmediate`
+     * lets that handler's reply seal. Sending the reply in the clear after the
+     * peer had armed is a protocol violation that closes the other side.
+     */
+    function releaseCipherAfterTurn() {
+        if (cipherReleaseTimer)
+            return;
+        const sealer = sendSealer;
+        const opener = receiveOpener;
+        cipherReleaseTimer = setImmediate(() => {
+            cipherReleaseTimer = undefined;
+            if (sendSealer === sealer)
+                sendSealer = null;
+            if (receiveOpener === opener)
+                receiveOpener = null;
+            sealer?.destroy();
+            opener?.destroy();
+        });
+        cipherReleaseTimer.unref?.();
+    }
     // ─── Drain / Backpressure ────────────────────────────────────────
     // Single persistent drain handler to avoid leaking listeners
     let drainResolve = null;
@@ -266,8 +337,13 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     /**
      * Send a single frame through the underlying transport with backpressure
      * and event-loop yielding. This is the ONLY function that calls peer.send().
+     *
+     * `frame` is an inner frame (type byte first). It is sealed here if the send
+     * cipher is armed. `sendOptions.armFrameCipherAfter` arms the send cipher
+     * synchronously after this frame has been handed to the transport, so the
+     * handshake response goes out in the clear and everything after it sealed.
      */
-    async function sendFrame(frame) {
+    async function sendFrame(frame, sendOptions) {
         // Backpressure: wait for buffer to drain before sending more
         while ((peer.getBufferedAmount?.() ?? 0) > config.highWaterMark) {
             await new Promise((resolve) => {
@@ -282,9 +358,17 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
                 }, 5);
             });
         }
-        stats.bytesSent += frame.length;
+        // A retired cipher must not fall back to a clear frame; the peer would close
+        // on it. Drop the send instead.
+        if (!sendSealer && sendCipherWasArmed)
+            return;
+        const wire = sendSealer ? sendSealer.seal(frame) : frame;
+        stats.bytesSent += wire.length;
         stats.messagesSent++;
-        peer.send(frame);
+        peer.send(wire);
+        if (sendOptions?.armFrameCipherAfter) {
+            armSend(sendOptions.armFrameCipherAfter.sendKey);
+        }
         // Yield to event loop so the receiving side can process I/O.
         // CRITICAL for Go sidecar pipeline: without this, Node.js sends chunks
         // in a microtask chain that starves the Unix socket I/O, deadlocking
@@ -300,29 +384,31 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     /**
      * Send an encoded RPC message. Small messages go as single frames.
      * Large messages are chunked through the queue to prevent interleaving.
+     * `sendOptions` apply to the last frame of the message.
      */
-    function sendRPC(encoded) {
+    function sendRPC(encoded, sendOptions) {
         // RPC_COMPLETE header overhead is 1 byte
-        if (encoded.length + 1 <= config.maxFramePayload) {
+        if (encoded.length + 1 <= maxInnerFrame) {
             // Small message: send directly as single frame (no queue needed)
-            return sendFrame(buildRPCComplete(encoded));
+            return sendFrame(buildRPCComplete(encoded), sendOptions);
         }
         // Large message: needs chunking. Serialize through queue.
         const sendChunked = async () => {
             const msgId = nextMsgId++;
             // RPC_START header: 1 (type) + 4 (msgId) + 4 (totalSize) = 9 bytes
             const startHeaderSize = 9;
-            const firstChunkDataSize = config.maxFramePayload - startHeaderSize;
+            const firstChunkDataSize = maxInnerFrame - startHeaderSize;
             const firstChunkData = encoded.subarray(0, firstChunkDataSize);
             await sendFrame(buildRPCStart(msgId, encoded.length, firstChunkData));
             // RPC_CONT header: 1 (type) + 4 (msgId) = 5 bytes
             const contHeaderSize = 5;
-            const contChunkDataSize = config.maxFramePayload - contHeaderSize;
+            const contChunkDataSize = maxInnerFrame - contHeaderSize;
             let offset = firstChunkDataSize;
             while (offset < encoded.length) {
                 const end = Math.min(offset + contChunkDataSize, encoded.length);
                 const chunkData = encoded.subarray(offset, end);
-                await sendFrame(buildRPCCont(msgId, chunkData));
+                const isLast = end === encoded.length;
+                await sendFrame(buildRPCCont(msgId, chunkData), isLast ? sendOptions : undefined);
                 offset = end;
             }
         };
@@ -353,6 +439,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         console.warn(`Closing ${protocol} peer after binary protocol violation: ${reason}`);
         isClosed = true;
         clearAllReassemblies();
+        destroyFrameCipher();
         socket.connected = false;
         peer.destroy();
     }
@@ -406,7 +493,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
                 return;
             }
             try {
-                const callback = (err, result) => {
+                const callback = (err, result, sendOptions) => {
                     const responseMessage = {
                         type: "callback",
                         callbackId: message.callbackId,
@@ -416,7 +503,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
                     else
                         responseMessage.result = result;
                     const encoded = encodeMessage(responseMessage);
-                    sendRPC(encoded);
+                    sendRPC(encoded, sendOptions);
                 };
                 handler(message.args, callback);
             }
@@ -439,18 +526,18 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         const sidBytes = getStreamIdBytes(streamId);
         // STREAM_COMPLETE header: 1 (type) + 1 (sidLen) + sidBytes.length
         const headerSize = 1 + 1 + sidBytes.length;
-        if (data.length + headerSize <= config.maxFramePayload) {
+        if (data.length + headerSize <= maxInnerFrame) {
             // Single frame
             await sendFrame(buildStreamComplete(sidBytes, data));
         }
         else {
             // Chunked: STREAM_START has +4 bytes for totalSize
             const startHeaderSize = headerSize + 4;
-            const firstDataSize = config.maxFramePayload - startHeaderSize;
+            const firstDataSize = maxInnerFrame - startHeaderSize;
             const firstChunkData = data.subarray(0, firstDataSize);
             await sendFrame(buildStreamStart(sidBytes, data.length, firstChunkData));
             // STREAM_CONT has same header as STREAM_COMPLETE (no totalSize)
-            const contDataSize = config.maxFramePayload - headerSize;
+            const contDataSize = maxInnerFrame - headerSize;
             let offset = firstDataSize;
             while (offset < data.length) {
                 const end = Math.min(offset + contDataSize, data.length);
@@ -463,12 +550,46 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     // ─── Incoming Frame Router ───────────────────────────────────────
     peer.on("data", (data) => {
         try {
-            const bytes = new Uint8Array(data);
+            if (isClosed)
+                return;
+            let bytes = new Uint8Array(data);
             stats.bytesReceived += bytes.length;
             stats.messagesReceived++;
             if (bytes.length === 0)
                 return;
+            // ── Frame cipher gate ───────────────────────────────────────
+            // Once the receive cipher is armed every frame must be sealed; before
+            // that no frame may be. Either violation closes the connection so a
+            // peer can neither slip plaintext in after the switch nor pre-empt
+            // the handshake with ciphertext.
+            if (receiveOpener) {
+                if (bytes[0] !== frame_cipher_1.FRAME_ENC) {
+                    closeForProtocolViolation("plaintext frame received after frame cipher was armed");
+                    return;
+                }
+                const inner = receiveOpener.open(bytes);
+                if (!inner) {
+                    closeForProtocolViolation("sealed frame failed authentication");
+                    return;
+                }
+                bytes = inner;
+                if (bytes.length === 0)
+                    return;
+            }
+            else if (bytes[0] === frame_cipher_1.FRAME_ENC) {
+                closeForProtocolViolation("sealed frame received before frame cipher was armed");
+                return;
+            }
             const frameType = bytes[0];
+            // Stream frames bypass Connection's verification gate, so the socket
+            // enforces it: deliver only when sealed (handshake done) or when the
+            // owner explicitly allows plaintext streams.
+            if (frameType >= STREAM_COMPLETE &&
+                frameType <= STREAM_CONT &&
+                !receiveOpener &&
+                !plaintextStreamsAllowed) {
+                return;
+            }
             switch (frameType) {
                 // ── RPC frames ──────────────────────────────────────────
                 case RPC_COMPLETE: {
@@ -627,13 +748,15 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
             console.error(`Error parsing ${protocol} frame:`, err);
         }
     });
-    // Handle closure
+    // Handle closure. Cipher teardown waits until queued RPC replies have sealed;
+    // see {@link releaseCipherAfterTurn}.
     peer.on("close", () => {
         if (isClosed)
             return;
         isClosed = true;
-        clearAllReassemblies();
         socket.connected = false;
+        clearAllReassemblies();
+        releaseCipherAfterTurn();
     });
     // ─── ISocket Implementation ──────────────────────────────────────
     const socket = {
@@ -642,6 +765,13 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         handlesOwnEncoding: true,
         transportType,
         stats,
+        armFrameCipher,
+        get frameCipherArmed() {
+            return sendSealer !== null && receiveOpener !== null;
+        },
+        setPlaintextStreamsAllowed(allowed) {
+            plaintextStreamsAllowed = allowed;
+        },
         emit(eventName, args, callback) {
             const callbackId = (0, utils_1.newid)();
             callbacks[callbackId] = callback;
@@ -697,7 +827,9 @@ function wrapBinaryPeer(connectionId, peer, localDevice, initiator, options, get
 }
 /**
  * Wraps a WebRTC peer into a Connection.
- * WebRTC is encrypted at the transport layer (DTLS-SRTP).
+ * WebRTC is encrypted at the transport layer (DTLS-SRTP); the frame cipher is
+ * armed on top of it by the handshake so no code path depends on transport
+ * classification.
  */
 function wrapWrtc(connectionId, peer, localDevice, initiator, getTrustLevel, receiveLimits) {
     return wrapBinaryPeer(connectionId, peer, localDevice, initiator, { protocol: "wrtc", markTransportSecure: true, receiveLimits }, getTrustLevel);