@sideband/secure-relay 0.0.1

package/src/handshake.ts

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * E2EE handshake protocol for Sideband Relay Protocol (SBRP).
+ *
+ * Implements the authenticated key exchange between client and daemon,
+ * with Ed25519 signatures for MITM protection.
+ */
+
+import {
+  computeSharedSecret,
+  createSignaturePayload,
+  createTranscriptHash,
+  deriveSessionKeys,
+  generateEphemeralKeyPair,
+  signPayload,
+  verifySignature,
+  zeroize,
+} from "./crypto.js";
+import type {
+  DaemonId,
+  EphemeralKeyPair,
+  HandshakeAccept,
+  HandshakeInit,
+  IdentityKeyPair,
+  SessionKeys,
+} from "./types.js";
+import { SbrpError, SbrpErrorCode } from "./types.js";
+
+/** Result of a successful daemon handshake */
+export interface DaemonHandshakeResult {
+  sessionKeys: SessionKeys;
+  ephemeralKeyPair: EphemeralKeyPair;
+  signature: Uint8Array;
+}
+
+/** Result of a successful client handshake */
+export interface ClientHandshakeResult {
+  sessionKeys: SessionKeys;
+  ephemeralKeyPair: EphemeralKeyPair;
+}
+
+/**
+ * Create a handshake init message (client side).
+ *
+ * Generates an ephemeral X25519 keypair for this session.
+ */
+export function createHandshakeInit(): {
+  message: HandshakeInit;
+  ephemeralKeyPair: EphemeralKeyPair;
+} {
+  const ephemeralKeyPair = generateEphemeralKeyPair();
+  return {
+    message: {
+      type: "handshake.init",
+      initPublicKey: ephemeralKeyPair.publicKey,
+    },
+    ephemeralKeyPair,
+  };
+}
+
+/**
+ * Process handshake init and create accept message (daemon side).
+ *
+ * 1. Generate ephemeral X25519 keypair
+ * 2. Sign ephemeral public key with identity key (context-bound)
+ * 3. Derive session keys
+ */
+export function processHandshakeInit(
+  init: HandshakeInit,
+  daemonId: DaemonId,
+  identityKeyPair: IdentityKeyPair,
+): { message: HandshakeAccept; result: DaemonHandshakeResult } {
+  const ephemeralKeyPair = generateEphemeralKeyPair();
+
+  // Sign ephemeral key with context binding
+  const signaturePayload = createSignaturePayload(
+    daemonId,
+    init.initPublicKey,
+    ephemeralKeyPair.publicKey,
+  );
+  const signature = signPayload(signaturePayload, identityKeyPair.privateKey);
+
+  // Derive session keys
+  const sharedSecret = computeSharedSecret(
+    ephemeralKeyPair.privateKey,
+    init.initPublicKey,
+  );
+  const transcriptHash = createTranscriptHash(
+    daemonId,
+    init.initPublicKey,
+    ephemeralKeyPair.publicKey,
+    signature,
+  );
+  const sessionKeys = deriveSessionKeys(sharedSecret, transcriptHash);
+
+  // Best-effort zeroize shared secret
+  zeroize(sharedSecret);
+
+  return {
+    message: {
+      type: "handshake.accept",
+      acceptPublicKey: ephemeralKeyPair.publicKey,
+      signature,
+    },
+    result: {
+      sessionKeys,
+      ephemeralKeyPair,
+      signature,
+    },
+  };
+}
+
+/**
+ * Process handshake accept message (client side).
+ *
+ * 1. Verify signature using PINNED identity key (TOFU)
+ * 2. Derive session keys using same transcript hash as daemon
+ *
+ * @throws {SbrpError} with code HandshakeFailed if signature verification fails
+ */
+export function processHandshakeAccept(
+  accept: HandshakeAccept,
+  daemonId: DaemonId,
+  pinnedIdentityPublicKey: Uint8Array,
+  ephemeralKeyPair: EphemeralKeyPair,
+): ClientHandshakeResult {
+  // Verify daemon signature using PINNED key (not relay-provided!)
+  const signaturePayload = createSignaturePayload(
+    daemonId,
+    ephemeralKeyPair.publicKey,
+    accept.acceptPublicKey,
+  );
+
+  const valid = verifySignature(
+    signaturePayload,
+    accept.signature,
+    pinnedIdentityPublicKey,
+  );
+
+  if (!valid) {
+    throw new SbrpError(
+      SbrpErrorCode.HandshakeFailed,
+      "Signature verification failed",
+    );
+  }
+
+  // Derive session keys using same transcript hash as daemon
+  const sharedSecret = computeSharedSecret(
+    ephemeralKeyPair.privateKey,
+    accept.acceptPublicKey,
+  );
+  const transcriptHash = createTranscriptHash(
+    daemonId,
+    ephemeralKeyPair.publicKey,
+    accept.acceptPublicKey,
+    accept.signature,
+  );
+  const sessionKeys = deriveSessionKeys(sharedSecret, transcriptHash);
+
+  // Best-effort zeroize shared secret
+  zeroize(sharedSecret);
+
+  return {
+    sessionKeys,
+    ephemeralKeyPair,
+  };
+}

