@peers-app/peers-sdk 0.25.6 → 0.25.8

package/dist/device/frame-cipher.test.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const nacl = require("tweetnacl");
+const utils_1 = require("../utils");
+const frame_cipher_1 = require("./frame-cipher");
+function randomKey() {
+    return nacl.randomBytes(32);
+}
+function derivationParams() {
+    return {
+        ephemeralSharedSecret: nacl.randomBytes(32),
+        staticSharedSecret: nacl.randomBytes(32),
+        connectionId: (0, utils_1.newid)(),
+        clientDeviceId: (0, utils_1.newid)(),
+        serverDeviceId: (0, utils_1.newid)(),
+        timestamp: Date.now(),
+    };
+}
+function innerFrame(type, payload) {
+    const frame = new Uint8Array(1 + payload.length);
+    frame[0] = type;
+    frame.set(payload, 1);
+    return frame;
+}
+describe("frame-cipher", () => {
+    describe("seal / open", () => {
+        it("round-trips an inner frame with exactly FRAME_CIPHER_OVERHEAD bytes added", () => {
+            const key = randomKey();
+            const connectionId = (0, utils_1.newid)();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), connectionId);
+            const opener = new frame_cipher_1.FrameOpener(key.slice(), connectionId);
+            const inner = innerFrame(0x10, new Uint8Array([1, 2, 3, 4, 5]));
+            const sealed = sealer.seal(inner);
+            expect(sealed[0]).toBe(frame_cipher_1.FRAME_ENC);
+            expect(sealed.length).toBe(inner.length + frame_cipher_1.FRAME_CIPHER_OVERHEAD);
+            expect(Buffer.from(opener.open(sealed) ?? [])).toEqual(Buffer.from(inner));
+        });
+        it("round-trips an empty inner frame and a large inner frame", () => {
+            const key = randomKey();
+            const { sealer, opener } = (0, frame_cipher_1.createFrameCiphers)({ sendKey: key.slice(), receiveKey: key.slice() }, "conn");
+            const empty = new Uint8Array(0);
+            expect(opener.open(sealer.seal(empty))?.length).toBe(0);
+            const large = new Uint8Array(512 * 1024);
+            for (let i = 0; i < large.length; i++)
+                large[i] = i % 251;
+            const opened = opener.open(sealer.seal(large));
+            expect(opened).not.toBeNull();
+            expect(Buffer.from(opened)).toEqual(Buffer.from(large));
+        });
+        it("does not leak the inner frame bytes on the wire", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key, "conn");
+            const marker = Buffer.from("SECRET-MARKER-0123456789abcdef");
+            const sealed = Buffer.from(sealer.seal(innerFrame(0x00, marker)));
+            expect(sealed.indexOf(marker)).toBe(-1);
+        });
+        it("fails to open with the wrong key", () => {
+            const sealer = new frame_cipher_1.FrameSealer(randomKey(), "conn");
+            const opener = new frame_cipher_1.FrameOpener(randomKey(), "conn");
+            expect(opener.open(sealer.seal(innerFrame(0x00, new Uint8Array([9]))))).toBeNull();
+        });
+        it("fails to open with the wrong connectionId (AAD)", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), "conn-a");
+            const opener = new frame_cipher_1.FrameOpener(key.slice(), "conn-b");
+            expect(opener.open(sealer.seal(innerFrame(0x00, new Uint8Array([9]))))).toBeNull();
+        });
+        it("fails to open a frame sealed for the other direction", () => {
+            const derived = (0, frame_cipher_1.deriveFrameKeys)(derivationParams());
+            const client = (0, frame_cipher_1.createFrameCiphers)((0, frame_cipher_1.frameKeysForRole)(derived, "client"), "conn");
+            const server = (0, frame_cipher_1.createFrameCiphers)((0, frame_cipher_1.frameKeysForRole)(derived, "server"), "conn");
+            const sealed = client.sealer.seal(innerFrame(0x00, new Uint8Array([1])));
+            // The client's own opener holds the server-to-client key: wrong direction.
+            expect(client.opener.open(sealed)).toBeNull();
+            // The server's opener holds the client-to-server key and is at counter 0.
+            expect(server.opener.open(sealed)).not.toBeNull();
+        });
+        it("fails to open when a ciphertext bit is flipped", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), "conn");
+            const opener = new frame_cipher_1.FrameOpener(key.slice(), "conn");
+            const sealed = sealer.seal(innerFrame(0x00, new Uint8Array([1, 2, 3])));
+            sealed[2] ^= 0x01;
+            expect(opener.open(sealed)).toBeNull();
+        });
+        it("fails to open when the tag is truncated or the type byte is wrong", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), "conn");
+            const sealed = sealer.seal(innerFrame(0x00, new Uint8Array([1, 2, 3])));
+            expect(new frame_cipher_1.FrameOpener(key.slice(), "conn").open(sealed.subarray(0, sealed.length - 1))).toBeNull();
+            expect(new frame_cipher_1.FrameOpener(key.slice(), "conn").open(new Uint8Array([frame_cipher_1.FRAME_ENC]))).toBeNull();
+            const wrongType = sealed.slice();
+            wrongType[0] = 0x00;
+            expect(new frame_cipher_1.FrameOpener(key.slice(), "conn").open(wrongType)).toBeNull();
+        });
+        it("fails to open a replayed frame because the receive counter has advanced", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), "conn");
+            const opener = new frame_cipher_1.FrameOpener(key.slice(), "conn");
+            const sealed = sealer.seal(innerFrame(0x00, new Uint8Array([7])));
+            expect(opener.open(sealed)).not.toBeNull();
+            expect(opener.open(sealed)).toBeNull();
+        });
+        it("fails to open frames delivered out of order", () => {
+            const key = randomKey();
+            const sealer = new frame_cipher_1.FrameSealer(key.slice(), "conn");
+            const opener = new frame_cipher_1.FrameOpener(key.slice(), "conn");
+            sealer.seal(innerFrame(0x00, new Uint8Array([1]))); // frame 0, never delivered
+            const second = sealer.seal(innerFrame(0x00, new Uint8Array([2])));
+            expect(opener.open(second)).toBeNull();
+        });
+        it("advances counters independently per direction", () => {
+            const derived = (0, frame_cipher_1.deriveFrameKeys)(derivationParams());
+            const client = (0, frame_cipher_1.createFrameCiphers)((0, frame_cipher_1.frameKeysForRole)(derived, "client"), "conn");
+            const server = (0, frame_cipher_1.createFrameCiphers)((0, frame_cipher_1.frameKeysForRole)(derived, "server"), "conn");
+            for (let i = 0; i < 5; i++) {
+                const opened = server.opener.open(client.sealer.seal(innerFrame(0x00, new Uint8Array([i]))));
+                expect(opened?.[1]).toBe(i);
+            }
+            expect(client.sealer.count).toBe(5);
+            expect(server.opener.count).toBe(5);
+            expect(server.sealer.count).toBe(0);
+            expect(client.opener.count).toBe(0);
+            const back = client.opener.open(server.sealer.seal(innerFrame(0x00, new Uint8Array([42]))));
+            expect(back?.[1]).toBe(42);
+            expect(server.sealer.count).toBe(1);
+            expect(client.opener.count).toBe(1);
+        });
+        it("produces different ciphertext for identical plaintext on consecutive frames", () => {
+            const sealer = new frame_cipher_1.FrameSealer(randomKey(), "conn");
+            const inner = innerFrame(0x00, new Uint8Array([1, 2, 3, 4]));
+            const a = Buffer.from(sealer.seal(inner));
+            const b = Buffer.from(sealer.seal(inner));
+            expect(a.equals(b)).toBe(false);
+        });
+        it("rejects keys of the wrong length", () => {
+            expect(() => new frame_cipher_1.FrameSealer(new Uint8Array(16), "conn")).toThrow(/32 bytes/);
+            expect(() => new frame_cipher_1.FrameOpener(new Uint8Array(31), "conn")).toThrow(/32 bytes/);
+        });
+    });
+    describe("deriveFrameKeys", () => {
+        it("is symmetric: both peers derive identical directional keys", () => {
+            const params = derivationParams();
+            const a = (0, frame_cipher_1.deriveFrameKeys)({ ...params });
+            const b = (0, frame_cipher_1.deriveFrameKeys)({ ...params });
+            expect(Buffer.from(a.clientToServer)).toEqual(Buffer.from(b.clientToServer));
+            expect(Buffer.from(a.serverToClient)).toEqual(Buffer.from(b.serverToClient));
+            expect(Buffer.from(a.clientToServer).equals(Buffer.from(a.serverToClient))).toBe(false);
+        });
+        it("maps roles onto directions so client.send == server.receive", () => {
+            const derived = (0, frame_cipher_1.deriveFrameKeys)(derivationParams());
+            const client = (0, frame_cipher_1.frameKeysForRole)(derived, "client");
+            const server = (0, frame_cipher_1.frameKeysForRole)(derived, "server");
+            expect(Buffer.from(client.sendKey)).toEqual(Buffer.from(server.receiveKey));
+            expect(Buffer.from(client.receiveKey)).toEqual(Buffer.from(server.sendKey));
+        });
+        it("changes with every input", () => {
+            const base = derivationParams();
+            const reference = (0, frame_cipher_1.deriveFrameKeys)(base);
+            const variants = [
+                { ephemeralSharedSecret: nacl.randomBytes(32) },
+                { staticSharedSecret: nacl.randomBytes(32) },
+                { connectionId: (0, utils_1.newid)() },
+                { clientDeviceId: (0, utils_1.newid)() },
+                { serverDeviceId: (0, utils_1.newid)() },
+                { timestamp: base.timestamp + 1 },
+            ];
+            for (const variant of variants) {
+                const derived = (0, frame_cipher_1.deriveFrameKeys)({ ...base, ...variant });
+                expect(Buffer.from(derived.clientToServer).equals(Buffer.from(reference.clientToServer))).toBe(false);
+                expect(Buffer.from(derived.serverToClient).equals(Buffer.from(reference.serverToClient))).toBe(false);
+            }
+        });
+        it("distinguishes swapped device IDs", () => {
+            const base = derivationParams();
+            const a = (0, frame_cipher_1.deriveFrameKeys)(base);
+            const b = (0, frame_cipher_1.deriveFrameKeys)({
+                ...base,
+                clientDeviceId: base.serverDeviceId,
+                serverDeviceId: base.clientDeviceId,
+            });
+            expect(Buffer.from(a.clientToServer).equals(Buffer.from(b.clientToServer))).toBe(false);
+        });
+        it("rejects malformed inputs", () => {
+            const base = derivationParams();
+            expect(() => (0, frame_cipher_1.deriveFrameKeys)({ ...base, ephemeralSharedSecret: new Uint8Array(31) })).toThrow(/32-byte/);
+            expect(() => (0, frame_cipher_1.deriveFrameKeys)({ ...base, connectionId: "" })).toThrow(/connectionId/);
+            expect(() => (0, frame_cipher_1.deriveFrameKeys)({ ...base, timestamp: -1 })).toThrow(/timestamp/);
+            expect(() => (0, frame_cipher_1.deriveFrameKeys)({ ...base, timestamp: 1.5 })).toThrow(/timestamp/);
+        });
+        it("works end to end with real X25519 shared secrets", () => {
+            const clientEph = nacl.box.keyPair();
+            const serverEph = nacl.box.keyPair();
+            const clientStatic = nacl.box.keyPair();
+            const serverStatic = nacl.box.keyPair();
+            const common = {
+                connectionId: (0, utils_1.newid)(),
+                clientDeviceId: (0, utils_1.newid)(),
+                serverDeviceId: (0, utils_1.newid)(),
+                timestamp: Date.now(),
+            };
+            const clientKeys = (0, frame_cipher_1.frameKeysForRole)((0, frame_cipher_1.deriveFrameKeys)({
+                ...common,
+                ephemeralSharedSecret: nacl.scalarMult(clientEph.secretKey, serverEph.publicKey),
+                staticSharedSecret: nacl.scalarMult(clientStatic.secretKey, serverStatic.publicKey),
+            }), "client");
+            const serverKeys = (0, frame_cipher_1.frameKeysForRole)((0, frame_cipher_1.deriveFrameKeys)({
+                ...common,
+                ephemeralSharedSecret: nacl.scalarMult(serverEph.secretKey, clientEph.publicKey),
+                staticSharedSecret: nacl.scalarMult(serverStatic.secretKey, clientStatic.publicKey),
+            }), "server");
+            const client = (0, frame_cipher_1.createFrameCiphers)(clientKeys, common.connectionId);
+            const server = (0, frame_cipher_1.createFrameCiphers)(serverKeys, common.connectionId);
+            const inner = innerFrame(0x11, Buffer.from("hello over x25519"));
+            expect(Buffer.from(server.opener.open(client.sealer.seal(inner)) ?? [])).toEqual(Buffer.from(inner));
+            expect(Buffer.from(client.opener.open(server.sealer.seal(inner)) ?? [])).toEqual(Buffer.from(inner));
+        });
+    });
+});

