@sideband/secure-relay 0.1.0 → 0.2.1

package/src/handshake.test.ts

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "bun:test";
+import { generateIdentityKeyPair } from "./crypto.js";
+import {
+  createHandshakeInit,
+  processHandshakeAccept,
+  processHandshakeInit,
+} from "./handshake.js";
+import { asDaemonId, SbrpError, SbrpErrorCode } from "./types.js";
+
+describe("handshake", () => {
+  const daemonId = asDaemonId("test-daemon-123");
+
+  describe("full handshake flow", () => {
+    it("completes handshake between client and daemon", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      // Client creates init
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+
+      // Daemon processes init and creates accept
+      const { message: accept, result: daemonResult } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+
+      // Client processes accept
+      const clientResult = processHandshakeAccept(
+        accept,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral,
+      );
+
+      // Both should have valid session keys
+      expect(clientResult.sessionKeys).toBeDefined();
+      expect(daemonResult.sessionKeys).toBeDefined();
+    });
+  });
+
+  describe("session key derivation", () => {
+    it("derives identical session keys on both sides", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept, result: daemonResult } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+      const clientResult = processHandshakeAccept(
+        accept,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral,
+      );
+
+      // Keys should be byte-for-byte identical
+      expect(clientResult.sessionKeys.clientToDaemon).toEqual(
+        daemonResult.sessionKeys.clientToDaemon,
+      );
+      expect(clientResult.sessionKeys.daemonToClient).toEqual(
+        daemonResult.sessionKeys.daemonToClient,
+      );
+    });
+
+    it("derives directional keys (clientToDaemon != daemonToClient)", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept, result: daemonResult } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+      const clientResult = processHandshakeAccept(
+        accept,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral,
+      );
+
+      // Directional keys must differ to prevent reflection attacks
+      expect(clientResult.sessionKeys.clientToDaemon).not.toEqual(
+        clientResult.sessionKeys.daemonToClient,
+      );
+      expect(daemonResult.sessionKeys.clientToDaemon).not.toEqual(
+        daemonResult.sessionKeys.daemonToClient,
+      );
+    });
+
+    it("produces different keys for different handshakes (ephemeral randomness)", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      // First handshake
+      const { message: init1, ephemeralKeyPair: clientEphemeral1 } =
+        createHandshakeInit();
+      const { message: accept1 } = processHandshakeInit(
+        init1,
+        daemonId,
+        daemonIdentity,
+      );
+      const result1 = processHandshakeAccept(
+        accept1,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral1,
+      );
+
+      // Second handshake
+      const { message: init2, ephemeralKeyPair: clientEphemeral2 } =
+        createHandshakeInit();
+      const { message: accept2 } = processHandshakeInit(
+        init2,
+        daemonId,
+        daemonIdentity,
+      );
+      const result2 = processHandshakeAccept(
+        accept2,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral2,
+      );
+
+      // Keys from different handshakes should differ
+      expect(result1.sessionKeys.clientToDaemon).not.toEqual(
+        result2.sessionKeys.clientToDaemon,
+      );
+      expect(result1.sessionKeys.daemonToClient).not.toEqual(
+        result2.sessionKeys.daemonToClient,
+      );
+    });
+  });
+
+  describe("signature verification", () => {
+    it("fails with wrong identity key (throws SbrpError with HandshakeFailed)", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+      const wrongIdentity = generateIdentityKeyPair();
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+
+      // Client tries to verify with wrong identity key
+      expect(() =>
+        processHandshakeAccept(
+          accept,
+          daemonId,
+          wrongIdentity.publicKey, // wrong key!
+          clientEphemeral,
+        ),
+      ).toThrow(SbrpError);
+
+      try {
+        processHandshakeAccept(
+          accept,
+          daemonId,
+          wrongIdentity.publicKey,
+          clientEphemeral,
+        );
+      } catch (err) {
+        expect(err).toBeInstanceOf(SbrpError);
+        expect((err as SbrpError).code).toBe(SbrpErrorCode.HandshakeFailed);
+      }
+    });
+
+    it("fails with tampered signature", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+
+      // Tamper with the signature
+      const tamperedAccept = {
+        ...accept,
+        signature: new Uint8Array(accept.signature),
+      };
+      tamperedAccept.signature[0] ^= 0xff; // flip bits
+
+      expect(() =>
+        processHandshakeAccept(
+          tamperedAccept,
+          daemonId,
+          daemonIdentity.publicKey,
+          clientEphemeral,
+        ),
+      ).toThrow(SbrpError);
+    });
+
+    it("fails with wrong daemon ID in verification", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+      const wrongDaemonId = asDaemonId("wrong-daemon-456");
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+
+      // Client tries to verify with wrong daemon ID
+      expect(() =>
+        processHandshakeAccept(
+          accept,
+          wrongDaemonId, // wrong daemon ID!
+          daemonIdentity.publicKey,
+          clientEphemeral,
+        ),
+      ).toThrow(SbrpError);
+
+      try {
+        processHandshakeAccept(
+          accept,
+          wrongDaemonId,
+          daemonIdentity.publicKey,
+          clientEphemeral,
+        );
+      } catch (err) {
+        expect(err).toBeInstanceOf(SbrpError);
+        expect((err as SbrpError).code).toBe(SbrpErrorCode.HandshakeFailed);
+      }
+    });
+  });
+
+  describe("createHandshakeInit", () => {
+    it("returns 32-byte ephemeral public key", () => {
+      const { message, ephemeralKeyPair } = createHandshakeInit();
+
+      expect(message.type).toBe("handshake.init");
+      expect(message.initPublicKey).toBeInstanceOf(Uint8Array);
+      expect(message.initPublicKey.length).toBe(32);
+      expect(ephemeralKeyPair.publicKey).toEqual(message.initPublicKey);
+      expect(ephemeralKeyPair.privateKey.length).toBe(32);
+    });
+
+    it("generates different ephemeral keys each time", () => {
+      const result1 = createHandshakeInit();
+      const result2 = createHandshakeInit();
+
+      expect(result1.message.initPublicKey).not.toEqual(
+        result2.message.initPublicKey,
+      );
+      expect(result1.ephemeralKeyPair.privateKey).not.toEqual(
+        result2.ephemeralKeyPair.privateKey,
+      );
+    });
+  });
+
+  describe("processHandshakeInit", () => {
+    it("returns 64-byte signature and 32-byte ephemeral key", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+      const { message: init } = createHandshakeInit();
+
+      const { message: accept, result } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+
+      expect(accept.type).toBe("handshake.accept");
+      expect(accept.acceptPublicKey).toBeInstanceOf(Uint8Array);
+      expect(accept.acceptPublicKey.length).toBe(32);
+      expect(accept.signature).toBeInstanceOf(Uint8Array);
+      expect(accept.signature.length).toBe(64);
+      expect(result.signature).toEqual(accept.signature);
+      expect(result.ephemeralKeyPair.publicKey).toEqual(accept.acceptPublicKey);
+    });
+
+    it("generates different ephemeral keys and signatures each time", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+      const { message: init } = createHandshakeInit();
+
+      const result1 = processHandshakeInit(init, daemonId, daemonIdentity);
+      const result2 = processHandshakeInit(init, daemonId, daemonIdentity);
+
+      // Different ephemeral keys
+      expect(result1.message.acceptPublicKey).not.toEqual(
+        result2.message.acceptPublicKey,
+      );
+
+      // Different signatures (due to different ephemeral keys in payload)
+      expect(result1.message.signature).not.toEqual(result2.message.signature);
+    });
+  });
+
+  describe("session key properties", () => {
+    it("derives 32-byte symmetric keys", () => {
+      const daemonIdentity = generateIdentityKeyPair();
+
+      const { message: init, ephemeralKeyPair: clientEphemeral } =
+        createHandshakeInit();
+      const { message: accept, result: daemonResult } = processHandshakeInit(
+        init,
+        daemonId,
+        daemonIdentity,
+      );
+      const clientResult = processHandshakeAccept(
+        accept,
+        daemonId,
+        daemonIdentity.publicKey,
+        clientEphemeral,
+      );
+
+      expect(clientResult.sessionKeys.clientToDaemon.length).toBe(32);
+      expect(clientResult.sessionKeys.daemonToClient.length).toBe(32);
+      expect(daemonResult.sessionKeys.clientToDaemon.length).toBe(32);
+      expect(daemonResult.sessionKeys.daemonToClient.length).toBe(32);
+    });
+  });
+});