package/src/index.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * @sideband/secure-relay
+ *
+ * Sideband Relay Protocol (SBRP) implementation for E2EE communication
+ * between daemons and clients via a relay server.
+ *
+ * Features:
+ * - Ed25519 identity signatures for MITM protection
+ * - X25519 ephemeral key exchange for forward secrecy
+ * - ChaCha20-Poly1305 authenticated encryption
+ * - TOFU (Trust On First Use) identity pinning
+ * - Bitmap-based replay protection
+ *
+ * @example
+ * ```typescript
+ * // Daemon side: generate identity keypair on first run
+ * const identity = generateIdentityKeyPair();
+ *
+ * // Client side: create handshake init
+ * const { message: init, ephemeralKeyPair } = createHandshakeInit();
+ *
+ * // Daemon side: process init and create accept
+ * const { message: accept, result } = processHandshakeInit(init, daemonId, identity);
+ * const clientSession = createClientSession(clientId, result.sessionKeys);
+ *
+ * // Client side: process accept (with TOFU-pinned identity)
+ * const { sessionKeys } = processHandshakeAccept(accept, daemonId, pinnedKey, ephemeralKeyPair);
+ * const daemonSession = createDaemonSession(sessionKeys);
+ *
+ * // Encrypt/decrypt messages
+ * const encrypted = encryptClientToDaemon(daemonSession, plaintext);
+ * const decrypted = decryptClientToDaemon(clientSession, encrypted);
+ * ```
+ */
+
+// Types
+export type {
+  ClientId,
+  DaemonId,
+  EncryptedMessage,
+  EphemeralKeyPair,
+  HandshakeAccept,
+  HandshakeInit,
+  IdentityKeyPair,
+  PinnedIdentity,
+  SessionKeys,
+} from "./types.js";
+
+export {
+  asClientId,
+  asDaemonId,
+  Direction,
+  SbrpError,
+  SbrpErrorCode,
+} from "./types.js";
+
+// Constants
+export {
+  AUTH_TAG_LENGTH,
+  DEFAULT_REPLAY_WINDOW_SIZE,
+  DIRECTION_CLIENT_TO_DAEMON,
+  DIRECTION_DAEMON_TO_CLIENT,
+  ED25519_PRIVATE_KEY_LENGTH,
+  ED25519_PUBLIC_KEY_LENGTH,
+  ED25519_SIGNATURE_LENGTH,
+  NONCE_LENGTH,
+  SBRP_HANDSHAKE_CONTEXT,
+  SBRP_SESSION_KEYS_INFO,
+  SBRP_TRANSCRIPT_CONTEXT,
+  SESSION_KEYS_LENGTH,
+  SYMMETRIC_KEY_LENGTH,
+  X25519_PRIVATE_KEY_LENGTH,
+  X25519_PUBLIC_KEY_LENGTH,
+} from "./constants.js";
+
+// Crypto primitives
+export {
+  computeFingerprint,
+  computeSharedSecret,
+  constructNonce,
+  createSignaturePayload,
+  createTranscriptHash,
+  decrypt,
+  deriveSessionKeys,
+  encrypt,
+  extractSequence,
+  generateEphemeralKeyPair,
+  generateIdentityKeyPair,
+  randomBytes,
+  signPayload,
+  verifySignature,
+  zeroize,
+} from "./crypto.js";
+
+// Handshake
+export type {
+  ClientHandshakeResult,
+  DaemonHandshakeResult,
+} from "./handshake.js";
+
+export {
+  createHandshakeInit,
+  processHandshakeAccept,
+  processHandshakeInit,
+} from "./handshake.js";
+
+// Replay protection
+export type { ReplayWindow } from "./replay.js";
+
+export {
+  checkAndUpdateReplay,
+  createReplayWindow,
+  isValidSequence,
+  resetReplayWindow,
+} from "./replay.js";
+
+// Session management
+export type { ClientSession, DaemonSession } from "./session.js";
+
+export {
+  clearClientSession,
+  clearDaemonSession,
+  createClientSession,
+  createDaemonSession,
+  decryptClientToDaemon,
+  decryptDaemonToClient,
+  encryptClientToDaemon,
+  encryptDaemonToClient,
+} from "./session.js";