package/dist/device/socket.type.d.ts

@@ -1,5 +1,23 @@
+import type { FrameKeys } from "./frame-cipher";
+/** Default chunk size for raw byte streaming. */
 export declare const DEFAULT_MAX_CHUNK_SIZE: number;
-export type RPCCallback = (error?: any, result?: any) => void;
+/**
+ * Transport instructions attached to one RPC reply.
+ *
+ * Only `Connection`'s handshake handler uses this: the server must send its
+ * handshake response in the clear (the client cannot open a sealed frame until
+ * it has the server's ephemeral key, which is in that response) and seal
+ * everything after it. Threading the keys through the reply callback lets the
+ * socket arm the send cipher synchronously after that exact frame.
+ */
+export interface RPCSendOptions {
+    /** Arm the outbound frame cipher with these keys right after this reply frame has been sent. */
+    armFrameCipherAfter?: FrameKeys;
+}
+/** Reply callback handed to RPC handlers. */
+export type RPCCallback = (error?: any, result?: any, sendOptions?: RPCSendOptions) => void;
+/** Which direction(s) of the frame cipher to arm. */
+export type FrameCipherDirection = "both" | "send" | "receive";
 /**
  * Lightweight stats tracking for socket throughput.
  * Tracks bytes and messages sent/received with minimal overhead.
@@ -16,7 +34,9 @@ export interface ISocketStats {
 }
 /** Creates a new stats object for tracking socket throughput */
 export declare function createSocketStats(): ISocketStats;
