@sideband/secure-relay 0.0.1 → 0.2.0

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,35 @@ 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
+
 ## 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
 

package/{LICENSE → dist/LICENSE}

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -48,7 +49,7 @@
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
       to that Work or Derivative Works thereof, that is intentionally
-      submitted to the Licensor for inclusion in the Work by the copyright owner
+      submitted to Licensor for inclusion in the Work by the copyright owner
       or by an individual or Legal Entity authorized to submit on behalf of
       the copyright owner. For the purposes of this definition, "submitted"
       means any form of electronic, verbal, or written communication sent
@@ -175,7 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2025-present Sideband <https://sideband.tech>
+   Copyright 2025 Sideband Project
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sideband/secure-relay",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Secure Relay Protocol (SBRP): E2EE handshake, session encryption, and TOFU identity pinning for relay-mediated communication.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,7 +40,6 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "bun": "./src/index.ts",
       "default": "./dist/index.js"
     },
     "./package.json": "./package.json"

package/src/constants.ts

@@ -1,5 +1,4 @@
-// SPDX-FileCopyrightText: 2025-present Sideband
-// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-License-Identifier: Apache-2.0
 
 /**
  * Protocol constants for Sideband Relay Protocol (SBRP).
@@ -47,3 +46,29 @@ export const DEFAULT_REPLAY_WINDOW_SIZE = 64n;
 /** Direction bytes in nonce (4 bytes, big-endian) */
 export const DIRECTION_CLIENT_TO_DAEMON = new Uint8Array([0, 0, 0, 1]);
 export const DIRECTION_DAEMON_TO_CLIENT = new Uint8Array([0, 0, 0, 2]);
+
+// Wire format constants (§13)
+
+/** Frame header size: type (1) + length (4) + sessionId (8) */
+export const FRAME_HEADER_SIZE = 13;
+
+/** Maximum payload size in bytes (64 KB) */
+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;
+
+/** Minimum encrypted payload: nonce (12) + authTag (16), no plaintext */
+export const MIN_ENCRYPTED_PAYLOAD_SIZE = NONCE_LENGTH + AUTH_TAG_LENGTH;
+
+/** Control payload minimum: code (2 bytes) */
+export const MIN_CONTROL_PAYLOAD_SIZE = 2;
+
+/** Signal payload size: signal (1) + reason (1) */
+export const SIGNAL_PAYLOAD_SIZE = 2;
+
+/** Maximum Ping/Pong payload size (0-8 bytes for RTT nonce) */
+export const MAX_PING_PAYLOAD_SIZE = 8;