package/src/replay.ts

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Bitmap-based replay protection for Sideband Relay Protocol (SBRP).
+ *
+ * Uses a sliding window to track seen sequence numbers and prevent
+ * replay attacks while avoiding memory exhaustion from attacker-controlled
+ * sequence numbers.
+ */
+
+import { DEFAULT_REPLAY_WINDOW_SIZE } from "./constants.js";
+
+/** Replay window state */
+export interface ReplayWindow {
+  /** Highest accepted sequence number */
+  maxSeen: bigint;
+  /** Bitmap: bit i set = sequence (maxSeen - i) was seen */
+  bitmap: bigint;
+  /** Window size in bits */
+  windowSize: bigint;
+}
+
+/**
+ * Create a new replay window.
+ *
+ * @param windowSize - Window size in bits (default: 64)
+ */
+export function createReplayWindow(
+  windowSize: bigint = DEFAULT_REPLAY_WINDOW_SIZE,
+): ReplayWindow {
+  return {
+    maxSeen: -1n, // No messages seen yet
+    bitmap: 0n,
+    windowSize,
+  };
+}
+
+/**
+ * Check if a sequence number is valid (not a replay) and update the window.
+ *
+ * @returns true if the sequence is valid and accepted, false if it's a replay
+ */
+export function checkAndUpdateReplay(
+  seq: bigint,
+  window: ReplayWindow,
+): boolean {
+  // First message ever
+  if (window.maxSeen === -1n) {
+    window.maxSeen = seq;
+    window.bitmap = 1n;
+    return true;
+  }
+
+  if (seq > window.maxSeen) {
+    // New high sequence - shift window
+    const shift = seq - window.maxSeen;
+    if (shift >= window.windowSize) {
+      // Sequence is far ahead, reset bitmap
+      window.bitmap = 1n;
+    } else {
+      window.bitmap = (window.bitmap << shift) | 1n;
+    }
+    window.maxSeen = seq;
+    return true;
+  }
+
+  // Sequence is within or before the window
+  const diff = window.maxSeen - seq;
+  if (diff >= window.windowSize) {
+    // Too old, outside window
+    return false;
+  }
+
+  const mask = 1n << diff;
+  if (window.bitmap & mask) {
+    // Already seen (replay)
+    return false;
+  }
+
+  // Mark as seen
+  window.bitmap |= mask;
+  return true;
+}
+
+/**
+ * Check if a sequence number would be valid without updating the window.
+ *
+ * Useful for pre-validation before decryption.
+ */
+export function isValidSequence(seq: bigint, window: ReplayWindow): boolean {
+  if (window.maxSeen === -1n) {
+    return true;
+  }
+
+  if (seq > window.maxSeen) {
+    return true;
+  }
+
+  const diff = window.maxSeen - seq;
+  if (diff >= window.windowSize) {
+    return false;
+  }
+
+  const mask = 1n << diff;
+  return (window.bitmap & mask) === 0n;
+}
+
+/**
+ * Reset the replay window to initial state.
+ */
+export function resetReplayWindow(window: ReplayWindow): void {
+  window.maxSeen = -1n;
+  window.bitmap = 0n;
+}

