@sideband/secure-relay 0.2.2 → 0.3.0

package/dist/types.js

@@ -0,0 +1,81 @@
+// 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) - Terminal
+    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",
+    // Throttling (0x09xx) - Varies (rate_limited=N, backpressure=T)
+    RateLimited: "rate_limited",
+    Backpressure: "backpressure",
+    // 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,8BAA8B;IAC9B,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,gEAAgE;IAChE,WAAW,EAAE,cAAc;IAC3B,YAAY,EAAE,cAAc;IAE5B,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.2",
+  "version": "0.3.0",
   "description": "Secure Relay Protocol (SBRP): E2EE handshake, session encryption, and TOFU identity pinning for relay-mediated communication.",
   "license": "Apache-2.0",
   "repository": {

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/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);
@@ -515,6 +556,17 @@ describe("frame codec", () => {
       expect(control.code).toBe(WireControlCode.SessionPaused);
     });
 
+    it("encodes and decodes backpressure (0x0902, terminal, SID=0)", () => {
+      const encoded = encodeControl(0n, WireControlCode.Backpressure);
+      const frame = decodeFrame(encoded);
+      expect(frame.sessionId).toBe(0n);
+
+      const control = decodeControl(frame);
+      expect(control.code).toBe(WireControlCode.Backpressure);
+      expect(control.code).toBe(0x0902);
+      expect(isTerminalCode(control.code)).toBe(true);
+    });
+
     it("handles invalid UTF-8 by replacing", () => {
       // Create control frame with invalid UTF-8 in message
       const payload = new Uint8Array([0x01, 0x01, 0xff, 0xfe]); // code 0x0101 + invalid UTF-8
@@ -531,30 +583,49 @@ 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", () => {
     it("returns true for terminal codes", () => {
-      expect(isTerminalCode(WireControlCode.Unauthorized)).toBe(true);
-      expect(isTerminalCode(WireControlCode.Forbidden)).toBe(true);
-      expect(isTerminalCode(WireControlCode.DaemonNotFound)).toBe(true);
-      expect(isTerminalCode(WireControlCode.SessionNotFound)).toBe(true);
-      expect(isTerminalCode(WireControlCode.SessionExpired)).toBe(true);
-      expect(isTerminalCode(WireControlCode.MalformedFrame)).toBe(true);
-      expect(isTerminalCode(WireControlCode.PayloadTooLarge)).toBe(true);
-      expect(isTerminalCode(WireControlCode.InvalidFrameType)).toBe(true);
-      expect(isTerminalCode(WireControlCode.InvalidSessionId)).toBe(true);
-      expect(isTerminalCode(WireControlCode.DisallowedSender)).toBe(true);
-      expect(isTerminalCode(WireControlCode.InternalError)).toBe(true);
+      const terminalCodes: WireControlCode[] = [
+        WireControlCode.Unauthorized,
+        WireControlCode.Forbidden,
+        WireControlCode.DaemonNotFound,
+        WireControlCode.DaemonOffline,
+        WireControlCode.SessionNotFound,
+        WireControlCode.SessionExpired,
+        WireControlCode.MalformedFrame,
+        WireControlCode.PayloadTooLarge,
+        WireControlCode.InvalidFrameType,
+        WireControlCode.InvalidSessionId,
+        WireControlCode.DisallowedSender,
+        WireControlCode.InternalError,
+        WireControlCode.Backpressure,
+      ];
+      for (const code of terminalCodes) {
+        expect(isTerminalCode(code)).toBe(true);
+      }
     });
 
     it("returns false for non-terminal codes", () => {
-      expect(isTerminalCode(WireControlCode.DaemonOffline)).toBe(false);
-      expect(isTerminalCode(WireControlCode.RateLimited)).toBe(false);
-      expect(isTerminalCode(WireControlCode.SessionPaused)).toBe(false);
-      expect(isTerminalCode(WireControlCode.SessionResumed)).toBe(false);
-      expect(isTerminalCode(WireControlCode.SessionEnded)).toBe(false);
-      expect(isTerminalCode(WireControlCode.SessionPending)).toBe(false);
+      const nonTerminalCodes: WireControlCode[] = [
+        WireControlCode.RateLimited,
+        WireControlCode.SessionPaused,
+        WireControlCode.SessionResumed,
+        WireControlCode.SessionEnded,
+        WireControlCode.SessionPending,
+      ];
+      for (const code of nonTerminalCodes) {
+        expect(isTerminalCode(code)).toBe(false);
+      }
     });
   });
 
@@ -582,8 +653,9 @@ describe("frame codec", () => {
       // Internal (0x06xx)
       expect(WireControlCode.InternalError).toBe(0x0601);
 
-      // Rate Limiting (0x09xx)
+      // Rate Limiting / Backpressure (0x09xx)
       expect(WireControlCode.RateLimited).toBe(0x0901);
+      expect(WireControlCode.Backpressure).toBe(0x0902);
 
       // Session State (0x10xx)
       expect(WireControlCode.SessionPaused).toBe(0x1001);
@@ -705,24 +777,6 @@ describe("frame codec", () => {
       );
     });
 
-    it("converts all WireControlCode to SbrpErrorCode", () => {
-      expect(fromWireControlCode(WireControlCode.Unauthorized)).toBe(
-        SbrpErrorCode.Unauthorized,
-      );
-      expect(fromWireControlCode(WireControlCode.MalformedFrame)).toBe(
-        SbrpErrorCode.MalformedFrame,
-      );
-      expect(fromWireControlCode(WireControlCode.InvalidSessionId)).toBe(
-        SbrpErrorCode.InvalidSessionId,
-      );
-      expect(fromWireControlCode(WireControlCode.InternalError)).toBe(
-        SbrpErrorCode.InternalError,
-      );
-      expect(fromWireControlCode(WireControlCode.SessionPaused)).toBe(
-        SbrpErrorCode.SessionPaused,
-      );
-    });
-
     it("throws on endpoint-only codes (never transmitted on wire)", () => {
       expect(() =>
         toWireControlCode(SbrpErrorCode.IdentityKeyChanged),
@@ -733,8 +787,20 @@ describe("frame codec", () => {
       expect(() => toWireControlCode(SbrpErrorCode.SequenceError)).toThrow();
     });
 
+    it("covers all WireControlCode entries bidirectionally", () => {
+      // Exhaustive check: every wire code must round-trip through both mappings.
+      // This catches missing entries (e.g., 0x0902 backpressure) that a spot-check would miss.
+      const allCodes = Object.values(WireControlCode) as WireControlCode[];
+      for (const wireCode of allCodes) {
+        const sbrpCode = fromWireControlCode(wireCode);
+        expect(toWireControlCode(sbrpCode)).toBe(wireCode);
+      }
+    });
+
     it("throws on unknown wire codes", () => {
-      expect(() => fromWireControlCode(0x9999 as WireControlCode)).toThrow();
+      expect(() => fromWireControlCode(0x9999 as WireControlCode)).toThrow(
+        /0x9999/,
+      );
     });
   });
 
@@ -744,8 +810,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 +824,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 +840,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 +857,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", () => {