@sideband/secure-relay 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,8 @@
 # @sideband/secure-relay
 
-End-to-end encrypted communication between browsers and daemons via untrusted relay servers.
+Low-level E2EE primitives for the Sideband Relay Protocol (SBRP).
+
+Implements authenticated handshake, key derivation, and message encryption for secure browser ↔ daemon communication via untrusted relay servers. Most applications should use `@sideband/peer` instead of this package directly.
 
 ## Features
 
@@ -10,6 +12,15 @@ End-to-end encrypted communication between browsers and daemons via untrusted re
 - **TOFU identity pinning** — Trust-on-first-use with key change detection
 - **Replay protection** — Bitmap-based sequence window
 
+## Non-Goals
+
+This package intentionally does NOT:
+
+- Handle network transport or WebSockets
+- Manage session lifecycle or reconnection
+- Persist identity keys or TOFU pins
+- Implement relay authentication or tokens
+
 ## Install
 
 ```bash
@@ -18,7 +29,7 @@ bun add @sideband/secure-relay
 
 ## Usage
 
-```typescript
+```ts
 import {
   generateIdentityKeyPair,
   createHandshakeInit,
@@ -34,7 +45,8 @@ import {
   asClientId,
 } from "@sideband/secure-relay";
 
-// Daemon: generate identity keypair (persist this!)
+// Daemon: generate identity keypair ONCE and persist securely.
+// Regenerating causes TOFU mismatch warnings for all clients.
 const identity = generateIdentityKeyPair();
 const daemonId = asDaemonId("my-daemon");
 
@@ -61,25 +73,72 @@ const { sessionKeys } = processHandshakeAccept(
 );
 const daemonSession = createDaemonSession(sessionKeys);
 
-// Encrypt/decrypt messages
+// Encrypt/decrypt messages (sessions are stateful — do not clone)
 const encrypted = encryptClientToDaemon(daemonSession, plaintext);
 const decrypted = decryptClientToDaemon(clientSession, encrypted);
 ```
 
+## TOFU Security
+
+Identity keys use trust-on-first-use (TOFU) pinning:
+
+- Pin daemon identity keys on first successful handshake
+- 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`:
 
-| Code                   | Meaning                                   |
-| ---------------------- | ----------------------------------------- |
-| `identity_key_changed` | Pinned key doesn't match (potential MITM) |
-| `handshake_failed`     | Signature verification failed             |
-| `decrypt_failed`       | Message authentication failed             |
-| `sequence_error`       | Replay detected or sequence out of window |
+| Code                   | Meaning                                   | Recovery                  |
+| ---------------------- | ----------------------------------------- | ------------------------- |
+| `identity_key_changed` | Pinned key doesn't match (potential MITM) | Close session, alert user |
+| `handshake_failed`     | Signature verification failed             | Close session             |
+| `decrypt_failed`       | Message authentication failed             | Close session             |
+| `sequence_error`       | Replay detected or sequence out of window | Close session             |
+
+All errors are fatal — close the session and re-handshake.
 
 ## Specification
 
-See [Secure Relay Protocol](https://sideband.tech/specs/secure-relay-protocol) for the full protocol specification.
+See the [SBRP protocol specification](https://sideband.tech/protocols/sbrp/) for implementation details.
 
 ## License