package/src/session.ts

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Session management for Sideband Relay Protocol (SBRP).
+ *
+ * Handles encrypted message sending/receiving with proper key selection,
+ * sequence number tracking, and replay protection.
+ */
+
+import { decrypt, encrypt, extractSequence, zeroize } from "./crypto.js";
+import {
+  checkAndUpdateReplay,
+  createReplayWindow,
+  type ReplayWindow,
+} from "./replay.js";
+import type { ClientId, EncryptedMessage, SessionKeys } from "./types.js";
+import { Direction, SbrpError, SbrpErrorCode } from "./types.js";
+
+/** Crypto state for one direction of communication (traffic key, counters, replay) */
+interface ChannelState {
+  trafficKey: Uint8Array;
+  sendSeq: bigint;
+  recvWindow: ReplayWindow;
+}
+
+/** Client session (daemon-side state for each connected client) */
+export interface ClientSession {
+  clientId: ClientId;
+  clientToDaemon: ChannelState;
+  daemonToClient: ChannelState;
+}
+
+/** Daemon session (client-side state for communicating with daemon) */
+export interface DaemonSession {
+  clientToDaemon: ChannelState;
+  daemonToClient: ChannelState;
+}
+
+/**
+ * Create a client session (daemon side).
+ *
+ * Used by daemon to manage state for each connected client.
+ */
+export function createClientSession(
+  clientId: ClientId,
+  sessionKeys: SessionKeys,
+): ClientSession {
+  return {
+    clientId,
+    clientToDaemon: {
+      trafficKey: sessionKeys.clientToDaemon,
+      sendSeq: 0n,
+      recvWindow: createReplayWindow(),
+    },
+    daemonToClient: {
+      trafficKey: sessionKeys.daemonToClient,
+      sendSeq: 0n,
+      recvWindow: createReplayWindow(),
+    },
+  };
+}
+
+/**
+ * Create a daemon session (client side).
+ *
+ * Used by client to communicate with daemon.
+ */
+export function createDaemonSession(sessionKeys: SessionKeys): DaemonSession {
+  return {
+    clientToDaemon: {
+      trafficKey: sessionKeys.clientToDaemon,
+      sendSeq: 0n,
+      recvWindow: createReplayWindow(),
+    },
+    daemonToClient: {
+      trafficKey: sessionKeys.daemonToClient,
+      sendSeq: 0n,
+      recvWindow: createReplayWindow(),
+    },
+  };
+}
+
+/**
+ * Encrypt a message from client to daemon.
+ */
+export function encryptClientToDaemon(
+  session: DaemonSession,
+  plaintext: Uint8Array,
+): EncryptedMessage {
+  const seq = session.clientToDaemon.sendSeq++;
+  const data = encrypt(
+    session.clientToDaemon.trafficKey,
+    Direction.ClientToDaemon,
+    seq,
+    plaintext,
+  );
+
+  return { type: "encrypted", seq, data };
+}
+
+/**
+ * Encrypt a message from daemon to client.
+ */
+export function encryptDaemonToClient(
+  session: ClientSession,
+  plaintext: Uint8Array,
+): EncryptedMessage {
+  const seq = session.daemonToClient.sendSeq++;
+  const data = encrypt(
+    session.daemonToClient.trafficKey,
+    Direction.DaemonToClient,
+    seq,
+    plaintext,
+  );
+
+  return { type: "encrypted", seq, data };
+}
+
+/**
+ * Decrypt a message received by daemon from client.
+ *
+ * @throws {SbrpError} with code SequenceError if replay detected
+ * @throws {SbrpError} with code DecryptFailed if decryption fails
+ */
+export function decryptClientToDaemon(
+  session: ClientSession,
+  message: EncryptedMessage,
+): Uint8Array {
+  // Check replay protection
+  const seq = extractSequence(message.data);
+  if (!checkAndUpdateReplay(seq, session.clientToDaemon.recvWindow)) {
+    throw new SbrpError(
+      SbrpErrorCode.SequenceError,
+      "Sequence number outside valid window or replay detected",
+    );
+  }
+
+  try {
+    return decrypt(session.clientToDaemon.trafficKey, message.data);
+  } catch {
+    throw new SbrpError(
+      SbrpErrorCode.DecryptFailed,
+      "Message decryption failed",
+    );
+  }
+}
+
+/**
+ * Decrypt a message received by client from daemon.
+ *
+ * @throws {SbrpError} with code SequenceError if replay detected
+ * @throws {SbrpError} with code DecryptFailed if decryption fails
+ */
+export function decryptDaemonToClient(
+  session: DaemonSession,
+  message: EncryptedMessage,
+): Uint8Array {
+  // Check replay protection
+  const seq = extractSequence(message.data);
+  if (!checkAndUpdateReplay(seq, session.daemonToClient.recvWindow)) {
+    throw new SbrpError(
+      SbrpErrorCode.SequenceError,
+      "Sequence number outside valid window or replay detected",
+    );
+  }
+
+  try {
+    return decrypt(session.daemonToClient.trafficKey, message.data);
+  } catch {
+    throw new SbrpError(
+      SbrpErrorCode.DecryptFailed,
+      "Message decryption failed",
+    );
+  }
+}
+
+/**
+ * Clear all key material from a client session.
+ *
+ * Best-effort zeroization (JS/GC limitations apply).
+ */
+export function clearClientSession(session: ClientSession): void {
+  zeroize(session.clientToDaemon.trafficKey);
+  zeroize(session.daemonToClient.trafficKey);
+}
+
+/**
+ * Clear all key material from a daemon session.
+ *
+ * Best-effort zeroization (JS/GC limitations apply).
+ */
+export function clearDaemonSession(session: DaemonSession): void {
+  zeroize(session.clientToDaemon.trafficKey);
+  zeroize(session.daemonToClient.trafficKey);
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Type definitions for Sideband Relay Protocol (SBRP).
+ */
+
+/** Branded type for daemon identifiers */
+export type DaemonId = string & { readonly __brand: "DaemonId" };
+
+/** Branded type for client session identifiers (relay-assigned) */
+export type ClientId = string & { readonly __brand: "ClientId" };
+
+/** Ed25519 identity keypair for daemon authentication */
+export interface IdentityKeyPair {
+  publicKey: Uint8Array; // 32 bytes
+  privateKey: Uint8Array; // 32 bytes (seed) or 64 bytes (expanded)
+}
+
+/** X25519 ephemeral keypair for key exchange */
+export interface EphemeralKeyPair {
+  publicKey: Uint8Array; // 32 bytes
+  privateKey: Uint8Array; // 32 bytes
+}
+
+/**
+ * TOFU trust record for daemon identity.
+ * Pinned on first connect, verified on reconnect to detect MITM.
+ * Per-client; not synced via relay.
+ */
+export interface PinnedIdentity {
+  daemonId: DaemonId;
+  identityPublicKey: Uint8Array; // 32 bytes Ed25519 public key
+  firstSeen: Date;
+  lastSeen: Date;
+}
+
+/** Session keys derived from handshake (directional symmetric keys) */
+export interface SessionKeys {
+  /** Key for encrypting client→daemon messages */
+  clientToDaemon: Uint8Array; // 32 bytes
+  /** Key for encrypting daemon→client messages */
+  daemonToClient: Uint8Array; // 32 bytes
+}
+
+/** Handshake init message (client → daemon) */
+export interface HandshakeInit {
+  type: "handshake.init";
+  initPublicKey: Uint8Array; // X25519 ephemeral public key
+}
+
+/** Handshake accept message (daemon → client) */
+export interface HandshakeAccept {
+  type: "handshake.accept";
+  acceptPublicKey: Uint8Array; // X25519 ephemeral public key
+  signature: Uint8Array; // Ed25519 signature
+}
+
+/** Encrypted message envelope */
+export interface EncryptedMessage {
+  type: "encrypted";
+  seq: bigint;
+  data: Uint8Array; // nonce || ciphertext || authTag
+}
+
+/** Direction of message flow (used in nonce construction) */
+export const enum Direction {
+  ClientToDaemon = 1,
+  DaemonToClient = 2,
+}
+
+/** SBRP error codes */
+export const enum SbrpErrorCode {
+  Unauthorized = "unauthorized",
+  DaemonNotFound = "daemon_not_found",
+  DaemonOffline = "daemon_offline",
+  DaemonNotOwned = "daemon_not_owned",
+  IdentityKeyChanged = "identity_key_changed",
+  HandshakeFailed = "handshake_failed",
+  DecryptFailed = "decrypt_failed",
+  SequenceError = "sequence_error",
+  RateLimited = "rate_limited",
+}
+
+/** SBRP-specific error */
+export class SbrpError extends Error {
+  constructor(
+    public readonly code: SbrpErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "SbrpError";
+  }
+}
+
+/** Brand a string as DaemonId (no validation) */
+export function asDaemonId(value: string): DaemonId {
+  return value as DaemonId;
+}
+
+/** Brand a string as ClientId (no validation) */
+export function asClientId(value: string): ClientId {
+  return value as ClientId;
+}