package/src/handshake.ts

@@ -1,5 +1,4 @@
-// SPDX-FileCopyrightText: 2025-present Sideband
-// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-License-Identifier: Apache-2.0
 
 /**
  * E2EE handshake protocol for Sideband Relay Protocol (SBRP).
@@ -66,6 +65,9 @@ export function createHandshakeInit(): {
  * 1. Generate ephemeral X25519 keypair
  * 2. Sign ephemeral public key with identity key (context-bound)
  * 3. Derive session keys
+ *
+ * NOTE: Callers MUST enforce a 30-second handshake timeout per SBRP §1.4.
+ * This function does not track time; timeout enforcement is a transport concern.
  */
 export function processHandshakeInit(
   init: HandshakeInit,
@@ -118,6 +120,9 @@ export function processHandshakeInit(
  * 1. Verify signature using PINNED identity key (TOFU)
  * 2. Derive session keys using same transcript hash as daemon
  *
+ * NOTE: Callers MUST enforce a 30-second handshake timeout per SBRP §1.4.
+ * This function does not track time; timeout enforcement is a transport concern.
+ *
  * @throws {SbrpError} with code HandshakeFailed if signature verification fails
  */
 export function processHandshakeAccept(

package/src/index.ts

@@ -1,5 +1,4 @@
-// SPDX-FileCopyrightText: 2025-present Sideband
-// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-License-Identifier: Apache-2.0
 
 /**
  * @sideband/secure-relay
@@ -46,6 +45,7 @@ export type {
   HandshakeInit,
   IdentityKeyPair,
   PinnedIdentity,
+  SessionId,
   SessionKeys,
 } from "./types.js";
 
@@ -55,6 +55,8 @@ export {
   Direction,
   SbrpError,
   SbrpErrorCode,
+  SignalCode,
+  SignalReason,
 } from "./types.js";
 
 // Constants
@@ -66,11 +68,19 @@ export {
   ED25519_PRIVATE_KEY_LENGTH,
   ED25519_PUBLIC_KEY_LENGTH,
   ED25519_SIGNATURE_LENGTH,
+  FRAME_HEADER_SIZE,
+  HANDSHAKE_ACCEPT_PAYLOAD_SIZE,
+  HANDSHAKE_INIT_PAYLOAD_SIZE,
+  MAX_PAYLOAD_SIZE,
+  MAX_PING_PAYLOAD_SIZE,
+  MIN_CONTROL_PAYLOAD_SIZE,
+  MIN_ENCRYPTED_PAYLOAD_SIZE,
   NONCE_LENGTH,
   SBRP_HANDSHAKE_CONTEXT,
   SBRP_SESSION_KEYS_INFO,
   SBRP_TRANSCRIPT_CONTEXT,
   SESSION_KEYS_LENGTH,
+  SIGNAL_PAYLOAD_SIZE,
   SYMMETRIC_KEY_LENGTH,
   X25519_PRIVATE_KEY_LENGTH,
   X25519_PUBLIC_KEY_LENGTH,
@@ -130,3 +140,35 @@ export {
   encryptClientToDaemon,
   encryptDaemonToClient,
 } from "./session.js";
+
+// Wire format (binary framing)
+export type {
+  ControlPayload,
+  Frame,
+  FrameHeader,
+  SignalPayload,
+} from "./frame.js";
+
+export {
+  decodeControl,
+  decodeData,
+  decodeFrame,
+  decodeHandshakeAccept,
+  decodeHandshakeInit,
+  decodeSignal,
+  encodeControl,
+  encodeData,
+  encodeFrame,
+  encodeHandshakeAccept,
+  encodeHandshakeInit,
+  encodePing,
+  encodePong,
+  encodeSignal,
+  FrameDecoder,
+  FrameType,
+  fromWireControlCode,
+  isTerminalCode,
+  readFrameHeader,
+  toWireControlCode,
+  WireControlCode,
+} from "./frame.js";