@sideband/secure-relay 0.2.0 → 0.2.2

package/README.md

@@ -12,7 +12,7 @@ Implements authenticated handshake, key derivation, and message encryption for s
 - **TOFU identity pinning** — Trust-on-first-use with key change detection
 - **Replay protection** — Bitmap-based sequence window
 
-## Non-Goals
+## Non-goals
 
 This package intentionally does NOT:
 
@@ -21,6 +21,23 @@ This package intentionally does NOT:
 - Persist identity keys or TOFU pins
 - Implement relay authentication or tokens
 
+## Threat model
+
+This package protects the **payload** of messages between a browser client and a daemon via an untrusted relay. Specifically:
+
+- The relay cannot read or tamper with message content (authenticated encryption).
+- A MITM cannot impersonate the daemon without its Ed25519 private key (signature verification on handshake).
+- Replayed messages are rejected within the sequence window.
+
+It does **not** protect against:
+
+- Compromise of the daemon's identity key (store it securely; if lost, all clients see a TOFU mismatch).
+- Traffic analysis (message sizes and timing are visible to the relay).
+- Key storage security — this package has no opinion on where keys live; that's the caller's responsibility.
+- Denial of service from a malicious relay (the relay can drop or delay messages).
+
+This implementation has not undergone a formal third-party security audit. Use accordingly.
+
 ## Install
 
 ```bash
@@ -78,7 +95,7 @@ const encrypted = encryptClientToDaemon(daemonSession, plaintext);
 const decrypted = decryptClientToDaemon(clientSession, encrypted);
 ```
 
-## TOFU Security
+## TOFU security
 
 Identity keys use trust-on-first-use (TOFU) pinning:
 
@@ -86,7 +103,44 @@ Identity keys use trust-on-first-use (TOFU) pinning:
 - Never accept key changes silently — `identity_key_changed` indicates potential MITM
 - On mismatch, present both fingerprints and require explicit user approval
 
-## Error Handling
+### Detecting identity key changes
+
+Compare the daemon's current identity key against your stored pin before handshake:
+
+```ts
+import {
+  processHandshakeAccept,
+  computeFingerprint,
+  SbrpError,
+  SbrpErrorCode,
+} from "@sideband/secure-relay";
+
+// Load pinned key from storage (null on first connection)
+const pinnedKey = await storage.get(`tofu:${daemonId}`);
+
+if (pinnedKey && !equalBytes(pinnedKey, currentIdentityKey)) {
+  // Key changed — potential MITM attack
+  throw new SbrpError(
+    SbrpErrorCode.IdentityKeyChanged,
+    `Identity key changed for ${daemonId}. ` +
+      `Expected: ${computeFingerprint(pinnedKey)}, ` +
+      `Got: ${computeFingerprint(currentIdentityKey)}`,
+  );
+}
+
+// First connection: pin the key after successful handshake
+const result = processHandshakeAccept(
+  accept,
+  daemonId,
+  currentIdentityKey,
+  ephemeralKeyPair,
+);
+if (!pinnedKey) {
+  await storage.set(`tofu:${daemonId}`, currentIdentityKey);
+}
+```
+
+## Error handling
 
 All errors throw `SbrpError` with a specific `code`:
 

package/package.json

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

package/src/constants.ts

@@ -40,8 +40,8 @@ export const NONCE_LENGTH = 12;
 /** Length of Poly1305 auth tag in bytes */
 export const AUTH_TAG_LENGTH = 16;
 
-/** Default replay window size (bits) */
-export const DEFAULT_REPLAY_WINDOW_SIZE = 64n;
+/** Default replay window size (bits). Spec requires ≥64, recommends ≥128. */
+export const DEFAULT_REPLAY_WINDOW_SIZE = 128n;
 
 /** Direction bytes in nonce (4 bytes, big-endian) */
 export const DIRECTION_CLIENT_TO_DAEMON = new Uint8Array([0, 0, 0, 1]);

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/handshake.ts

@@ -65,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,
@@ -117,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/session.test.ts

@@ -185,16 +185,16 @@ describe("session", () => {
       const daemonSession = createDaemonSession(sessionKeys);
       const clientSession = createClientSession(clientId, sessionKeys);
 
-      // Encrypt 100 messages to advance the window
+      // Encrypt 200 messages to advance the window (default window is 128)
       const messages: EncryptedMessage[] = [];
-      for (let i = 0; i < 100; i++) {
+      for (let i = 0; i < 200; i++) {
         messages.push(
-          encryptClientToDaemon(daemonSession, new Uint8Array([i])),
+          encryptClientToDaemon(daemonSession, new Uint8Array([i % 256])),
         );
       }
 
-      // Decrypt latest 64 (within window)
-      for (let i = 99; i >= 36; i--) {
+      // Decrypt latest 128 (within window)
+      for (let i = 199; i >= 72; i--) {
         decryptClientToDaemon(clientSession, messages[i]);
       }
 
@@ -217,16 +217,16 @@ describe("session", () => {
       const daemonSession = createDaemonSession(sessionKeys);
       const clientSession = createClientSession(clientId, sessionKeys);
 
-      // Encrypt 100 messages to advance the window
+      // Encrypt 200 messages to advance the window (default window is 128)
       const messages: EncryptedMessage[] = [];
-      for (let i = 0; i < 100; i++) {
+      for (let i = 0; i < 200; i++) {
         messages.push(
-          encryptDaemonToClient(clientSession, new Uint8Array([i])),
+          encryptDaemonToClient(clientSession, new Uint8Array([i % 256])),
         );
       }
 
-      // Decrypt latest 64 (within window)
-      for (let i = 99; i >= 36; i--) {
+      // Decrypt latest 128 (within window)
+      for (let i = 199; i >= 72; i--) {
         decryptDaemonToClient(daemonSession, messages[i]);
       }