@sideband/secure-relay 0.2.1 → 0.2.3

package/dist/types.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Direction of message flow (used in nonce construction) */
+export const Direction = {
+    ClientToDaemon: 1,
+    DaemonToClient: 2,
+};
+/**
+ * SBRP error codes (string constants for SDK use).
+ *
+ * Wire codes use numeric values in Control frames (see frame.ts).
+ * These string constants provide type-safe SDK-level error handling.
+ */
+export const SbrpErrorCode = {
+    // Authentication (0x01xx) - Terminal
+    Unauthorized: "unauthorized",
+    Forbidden: "forbidden",
+    // Routing (0x02xx) - Varies
+    DaemonNotFound: "daemon_not_found",
+    DaemonOffline: "daemon_offline",
+    // Session (0x03xx) - Terminal
+    SessionNotFound: "session_not_found",
+    SessionExpired: "session_expired",
+    // Wire Format (0x04xx) - Terminal
+    MalformedFrame: "malformed_frame",
+    PayloadTooLarge: "payload_too_large",
+    InvalidFrameType: "invalid_frame_type",
+    InvalidSessionId: "invalid_session_id",
+    DisallowedSender: "disallowed_sender",
+    // Internal (0x06xx) - Terminal
+    InternalError: "internal_error",
+    // Rate Limiting (0x09xx) - Non-terminal
+    RateLimited: "rate_limited",
+    // Session State (0x10xx) - Non-terminal
+    SessionPaused: "session_paused",
+    SessionResumed: "session_resumed",
+    SessionEnded: "session_ended",
+    SessionPending: "session_pending",
+    // Endpoint-only (0xExxx) - Never on wire
+    IdentityKeyChanged: "identity_key_changed",
+    HandshakeFailed: "handshake_failed",
+    HandshakeTimeout: "handshake_timeout",
+    DecryptFailed: "decrypt_failed",
+    SequenceError: "sequence_error",
+};
+/** Signal codes for Signal frame (0x04) */
+export const SignalCode = {
+    Ready: 0x00,
+    Close: 0x01,
+};
+/** Reason codes for Signal frames (§13.4) */
+export const SignalReason = {
+    /** No specific reason (default for ready signal) */
+    None: 0x00,
+    /** Process restart, memory cleared */
+    StateLost: 0x01,
+    /** Graceful daemon shutdown */
+    Shutdown: 0x02,
+    /** Internal policy denial */
+    Policy: 0x03,
+    /** Internal daemon error */
+    Error: 0x04,
+};
+/** SBRP-specific error */
+export class SbrpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SbrpError";
+    }
+}
+/** Brand a string as DaemonId (no validation) */
+export function asDaemonId(value) {
+    return value;
+}
+/** Brand a string as ClientId (no validation) */
+export function asClientId(value) {
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AA4DtC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,cAAc,EAAE,CAAC;IACjB,cAAc,EAAE,CAAC;CACT,CAAC;AAIX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,qCAAqC;IACrC,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IAEtB,4BAA4B;IAC5B,cAAc,EAAE,kBAAkB;IAClC,aAAa,EAAE,gBAAgB;IAE/B,8BAA8B;IAC9B,eAAe,EAAE,mBAAmB;IACpC,cAAc,EAAE,iBAAiB;IAEjC,kCAAkC;IAClC,cAAc,EAAE,iBAAiB;IACjC,eAAe,EAAE,mBAAmB;IACpC,gBAAgB,EAAE,oBAAoB;IACtC,gBAAgB,EAAE,oBAAoB;IACtC,gBAAgB,EAAE,mBAAmB;IAErC,+BAA+B;IAC/B,aAAa,EAAE,gBAAgB;IAE/B,wCAAwC;IACxC,WAAW,EAAE,cAAc;IAE3B,wCAAwC;IACxC,aAAa,EAAE,gBAAgB;IAC/B,cAAc,EAAE,iBAAiB;IACjC,YAAY,EAAE,eAAe;IAC7B,cAAc,EAAE,iBAAiB;IAEjC,yCAAyC;IACzC,kBAAkB,EAAE,sBAAsB;IAC1C,eAAe,EAAE,kBAAkB;IACnC,gBAAgB,EAAE,mBAAmB;IACrC,aAAa,EAAE,gBAAgB;IAC/B,aAAa,EAAE,gBAAgB;CACvB,CAAC;AAIX,2CAA2C;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;CACH,CAAC;AAIX,6CAA6C;AAC7C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,oDAAoD;IACpD,IAAI,EAAE,IAAI;IACV,sCAAsC;IACtC,SAAS,EAAE,IAAI;IACf,+BAA+B;IAC/B,QAAQ,EAAE,IAAI;IACd,6BAA6B;IAC7B,MAAM,EAAE,IAAI;IACZ,4BAA4B;IAC5B,KAAK,EAAE,IAAI;CACH,CAAC;AAIX,0BAA0B;AAC1B,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IADlB,YACkB,IAAmB,EACnC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAe;QAInC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,iDAAiD;AACjD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAiB,CAAC;AAC3B,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAiB,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sideband/secure-relay",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Secure Relay Protocol (SBRP): E2EE handshake, session encryption, and TOFU identity pinning for relay-mediated communication.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,9 +45,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@noble/ciphers": "^1.2.1",
-    "@noble/curves": "^1.8.1",
-    "@noble/hashes": "^1.7.1"
+    "@noble/ciphers": "^2.1.1",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1"
   },
   "files": [
     "dist",

package/src/constants.ts

@@ -13,7 +13,7 @@ export const SBRP_TRANSCRIPT_CONTEXT = "sbrp-v1-transcript";
 /** HKDF info string for session key derivation */
 export const SBRP_SESSION_KEYS_INFO = "sbrp-session-keys";
 
-/** Length of session keys in bytes (browserToDaemon + daemonToBrowser) */
+/** Length of session keys in bytes (clientToDaemon + daemonToClient) */
 export const SESSION_KEYS_LENGTH = 64;
 
 /** Length of a single symmetric key in bytes */
@@ -58,8 +58,8 @@ export const MAX_PAYLOAD_SIZE = 65536;
 /** HandshakeInit payload: X25519 ephemeral public key */
 export const HANDSHAKE_INIT_PAYLOAD_SIZE = 32;
 
-/** HandshakeAccept payload: X25519 ephemeral (32) + Ed25519 signature (64) */
-export const HANDSHAKE_ACCEPT_PAYLOAD_SIZE = 96;
+/** HandshakeAccept payload: Ed25519 identity key (32) + X25519 ephemeral (32) + Ed25519 signature (64) */
+export const HANDSHAKE_ACCEPT_PAYLOAD_SIZE = 128;
 
 /** Minimum encrypted payload: nonce (12) + authTag (16), no plaintext */
 export const MIN_ENCRYPTED_PAYLOAD_SIZE = NONCE_LENGTH + AUTH_TAG_LENGTH;

package/src/crypto.test.ts

@@ -153,7 +153,7 @@ describe("crypto", () => {
 
       const signature = signPayload(payload, privateKey);
       // Tamper with signature
-      signature[0] ^= 0xff;
+      signature[0] = signature[0]! ^ 0xff;
 
       const valid = verifySignature(payload, signature, publicKey);
       expect(valid).toBe(false);
@@ -398,7 +398,7 @@ describe("crypto", () => {
       expect(encrypted.length).toBeGreaterThanOrEqual(NONCE_LENGTH + 16); // nonce + authTag
       const nonce = encrypted.slice(0, NONCE_LENGTH);
       const expected = constructNonce(Direction.ClientToDaemon, 42n);
-      expect(nonce).toEqual(expected);
+      expect(Array.from(nonce)).toEqual(Array.from(expected));
     });
 
     it("decryption fails with wrong key", () => {
@@ -416,7 +416,7 @@ describe("crypto", () => {
 
       const encrypted = encrypt(key, Direction.ClientToDaemon, 1n, plaintext);
       // Tamper with ciphertext (after nonce)
-      encrypted[NONCE_LENGTH + 1] ^= 0xff;
+      encrypted[NONCE_LENGTH + 1] = encrypted[NONCE_LENGTH + 1]! ^ 0xff;
 
       expect(() => decrypt(key, encrypted)).toThrow();
     });
@@ -427,7 +427,7 @@ describe("crypto", () => {
 
       const encrypted = encrypt(key, Direction.ClientToDaemon, 1n, plaintext);
       // Tamper with last byte (auth tag)
-      encrypted[encrypted.length - 1] ^= 0xff;
+      encrypted[encrypted.length - 1] = encrypted[encrypted.length - 1]! ^ 0xff;
 
       expect(() => decrypt(key, encrypted)).toThrow();
     });
@@ -438,7 +438,7 @@ describe("crypto", () => {
 
       const encrypted = encrypt(key, Direction.ClientToDaemon, 1n, plaintext);
       // Tamper with nonce
-      encrypted[0] ^= 0xff;
+      encrypted[0] = encrypted[0]! ^ 0xff;
 
       expect(() => decrypt(key, encrypted)).toThrow();
     });

package/src/crypto.ts

@@ -7,12 +7,12 @@
  * and @noble/hashes for SHA-256/HKDF.
  */
 
-import { chacha20poly1305 } from "@noble/ciphers/chacha";
-import { ed25519 } from "@noble/curves/ed25519";
-import { x25519 } from "@noble/curves/ed25519";
-import { hkdf } from "@noble/hashes/hkdf";
-import { sha256 } from "@noble/hashes/sha256";
-import { concatBytes, randomBytes } from "@noble/hashes/utils";
+import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { concatBytes, randomBytes } from "@noble/hashes/utils.js";
 import {
   AUTH_TAG_LENGTH,
   DIRECTION_CLIENT_TO_DAEMON,
@@ -36,14 +36,14 @@ const textEncoder = new TextEncoder();
 
 /** Generate a new Ed25519 identity keypair */
 export function generateIdentityKeyPair(): IdentityKeyPair {
-  const privateKey = ed25519.utils.randomPrivateKey();
+  const privateKey = ed25519.utils.randomSecretKey();
   const publicKey = ed25519.getPublicKey(privateKey);
   return { publicKey, privateKey };
 }
 
 /** Generate a new X25519 ephemeral keypair */
 export function generateEphemeralKeyPair(): EphemeralKeyPair {
-  const privateKey = x25519.utils.randomPrivateKey();
+  const privateKey = x25519.utils.randomSecretKey();
   const publicKey = x25519.getPublicKey(privateKey);
   return { publicKey, privateKey };
 }
@@ -137,7 +137,7 @@ export function deriveSessionKeys(
     sha256,
     sharedSecret,
     transcriptHash,
-    SBRP_SESSION_KEYS_INFO,
+    textEncoder.encode(SBRP_SESSION_KEYS_INFO),
     SESSION_KEYS_LENGTH,
   );
 

package/src/frame.test.ts

@@ -100,6 +100,13 @@ describe("frame codec", () => {
       expect(() => readFrameHeader(short)).toThrow(SbrpError);
     });
 
+    it("rejects unknown frame type", () => {
+      const frame = new Uint8Array(FRAME_HEADER_SIZE);
+      frame[0] = 0x99; // Unknown type
+      expect(() => readFrameHeader(frame)).toThrow(SbrpError);
+      expect(() => readFrameHeader(frame)).toThrow(/Unknown frame type/);
+    });
+
     it("rejects invalid payload length in header", () => {
       const frame = new Uint8Array(FRAME_HEADER_SIZE);
       frame[0] = FrameType.Data;
@@ -222,9 +229,23 @@ describe("frame codec", () => {
       );
     });
 
+    it("rejects wrong identityPublicKey size", () => {
+      const wrongSize: HandshakeAccept = {
+        type: "handshake.accept",
+        identityPublicKey: new Uint8Array(16), // should be 32
+        acceptPublicKey: new Uint8Array(32),
+        signature: new Uint8Array(64),
+      };
+      expect(() => encodeHandshakeAccept(1n, wrongSize)).toThrow(SbrpError);
+      expect(() => encodeHandshakeAccept(1n, wrongSize)).toThrow(
+        /identityPublicKey must be 32 bytes/,
+      );
+    });
+
     it("rejects wrong acceptPublicKey size", () => {
       const wrongSize: HandshakeAccept = {
         type: "handshake.accept",
+        identityPublicKey: new Uint8Array(32),
         acceptPublicKey: new Uint8Array(16), // should be 32
         signature: new Uint8Array(64),
       };
@@ -234,6 +255,7 @@ describe("frame codec", () => {
     it("rejects wrong signature size", () => {
       const wrongSize: HandshakeAccept = {
         type: "handshake.accept",
+        identityPublicKey: new Uint8Array(32),
         acceptPublicKey: new Uint8Array(32),
         signature: new Uint8Array(32), // should be 64
       };
@@ -313,10 +335,12 @@ describe("frame codec", () => {
 
   describe("HandshakeAccept", () => {
     it("encodes and decodes correctly", () => {
+      const identityPublicKey = new Uint8Array(32).fill(0xab);
       const acceptPublicKey = new Uint8Array(32).fill(0xcd);
       const signature = new Uint8Array(64).fill(0xef);
       const accept: HandshakeAccept = {
         type: "handshake.accept",
+        identityPublicKey,
         acceptPublicKey,
         signature,
       };
@@ -331,6 +355,7 @@ describe("frame codec", () => {
 
       const decoded = decodeHandshakeAccept(frame);
       expect(decoded.type).toBe("handshake.accept");
+      expect(decoded.identityPublicKey).toEqual(identityPublicKey);
       expect(decoded.acceptPublicKey).toEqual(acceptPublicKey);
       expect(decoded.signature).toEqual(signature);
     });
@@ -343,10 +368,10 @@ describe("frame codec", () => {
     });
 
     it("rejects zero sessionId on decode", () => {
-      const payload = new Uint8Array(96);
-      const frame = new Uint8Array(FRAME_HEADER_SIZE + 96);
+      const payload = new Uint8Array(128);
+      const frame = new Uint8Array(FRAME_HEADER_SIZE + 128);
       frame[0] = FrameType.HandshakeAccept;
-      new DataView(frame.buffer).setUint32(1, 96, false);
+      new DataView(frame.buffer).setUint32(1, 128, false);
       frame.set(payload, FRAME_HEADER_SIZE);
 
       // Validation happens at decodeFrame level (via readFrameHeader)
@@ -434,7 +459,7 @@ describe("frame codec", () => {
 
       const signal = decodeSignal(frame);
       expect(signal.signal).toBe(SignalCode.Ready);
-      expect(signal.reason).toBe(0);
+      expect(signal.reason).toBe(SignalReason.None);
     });
 
     it("encodes and decodes close signal with reason", () => {
@@ -472,6 +497,22 @@ describe("frame codec", () => {
       expect(signal.reason).toBe(SignalReason.None);
     });
 
+    it("rejects unknown signal code", () => {
+      const payload = new Uint8Array([0xff, 0x00]); // Unknown signal, valid reason
+      const encoded = encodeFrame(FrameType.Signal, 1n, payload);
+      const frame = decodeFrame(encoded);
+      expect(() => decodeSignal(frame)).toThrow(SbrpError);
+      expect(() => decodeSignal(frame)).toThrow(/Unknown signal code/);
+    });
+
+    it("rejects unknown signal reason", () => {
+      const payload = new Uint8Array([0x01, 0xff]); // Valid signal (Close), unknown reason
+      const encoded = encodeFrame(FrameType.Signal, 1n, payload);
+      const frame = decodeFrame(encoded);
+      expect(() => decodeSignal(frame)).toThrow(SbrpError);
+      expect(() => decodeSignal(frame)).toThrow(/Unknown signal reason/);
+    });
+
     it("rejects wrong payload size", () => {
       const wrongPayload = new Uint8Array(3);
       const encoded = encodeFrame(FrameType.Signal, 1n, wrongPayload);
@@ -531,6 +572,14 @@ describe("frame codec", () => {
       const frame = decodeFrame(encoded);
       expect(() => decodeControl(frame)).toThrow(SbrpError);
     });
+
+    it("rejects unknown control code", () => {
+      const payload = new Uint8Array([0x99, 0x99]); // Unknown code 0x9999
+      const encoded = encodeFrame(FrameType.Control, 0n, payload);
+      const frame = decodeFrame(encoded);
+      expect(() => decodeControl(frame)).toThrow(SbrpError);
+      expect(() => decodeControl(frame)).toThrow(/Unknown control code/);
+    });
   });
 
   describe("isTerminalCode", () => {
@@ -744,8 +793,8 @@ describe("frame codec", () => {
       const frame = encodePing();
       const frames = [...decoder.push(frame)];
       expect(frames.length).toBe(1);
-      expect(frames[0].type).toBe(FrameType.Ping);
-      expect(frames[0].sessionId).toBe(0n);
+      expect(frames[0]!.type).toBe(FrameType.Ping);
+      expect(frames[0]!.sessionId).toBe(0n);
     });
 
     it("decodes multiple frames in one push", () => {
@@ -758,8 +807,8 @@ describe("frame codec", () => {
 
       const frames = [...decoder.push(combined)];
       expect(frames.length).toBe(2);
-      expect(frames[0].type).toBe(FrameType.Ping);
-      expect(frames[1].type).toBe(FrameType.Pong);
+      expect(frames[0]!.type).toBe(FrameType.Ping);
+      expect(frames[1]!.type).toBe(FrameType.Pong);
     });
 
     it("buffers incomplete frames", () => {
@@ -774,7 +823,7 @@ describe("frame codec", () => {
       // Push rest
       frames = [...decoder.push(frame.subarray(FRAME_HEADER_SIZE))];
       expect(frames.length).toBe(1);
-      expect(frames[0].type).toBe(FrameType.Control);
+      expect(frames[0]!.type).toBe(FrameType.Control);
       expect(decoder.bufferedBytes).toBe(0);
     });
 
@@ -791,7 +840,7 @@ describe("frame codec", () => {
       }
 
       expect(allFrames.length).toBe(1);
-      expect(allFrames[0].type).toBe(FrameType.Ping);
+      expect(allFrames[0]!.type).toBe(FrameType.Ping);
     });
 
     it("resets state correctly", () => {