cairn-p2p 0.2.0

package/src/errors.ts

@@ -0,0 +1,166 @@
+/**
+ * Recommended recovery action for a given error.
+ */
+export enum ErrorBehavior {
+  Retry = 'retry',
+  Reconnect = 'reconnect',
+  Abort = 'abort',
+  ReGenerate = 'regenerate',
+  Wait = 'wait',
+  Inform = 'inform',
+}
+
+/**
+ * Base error class for all cairn errors.
+ *
+ * Every error carries a machine-readable `code` and optional structured
+ * `details` for diagnostic context.
+ */
+export class CairnError extends Error {
+  readonly code: string;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: string, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = 'CairnError';
+    this.code = code;
+    this.details = details;
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Abort;
+  }
+}
+
+/**
+ * All transports in the fallback chain failed.
+ *
+ * Details include per-transport failures and suggestions (e.g., deploy a
+ * signaling server and/or TURN relay).
+ */
+export class TransportExhaustedError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('TRANSPORT_EXHAUSTED', message, {
+      suggestion: 'deploy the cairn signaling server and/or TURN relay',
+      ...details,
+    });
+    this.name = 'TransportExhaustedError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Retry;
+  }
+}
+
+/**
+ * Session exceeded the expiry window.
+ *
+ * Re-establishment via Noise XX handshake is needed; no re-pairing required.
+ */
+export class SessionExpiredError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('SESSION_EXPIRED', message, details);
+    this.name = 'SessionExpiredError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Reconnect;
+  }
+}
+
+/**
+ * Peer not found at any rendezvous point within timeout.
+ */
+export class PeerUnreachableError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('PEER_UNREACHABLE', message, details);
+    this.name = 'PeerUnreachableError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Wait;
+  }
+}
+
+/**
+ * Session resumption crypto verification failed.
+ *
+ * Possible key compromise — reject connection and alert application.
+ */
+export class AuthenticationFailedError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('AUTHENTICATION_FAILED', message, details);
+    this.name = 'AuthenticationFailedError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Abort;
+  }
+}
+
+/**
+ * Remote peer rejected pairing request.
+ */
+export class PairingRejectedError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('PAIRING_REJECTED', message, details);
+    this.name = 'PairingRejectedError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Inform;
+  }
+}
+
+/**
+ * Pairing payload (pin, QR, link) has expired.
+ *
+ * Generate a new payload to retry.
+ */
+export class PairingExpiredError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('PAIRING_EXPIRED', message, details);
+    this.name = 'PairingExpiredError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.ReGenerate;
+  }
+}
+
+/**
+ * No route to destination through mesh network.
+ */
+export class MeshRouteNotFoundError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('MESH_ROUTE_NOT_FOUND', message, {
+      suggestion: 'try a direct connection or wait for mesh route discovery',
+      ...details,
+    });
+    this.name = 'MeshRouteNotFoundError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Wait;
+  }
+}
+
+/**
+ * No common protocol version between peers.
+ *
+ * Details include the peer's supported version range so the application
+ * can inform the user which peer needs updating.
+ */
+export class VersionMismatchError extends CairnError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('VERSION_MISMATCH', message, {
+      suggestion: 'peer needs to update to a compatible cairn version',
+      ...details,
+    });
+    this.name = 'VersionMismatchError';
+  }
+
+  errorBehavior(): ErrorBehavior {
+    return ErrorBehavior.Abort;
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// Public API exports
+
+// Node
+export { Node, NodeSession, NodeChannel } from './node.js';
+export type {
+  NodeEvents,
+  SessionEvents,
+  QrPairingData,
+  PinPairingData,
+  LinkPairingData,
+  ResolvedConfig,
+} from './node.js';
+
+// Configuration types
+export type {
+  CairnConfig,
+  TurnServerConfig,
+  BackoffConfig,
+  ReconnectionPolicy,
+  MeshSettings,
+  StorageAdapter,
+  StorageBackend,
+  TransportType,
+  NatType,
+  ConnectionState,
+  CipherSuite,
+  PeerId,
+} from './config.js';
+
+export {
+  DEFAULT_STUN_SERVERS,
+  DEFAULT_TRANSPORT_PREFERENCES,
+  DEFAULT_RECONNECTION_POLICY,
+  DEFAULT_MESH_SETTINGS,
+} from './config.js';
+
+// Error types
+export {
+  ErrorBehavior,
+  CairnError,
+  TransportExhaustedError,
+  SessionExpiredError,
+  PeerUnreachableError,
+  AuthenticationFailedError,
+  PairingRejectedError,
+  PairingExpiredError,
+  MeshRouteNotFoundError,
+  VersionMismatchError,
+} from './errors.js';
+
+// Session state machine
+export { SessionStateMachine, isValidTransition } from './session/index.js';
+export type { StateChangedEvent, StateChangedListener } from './session/index.js';
+
+// Server
+export type { ServerConfig } from './server/index.js';
+export { defaultServerConfig } from './server/index.js';

package/src/mesh/index.ts

@@ -0,0 +1,48 @@
+// Mesh module — routing, relay, multi-hop networking
+
+/** Mesh networking configuration (spec 9.4). */
+export interface MeshConfig {
+  /** Enable/disable mesh routing. Default: false. */
+  meshEnabled: boolean;
+  /** Maximum relay hops allowed for any route. Default: 3. */
+  maxHops: number;
+  /** Whether this peer is willing to relay traffic for others. Default: false. */
+  relayWilling: boolean;
+  /** Maximum simultaneous relay connections this peer will serve. Default: 10. */
+  relayCapacity: number;
+}
+
+/** Default mesh config: disabled, 3 max hops, not willing, capacity 10. */
+export function defaultMeshConfig(): MeshConfig {
+  return {
+    meshEnabled: false,
+    maxHops: 3,
+    relayWilling: false,
+    relayCapacity: 10,
+  };
+}
+
+/** Server-mode mesh config: enabled, willing, capacity 100. */
+export function serverMeshConfig(): MeshConfig {
+  return {
+    meshEnabled: true,
+    maxHops: 3,
+    relayWilling: true,
+    relayCapacity: 100,
+  };
+}
+
+export type {
+  Route,
+  ReachabilityEntry,
+  MeshTopologyUpdate,
+} from './routing-table.js';
+export {
+  RoutingTable,
+  directRoute,
+  relayedRoute,
+  hopCount,
+} from './routing-table.js';
+
+export type { RelaySessionId, RelaySession } from './relay.js';
+export { RelayManager } from './relay.js';

package/src/mesh/relay.ts

@@ -0,0 +1,100 @@
+// Mesh relay forwarding (spec/09 section 9.3)
+//
+// Handles forwarding opaque encrypted bytes between peers. Relay peers
+// cannot read, modify, or forge relayed content.
+
+import { CairnError } from '../errors.js';
+import type { MeshConfig } from './index.js';
+
+/** Unique identifier for a relay session. */
+export type RelaySessionId = number;
+
+/** A relay session bridging two peers through this node. */
+export interface RelaySession {
+  /** The unique session identifier. */
+  id: RelaySessionId;
+  /** The source peer ID (hex, requesting the relay). */
+  source: string;
+  /** The destination peer ID (hex, being relayed to). */
+  destination: string;
+}
+
+/**
+ * Manages relay sessions for this peer.
+ *
+ * Enforces relayWilling and relayCapacity from MeshConfig.
+ * Each relay session bridges two streams, forwarding opaque bytes.
+ */
+export class RelayManager {
+  private _config: MeshConfig;
+  private readonly _sessions = new Map<RelaySessionId, RelaySession>();
+  private _nextSessionId = 1;
+
+  constructor(config: MeshConfig) {
+    this._config = { ...config };
+  }
+
+  /**
+   * Request to start a new relay session.
+   *
+   * Validates that this peer is willing to relay, has capacity,
+   * and the destination is not the source.
+   */
+  requestRelay(source: string, destination: string): RelaySessionId {
+    if (!this._config.meshEnabled) {
+      throw new CairnError('MESH_DISABLED', 'mesh routing disabled');
+    }
+
+    if (!this._config.relayWilling) {
+      throw new CairnError('RELAY_NOT_WILLING', 'relay not willing');
+    }
+
+    if (this._sessions.size >= this._config.relayCapacity) {
+      throw new CairnError(
+        'RELAY_CAPACITY_FULL',
+        `relay capacity full (${this._sessions.size}/${this._config.relayCapacity})`,
+      );
+    }
+
+    if (source === destination) {
+      throw new CairnError(
+        'RELAY_CONNECTION_FAILED',
+        'source and destination are the same peer',
+      );
+    }
+
+    const id = this._nextSessionId++;
+    this._sessions.set(id, { id, source, destination });
+    return id;
+  }
+
+  /** Close a relay session. Returns true if the session existed. */
+  closeSession(sessionId: RelaySessionId): boolean {
+    return this._sessions.delete(sessionId);
+  }
+
+  /** Get the number of active relay sessions. */
+  get activeSessionCount(): number {
+    return this._sessions.size;
+  }
+
+  /** Get a relay session by ID. */
+  getSession(sessionId: RelaySessionId): RelaySession | undefined {
+    return this._sessions.get(sessionId);
+  }
+
+  /** Get the remaining relay capacity. */
+  get remainingCapacity(): number {
+    return Math.max(0, this._config.relayCapacity - this._sessions.size);
+  }
+
+  /** Check whether this peer is willing to relay. */
+  get isWilling(): boolean {
+    return this._config.relayWilling;
+  }
+
+  /** Update the mesh configuration. */
+  updateConfig(config: MeshConfig): void {
+    this._config = { ...config };
+  }
+}

package/src/mesh/routing-table.ts

@@ -0,0 +1,196 @@
+// Mesh routing table and route selection (spec/09 section 9.2)
+
+import { CairnError, MeshRouteNotFoundError } from '../errors.js';
+
+/** A route to a destination peer, potentially through intermediate relay hops. */
+export interface Route {
+  /** Ordered list of intermediate relay peer IDs (hex). Empty means direct. */
+  hops: string[];
+  /** Measured or estimated latency in milliseconds. */
+  latencyMs: number;
+  /** Estimated available bandwidth in bytes/sec. */
+  bandwidthBps: number;
+  /** When this route was last confirmed reachable (unix ms). */
+  lastSeen: number;
+}
+
+/** Create a direct route (zero hops). */
+export function directRoute(latencyMs: number, bandwidthBps: number): Route {
+  return { hops: [], latencyMs, bandwidthBps, lastSeen: Date.now() };
+}
+
+/** Create a relayed route through intermediate hops. */
+export function relayedRoute(hops: string[], latencyMs: number, bandwidthBps: number): Route {
+  return { hops: [...hops], latencyMs, bandwidthBps, lastSeen: Date.now() };
+}
+
+/** Get the hop count for a route. */
+export function hopCount(route: Route): number {
+  return route.hops.length;
+}
+
+/** A single reachability entry in a topology update. */
+export interface ReachabilityEntry {
+  /** The reachable peer (hex peer ID). */
+  peerId: string;
+  /** Intermediate hops to reach this peer from the sender (empty = direct). */
+  viaHops: string[];
+  /** Estimated latency in milliseconds. */
+  latencyMs: number;
+  /** Estimated bandwidth in bytes/sec. */
+  bandwidthBps: number;
+}
+
+/** A topology update message exchanged between mesh peers (distance-vector). */
+export interface MeshTopologyUpdate {
+  /** Peers reachable from the sender. */
+  reachablePeers: ReachabilityEntry[];
+}
+
+/**
+ * Route selection comparison.
+ *
+ * Priority: shortest hops -> lowest latency -> highest bandwidth.
+ * Returns negative if a is better, positive if b is better, 0 if equal.
+ */
+function compareRoutes(a: Route, b: Route): number {
+  const hopDiff = hopCount(a) - hopCount(b);
+  if (hopDiff !== 0) return hopDiff;
+
+  const latDiff = a.latencyMs - b.latencyMs;
+  if (latDiff !== 0) return latDiff;
+
+  // Higher bandwidth is better, so reverse comparison
+  return b.bandwidthBps - a.bandwidthBps;
+}
+
+/**
+ * Routing table maintaining known peers and their reachability.
+ */
+export class RoutingTable {
+  private readonly _routes = new Map<string, Route[]>();
+  private readonly _maxHops: number;
+
+  constructor(maxHops: number) {
+    this._maxHops = maxHops;
+  }
+
+  /** Get the max hops limit. */
+  get maxHops(): number {
+    return this._maxHops;
+  }
+
+  /**
+   * Add or update a route to a destination peer.
+   * Routes exceeding maxHops are rejected.
+   */
+  addRoute(destination: string, route: Route): void {
+    const hops = hopCount(route);
+    if (hops > this._maxHops) {
+      throw new CairnError(
+        'MESH_MAX_HOPS_EXCEEDED',
+        `max hops exceeded: ${hops} > ${this._maxHops}`,
+      );
+    }
+
+    const existing = this._routes.get(destination);
+    if (existing) {
+      existing.push(route);
+    } else {
+      this._routes.set(destination, [route]);
+    }
+  }
+
+  /**
+   * Select the best route to a destination peer.
+   *
+   * Priority order per spec 9.2:
+   * 1. Shortest hop count
+   * 2. Lowest latency
+   * 3. Highest bandwidth
+   */
+  selectBestRoute(destination: string): Route {
+    const routes = this._routes.get(destination);
+    if (!routes || routes.length === 0) {
+      throw new MeshRouteNotFoundError(`no route to peer ${destination}`);
+    }
+
+    let best = routes[0];
+    for (let i = 1; i < routes.length; i++) {
+      if (compareRoutes(routes[i], best) < 0) {
+        best = routes[i];
+      }
+    }
+    return best;
+  }
+
+  /** Get all known routes to a destination peer. */
+  getRoutes(destination: string): Route[] | undefined {
+    return this._routes.get(destination);
+  }
+
+  /** Remove all routes to a destination peer. */
+  removeRoutes(destination: string): void {
+    this._routes.delete(destination);
+  }
+
+  /** Remove stale routes older than the given age (ms). */
+  expireRoutes(maxAgeMs: number): void {
+    const cutoff = Date.now() - maxAgeMs;
+    for (const [dest, routes] of this._routes) {
+      const fresh = routes.filter((r) => r.lastSeen >= cutoff);
+      if (fresh.length === 0) {
+        this._routes.delete(dest);
+      } else {
+        this._routes.set(dest, fresh);
+      }
+    }
+  }
+
+  /** Get the number of known destination peers. */
+  get peerCount(): number {
+    return this._routes.size;
+  }
+
+  /** Get the total number of routes across all destinations. */
+  get routeCount(): number {
+    let count = 0;
+    for (const routes of this._routes.values()) {
+      count += routes.length;
+    }
+    return count;
+  }
+
+  /** Get all known destination peer IDs. */
+  get destinations(): string[] {
+    return [...this._routes.keys()];
+  }
+
+  /**
+   * Apply a topology update from a neighboring peer.
+   *
+   * Merges the neighbor's reachability information, adding the neighbor
+   * as an additional hop to each advertised destination.
+   * Returns the number of routes successfully added.
+   */
+  applyTopologyUpdate(neighbor: string, update: MeshTopologyUpdate): number {
+    let added = 0;
+    for (const entry of update.reachablePeers) {
+      const hops = [neighbor, ...entry.viaHops];
+      const route: Route = {
+        hops,
+        latencyMs: entry.latencyMs,
+        bandwidthBps: entry.bandwidthBps,
+        lastSeen: Date.now(),
+      };
+
+      try {
+        this.addRoute(entry.peerId, route);
+        added++;
+      } catch {
+        // Skip routes exceeding max hops
+      }
+    }
+    return added;
+  }
+}