+/** Underlying transport family of a socket. */
 export type TransportType = "ws" | "wrtc" | "unknown";
+/** Minimal RPC + raw-byte transport abstraction consumed by `Connection`. */
 export interface ISocket {
     id?: string;
     connected?: boolean;
@@ -59,7 +79,28 @@ export interface ISocket {
      * @param streamId - Stream identifier to stop listening on
      */
     removeRawBytesHandler?(streamId: string): void;
+    /**
+     * Arms the per-connection frame cipher (see `frame-cipher.ts`). Sockets that
+     * implement this seal every outbound frame and require every inbound frame to
+     * be sealed once the corresponding direction is armed. `Connection` only
+     * advertises `frameCrypto` support in its handshake when this is present.
+     * @param keys - This peer's send and receive keys
+     * @param direction - Defaults to `"both"`. The handshake server arms
+     *   `"receive"` first and lets the reply's {@link RPCSendOptions} arm send.
+     */
+    armFrameCipher?(keys: FrameKeys, direction?: FrameCipherDirection): void;
+    /** True once both directions of the frame cipher are armed. */
+    readonly frameCipherArmed?: boolean;
+    /**
+     * Controls delivery of inbound plaintext `STREAM_*` frames. Sockets start
+     * permissive so bare transports keep working; `Connection` turns this off on
+     * construction and only turns it back on for a verified legacy peer. Sealed
+     * stream frames are always delivered because arming implies a completed
+     * handshake.
+     */
+    setPlaintextStreamsAllowed?(allowed: boolean): void;
 }
+/** How much a remote device identity is trusted. Negative values are rejected. */
 export declare enum TrustLevel {
     Malicious = -20,
     Untrusted = -10,

package/dist/device/socket.type.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TrustLevel = exports.DEFAULT_MAX_CHUNK_SIZE = void 0;
 exports.createSocketStats = createSocketStats;
+/** Default chunk size for raw byte streaming. */
 exports.DEFAULT_MAX_CHUNK_SIZE = 1024 * 1024; // 1MB
 /** Creates a new stats object for tracking socket throughput */
 function createSocketStats() {
@@ -17,6 +18,7 @@ function createSocketStats() {
         lastSampleBytesReceived: 0,
     };
 }
+/** How much a remote device identity is trusted. Negative values are rejected. */
 var TrustLevel;
 (function (TrustLevel) {
     TrustLevel[TrustLevel["Malicious"] = -20] = "Malicious";

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./device/binary-peer-connection-v2";
 export * from "./device/connection";
 export * from "./device/device";
 export * from "./device/device-election";
+export * from "./device/frame-cipher";
 export * from "./device/get-trust-level-fn";
 export * from "./device/socket.type";
 export * from "./device/socket-io-binary-peer";

package/dist/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./device/binary-peer-connection-v2"), exports);
 __exportStar(require("./device/connection"), exports);
 __exportStar(require("./device/device"), exports);
 __exportStar(require("./device/device-election"), exports);
+__exportStar(require("./device/frame-cipher"), exports);
 __exportStar(require("./device/get-trust-level-fn"), exports);
 __exportStar(require("./device/socket.type"), exports);
 __exportStar(require("./device/socket-io-binary-peer"), exports);

package/dist/keys.d.ts

@@ -82,6 +82,25 @@ export declare function openSignedObject<T>(signedObj: ISignedObject<T>): T;
  * @param toPublicBoxKey Recipient’s X25519 public key (base64url)
  */
 export declare function boxDataWithKeys(data: any, toPublicBoxKey: string, mySecretKey: string): IDataBox;
+/**
+ * Raw X25519 shared secret between the box key derived from `myEd25519SecretKey` and
+ * `theirPublicBoxKey`. Used as key-agreement input (feed it to a KDF, never use it directly).
+ * @param myEd25519SecretKey Ed25519 secret key in the encoding produced by {@link newKeys}
+ * @param theirPublicBoxKey Peer's X25519 public key (base64url)
+ * @returns 32-byte shared secret; the caller should zeroize it when done
+ */
+export declare function computeStaticSharedSecret(myEd25519SecretKey: string, theirPublicBoxKey: string): Uint8Array;
+/** Fresh X25519 keypair for one connection's frame-key agreement. Raw bytes, not base64. */
+export declare function newEphemeralBoxKeyPair(): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * Raw X25519 shared secret between a raw 32-byte secret key and a base64url public key.
+ * Used for the ephemeral half of frame-key agreement; feed the result to a KDF.
+ * @returns 32-byte shared secret; the caller should zeroize it when done
+ */
+export declare function computeEphemeralSharedSecret(mySecretKey: Uint8Array, theirPublicKey: string): Uint8Array;
 /** Narrowing guard: value looks like an {@link IDataBox} envelope. */
 export declare function isBoxedData(data: any): boolean;
 /**

package/dist/keys.js

@@ -16,6 +16,9 @@ exports.openMessageWithPublicKey = openMessageWithPublicKey;
 exports.signObjectWithSecretKey = signObjectWithSecretKey;
 exports.openSignedObject = openSignedObject;
 exports.boxDataWithKeys = boxDataWithKeys;
+exports.computeStaticSharedSecret = computeStaticSharedSecret;
+exports.newEphemeralBoxKeyPair = newEphemeralBoxKeyPair;
+exports.computeEphemeralSharedSecret = computeEphemeralSharedSecret;
 exports.isBoxedData = isBoxedData;
 exports.openBoxWithSecretKey = openBoxWithSecretKey;
 exports.encryptData = encryptData;
@@ -242,6 +245,31 @@ function boxDataWithKeys(data, toPublicBoxKey, mySecretKey) {
         fromPublicKey: encodeBase64(boxKeyPair.publicKey),
     };
 }
+/**
+ * Raw X25519 shared secret between the box key derived from `myEd25519SecretKey` and
+ * `theirPublicBoxKey`. Used as key-agreement input (feed it to a KDF, never use it directly).
+ * @param myEd25519SecretKey Ed25519 secret key in the encoding produced by {@link newKeys}
+ * @param theirPublicBoxKey Peer's X25519 public key (base64url)
+ * @returns 32-byte shared secret; the caller should zeroize it when done
+ */
+function computeStaticSharedSecret(myEd25519SecretKey, theirPublicBoxKey) {
+    const curveSecret = ed2curve.convertSecretKey(decodeBase64(myEd25519SecretKey));
+    const shared = nacl.scalarMult(curveSecret, decodeBase64(theirPublicBoxKey));
+    curveSecret.fill(0);
+    return shared;
+}
+/** Fresh X25519 keypair for one connection's frame-key agreement. Raw bytes, not base64. */
+function newEphemeralBoxKeyPair() {
+    return nacl.box.keyPair();
+}
+/**
+ * Raw X25519 shared secret between a raw 32-byte secret key and a base64url public key.
+ * Used for the ephemeral half of frame-key agreement; feed the result to a KDF.
+ * @returns 32-byte shared secret; the caller should zeroize it when done
+ */
+function computeEphemeralSharedSecret(mySecretKey, theirPublicKey) {
+    return nacl.scalarMult(mySecretKey, decodeBase64(theirPublicKey));
+}
 /** Narrowing guard: value looks like an {@link IDataBox} envelope. */
 function isBoxedData(data) {
     return (typeof data === "object" &&

package/dist/rpc-types.d.ts

@@ -41,6 +41,8 @@ export interface IConnectedDeviceSummary {
     connectionAddress?: string;
     trustLevel: number;
     verified: boolean;
+    /** True when every frame on the connection is sealed by the per-connection frame cipher. */
+    frameCipherArmed?: boolean;
 }
 /** Filters and bounds for one remote System Logs query. */
 export interface IRemoteLogsQueryInput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.25.6",
+  "version": "0.25.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.2",
+    "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
     "buffer": "^6.0.3",
     "ed2curve": "^0.3.0",