@sideband/secure-relay 0.2.0 → 0.2.1

package/README.md

@@ -86,6 +86,43 @@ 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
 
+### 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.1",
   "description": "Secure Relay Protocol (SBRP): E2EE handshake, session encryption, and TOFU identity pinning for relay-mediated communication.",
   "license": "Apache-2.0",
   "repository": {
@@ -49,9 +49,6 @@
     "@noble/curves": "^1.8.1",
     "@noble/hashes": "^1.7.1"
   },
-  "devDependencies": {
-    "@types/bun": "^1.3.3"
-  },
   "files": [
     "dist",
     "src"

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/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]);
       }