cairn-p2p 0.2.0

package/eslint.config.js

@@ -0,0 +1,24 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+
+export default [
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "cairn-p2p",
+  "version": "0.2.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moukrea/cairn.git",
+    "directory": "packages/ts/cairn-p2p"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@chainsafe/libp2p-noise": "^16.0.0",
+    "@libp2p/circuit-relay-v2": "^2.0.0",
+    "@libp2p/interface": "^2.0.0",
+    "@libp2p/kad-dht": "^13.0.0",
+    "@libp2p/mdns": "^11.0.0",
+    "@libp2p/tcp": "^10.0.0",
+    "@libp2p/webrtc": "^5.0.0",
+    "@libp2p/websockets": "^9.0.0",
+    "@libp2p/webtransport": "^5.0.0",
+    "@libp2p/yamux": "^7.0.0",
+    "@noble/ciphers": "^1.0.0",
+    "@noble/curves": "^1.4.0",
+    "@noble/ed25519": "^2.0.0",
+    "@noble/hashes": "^1.4.0",
+    "@stablelib/chacha20poly1305": "^1.0.0",
+    "cborg": "^4.0.0",
+    "eventemitter3": "^5.0.0",
+    "libp2p": "^2.0.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/uuid": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "js-yaml": "^4.1.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,277 @@
+import { CairnError } from './errors.js';
+import { encode, decode } from 'cborg';
+
+// ---------------------------------------------------------------------------
+// Channel constants
+// ---------------------------------------------------------------------------
+
+/** Prefix for reserved cairn-internal channel names. */
+export const RESERVED_CHANNEL_PREFIX = '__cairn_';
+
+/** Reserved channel name for store-and-forward operations. */
+export const CHANNEL_FORWARD = '__cairn_forward';
+
+/** Message type code for ChannelInit (first message on a new stream). */
+export const CHANNEL_INIT_TYPE = 0x0303;
+
+// ---------------------------------------------------------------------------
+// Channel name validation
+// ---------------------------------------------------------------------------
+
+/** Validate that a channel name is not reserved and not empty. */
+export function validateChannelName(name: string): void {
+  if (!name) {
+    throw new CairnError('PROTOCOL', 'channel name must not be empty');
+  }
+  if (name.startsWith(RESERVED_CHANNEL_PREFIX)) {
+    throw new CairnError(
+      'PROTOCOL',
+      `channel name '${name}' uses reserved prefix '${RESERVED_CHANNEL_PREFIX}'`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Channel lifecycle states
+// ---------------------------------------------------------------------------
+
+/** Channel lifecycle states. */
+export type ChannelState = 'opening' | 'open' | 'rejected' | 'closed';
+
+// ---------------------------------------------------------------------------
+// Channel
+// ---------------------------------------------------------------------------
+
+/** A named channel multiplexed over a yamux stream. */
+export class Channel {
+  readonly name: string;
+  readonly streamId: number;
+  private _state: ChannelState;
+  readonly metadata?: Uint8Array;
+
+  constructor(name: string, streamId: number, metadata?: Uint8Array) {
+    this.name = name;
+    this.streamId = streamId;
+    this._state = 'opening';
+    this.metadata = metadata;
+  }
+
+  /** Current channel state. */
+  get state(): ChannelState {
+    return this._state;
+  }
+
+  /** Check if the channel is open and ready for data flow. */
+  isOpen(): boolean {
+    return this._state === 'open';
+  }
+
+  /** Transition to the Open state (accepted by remote). */
+  accept(): void {
+    if (this._state !== 'opening') {
+      throw new CairnError('PROTOCOL', `cannot accept channel '${this.name}' in state ${this._state}`);
+    }
+    this._state = 'open';
+  }
+
+  /** Transition to the Rejected state. */
+  reject(): void {
+    if (this._state !== 'opening') {
+      throw new CairnError('PROTOCOL', `cannot reject channel '${this.name}' in state ${this._state}`);
+    }
+    this._state = 'rejected';
+  }
+
+  /** Transition to the Closed state. */
+  close(): void {
+    if (this._state === 'closed') {
+      throw new CairnError('PROTOCOL', `channel '${this.name}' is already closed`);
+    }
+    this._state = 'closed';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ChannelInit payload
+// ---------------------------------------------------------------------------
+
+/** The first message sent on a newly opened yamux stream. */
+export interface ChannelInit {
+  channelName: string;
+  metadata?: Uint8Array;
+}
+
+/** Encode a ChannelInit to CBOR bytes. */
+export function encodeChannelInit(init: ChannelInit): Uint8Array {
+  const obj: Record<string, unknown> = { channel_name: init.channelName };
+  if (init.metadata) {
+    obj.metadata = init.metadata;
+  }
+  return encode(obj);
+}
+
+/** Decode a ChannelInit from CBOR bytes. */
+export function decodeChannelInit(data: Uint8Array): ChannelInit {
+  const obj = decode(data) as Record<string, unknown>;
+  const channelName = obj.channel_name as string;
+  if (typeof channelName !== 'string') {
+    throw new CairnError('PROTOCOL', 'ChannelInit missing channel_name');
+  }
+  return {
+    channelName,
+    metadata: obj.metadata instanceof Uint8Array ? obj.metadata : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// DataMessage / DataAck / DataNack
+// ---------------------------------------------------------------------------
+
+/** Application data payload with reliable delivery semantics (0x0300). */
+export interface DataMessage {
+  msgId: Uint8Array;
+  payload: Uint8Array;
+}
+
+/** Create a new DataMessage with a fresh UUID v7 identifier. */
+export function createDataMessage(payload: Uint8Array): DataMessage {
+  const msgId = new Uint8Array(16);
+  crypto.getRandomValues(msgId);
+  // Set version 7 (bits 48-51)
+  msgId[6] = (msgId[6] & 0x0f) | 0x70;
+  // Set variant (bits 64-65)
+  msgId[8] = (msgId[8] & 0x3f) | 0x80;
+  // Embed timestamp in first 48 bits for ordering
+  const now = Date.now();
+  msgId[0] = (now / 2 ** 40) & 0xff;
+  msgId[1] = (now / 2 ** 32) & 0xff;
+  msgId[2] = (now / 2 ** 24) & 0xff;
+  msgId[3] = (now / 2 ** 16) & 0xff;
+  msgId[4] = (now / 2 ** 8) & 0xff;
+  msgId[5] = now & 0xff;
+  return { msgId, payload };
+}
+
+/** Acknowledges successful receipt of a DataMessage (0x0301). */
+export interface DataAck {
+  ackedMsgId: Uint8Array;
+}
+
+/** Negative acknowledgment, requesting retransmission (0x0302). */
+export interface DataNack {
+  nackedMsgId: Uint8Array;
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// ChannelManager
+// ---------------------------------------------------------------------------
+
+/** Events emitted by the channel manager. */
+export type ChannelEvent =
+  | { type: 'opened'; channelName: string; streamId: number; metadata?: Uint8Array }
+  | { type: 'accepted'; streamId: number }
+  | { type: 'rejected'; streamId: number; reason?: string }
+  | { type: 'data'; streamId: number; message: DataMessage }
+  | { type: 'closed'; streamId: number };
+
+export type ChannelEventListener = (event: ChannelEvent) => void;
+
+/** Manages channels within a session. */
+export class ChannelManager {
+  private readonly _channels = new Map<number, Channel>();
+  private readonly _listeners: ChannelEventListener[] = [];
+
+  onEvent(listener: ChannelEventListener): void {
+    this._listeners.push(listener);
+  }
+
+  private emit(event: ChannelEvent): void {
+    for (const listener of this._listeners) {
+      listener(event);
+    }
+  }
+
+  /** Open a new channel on a given stream. Returns the ChannelInit payload. */
+  openChannel(name: string, streamId: number, metadata?: Uint8Array): ChannelInit {
+    validateChannelName(name);
+
+    if (this._channels.has(streamId)) {
+      throw new CairnError('PROTOCOL', `stream ${streamId} already has a channel`);
+    }
+
+    const channel = new Channel(name, streamId, metadata);
+    this._channels.set(streamId, channel);
+
+    return { channelName: name, metadata };
+  }
+
+  /** Handle an incoming ChannelInit from a remote peer. */
+  handleChannelInit(streamId: number, init: ChannelInit): void {
+    if (this._channels.has(streamId)) {
+      throw new CairnError('PROTOCOL', `stream ${streamId} already has a channel`);
+    }
+
+    const channel = new Channel(init.channelName, streamId, init.metadata);
+    this._channels.set(streamId, channel);
+
+    this.emit({
+      type: 'opened',
+      channelName: init.channelName,
+      streamId,
+      metadata: init.metadata,
+    });
+  }
+
+  /** Accept an incoming channel. */
+  acceptChannel(streamId: number): void {
+    const channel = this._channels.get(streamId);
+    if (!channel) {
+      throw new CairnError('PROTOCOL', `no channel on stream ${streamId}`);
+    }
+    channel.accept();
+    this.emit({ type: 'accepted', streamId });
+  }
+
+  /** Reject an incoming channel. */
+  rejectChannel(streamId: number, reason?: string): void {
+    const channel = this._channels.get(streamId);
+    if (!channel) {
+      throw new CairnError('PROTOCOL', `no channel on stream ${streamId}`);
+    }
+    channel.reject();
+    this.emit({ type: 'rejected', streamId, reason });
+  }
+
+  /** Handle incoming data on a channel. */
+  handleData(streamId: number, message: DataMessage): void {
+    const channel = this._channels.get(streamId);
+    if (!channel) {
+      throw new CairnError('PROTOCOL', `no channel on stream ${streamId}`);
+    }
+    if (!channel.isOpen()) {
+      throw new CairnError('PROTOCOL', `channel '${channel.name}' is not open (state: ${channel.state})`);
+    }
+    this.emit({ type: 'data', streamId, message });
+  }
+
+  /** Close a channel. */
+  closeChannel(streamId: number): void {
+    const channel = this._channels.get(streamId);
+    if (!channel) {
+      throw new CairnError('PROTOCOL', `no channel on stream ${streamId}`);
+    }
+    channel.close();
+    this.emit({ type: 'closed', streamId });
+  }
+
+  /** Get a channel by stream ID. */
+  getChannel(streamId: number): Channel | undefined {
+    return this._channels.get(streamId);
+  }
+
+  /** Get the number of tracked channels. */
+  get channelCount(): number {
+    return this._channels.size;
+  }
+}

package/src/config.ts

@@ -0,0 +1,161 @@
+/**
+ * Storage adapter interface for persisting identity, per-peer state, and
+ * per-session state. All values are opaque Uint8Array blobs.
+ */
+export interface StorageAdapter {
+  get(key: string): Promise<Uint8Array | null>;
+  set(key: string, value: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Transport protocol in the fallback chain.
+ */
+export type TransportType = 'quic' | 'tcp' | 'websocket' | 'webtransport' | 'circuit-relay-v2';
+
+/**
+ * Storage backend selection.
+ *
+ * - `'filesystem'` — encrypted at rest with passphrase (Node.js)
+ * - `'memory'` — ephemeral, for testing
+ * - A `StorageAdapter` instance for custom backends (keychains, HSMs, IndexedDB)
+ */
+export type StorageBackend = 'filesystem' | 'memory' | StorageAdapter;
+
+/**
+ * NAT type as detected by STUN probing.
+ */
+export type NatType =
+  | 'open'
+  | 'full_cone'
+  | 'restricted_cone'
+  | 'port_restricted_cone'
+  | 'symmetric'
+  | 'unknown';
+
+/**
+ * Connection state machine states (spec/07 section 2).
+ */
+export type ConnectionState =
+  | 'connected'
+  | 'unstable'
+  | 'disconnected'
+  | 'reconnecting'
+  | 'suspended'
+  | 'reconnected'
+  | 'failed';
+
+/**
+ * Cipher suite for AEAD encryption.
+ */
+export type CipherSuite = 'aes-256-gcm' | 'chacha20-poly1305';
+
+/**
+ * Peer identity — 34-byte multihash (0x12, 0x20, <32-byte SHA-256>).
+ */
+export type PeerId = Uint8Array;
+
+/**
+ * TURN relay server credentials.
+ */
+export interface TurnServerConfig {
+  url: string;
+  username: string;
+  credential: string;
+}
+
+/**
+ * Exponential backoff parameters.
+ */
+export interface BackoffConfig {
+  initialDelay: number;
+  maxDelay: number;
+  factor: number;
+}
+
+/**
+ * Reconnection and timeout policy (spec/11 section 2.2).
+ */
+export interface ReconnectionPolicy {
+  connectTimeout: number;
+  transportTimeout: number;
+  reconnectMaxDuration: number;
+  reconnectBackoff: BackoffConfig;
+  rendezvousPollInterval: number;
+  sessionExpiry: number;
+  pairingPayloadExpiry: number;
+}
+
+/**
+ * Mesh routing settings.
+ */
+export interface MeshSettings {
+  meshEnabled?: boolean;
+  maxHops?: number;
+  relayWilling?: boolean;
+  relayCapacity?: number;
+}
+
+/**
+ * Top-level configuration object.
+ *
+ * Every field is optional — sensible defaults enable zero-config usage (Tier 0).
+ */
+export interface CairnConfig {
+  stunServers?: string[];
+  turnServers?: TurnServerConfig[];
+  signalingServers?: string[];
+  trackerUrls?: string[];
+  bootstrapNodes?: string[];
+  transportPreferences?: TransportType[];
+  reconnectionPolicy?: Partial<ReconnectionPolicy>;
+  meshSettings?: MeshSettings;
+  storageBackend?: StorageBackend;
+}
+
+/**
+ * Default STUN servers (Google, Cloudflare).
+ */
+export const DEFAULT_STUN_SERVERS: readonly string[] = [
+  'stun:stun.l.google.com:19302',
+  'stun:stun1.l.google.com:19302',
+  'stun:stun.cloudflare.com:3478',
+];
+
+/**
+ * Default transport fallback order.
+ */
+export const DEFAULT_TRANSPORT_PREFERENCES: readonly TransportType[] = [
+  'quic',
+  'tcp',
+  'websocket',
+  'webtransport',
+  'circuit-relay-v2',
+];
+
+/**
+ * Default reconnection policy values.
+ */
+export const DEFAULT_RECONNECTION_POLICY: Readonly<ReconnectionPolicy> = {
+  connectTimeout: 30_000,
+  transportTimeout: 10_000,
+  reconnectMaxDuration: 3_600_000,
+  reconnectBackoff: {
+    initialDelay: 1_000,
+    maxDelay: 60_000,
+    factor: 2.0,
+  },
+  rendezvousPollInterval: 30_000,
+  sessionExpiry: 86_400_000,
+  pairingPayloadExpiry: 300_000,
+};
+
+/**
+ * Default mesh settings.
+ */
+export const DEFAULT_MESH_SETTINGS: Readonly<Required<MeshSettings>> = {
+  meshEnabled: false,
+  maxHops: 3,
+  relayWilling: false,
+  relayCapacity: 10,
+};

package/src/crypto/aead.ts

@@ -0,0 +1,80 @@
+import { gcm } from '@noble/ciphers/aes';
+import { ChaCha20Poly1305 } from '@stablelib/chacha20poly1305';
+import { CairnError } from '../errors.js';
+import type { CipherSuite } from '../config.js';
+
+/** Nonce size for both ciphers: 12 bytes. */
+export const NONCE_SIZE = 12;
+/** Key size for both ciphers: 32 bytes. */
+export const KEY_SIZE = 32;
+/** Authentication tag size for both ciphers: 16 bytes. */
+export const TAG_SIZE = 16;
+
+/**
+ * Encrypt plaintext with associated data using the specified cipher.
+ *
+ * Returns ciphertext with appended authentication tag.
+ */
+export function aeadEncrypt(
+  cipher: CipherSuite,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  plaintext: Uint8Array,
+  aad: Uint8Array,
+): Uint8Array {
+  if (key.length !== KEY_SIZE) {
+    throw new CairnError('CRYPTO', `AEAD key must be ${KEY_SIZE} bytes, got ${key.length}`);
+  }
+  if (nonce.length !== NONCE_SIZE) {
+    throw new CairnError('CRYPTO', `AEAD nonce must be ${NONCE_SIZE} bytes, got ${nonce.length}`);
+  }
+
+  try {
+    if (cipher === 'aes-256-gcm') {
+      const aes = gcm(key, nonce, aad);
+      return aes.encrypt(plaintext);
+    } else {
+      const chacha = new ChaCha20Poly1305(key);
+      return chacha.seal(nonce, plaintext, aad);
+    }
+  } catch (e) {
+    throw new CairnError('CRYPTO', `AEAD encrypt error: ${e}`);
+  }
+}
+
+/**
+ * Decrypt ciphertext with associated data using the specified cipher.
+ *
+ * Returns plaintext on success. Throws CairnError if authentication fails.
+ */
+export function aeadDecrypt(
+  cipher: CipherSuite,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  ciphertext: Uint8Array,
+  aad: Uint8Array,
+): Uint8Array {
+  if (key.length !== KEY_SIZE) {
+    throw new CairnError('CRYPTO', `AEAD key must be ${KEY_SIZE} bytes, got ${key.length}`);
+  }
+  if (nonce.length !== NONCE_SIZE) {
+    throw new CairnError('CRYPTO', `AEAD nonce must be ${NONCE_SIZE} bytes, got ${nonce.length}`);
+  }
+
+  try {
+    if (cipher === 'aes-256-gcm') {
+      const aes = gcm(key, nonce, aad);
+      return aes.decrypt(ciphertext);
+    } else {
+      const chacha = new ChaCha20Poly1305(key);
+      const result = chacha.open(nonce, ciphertext, aad);
+      if (result === null) {
+        throw new CairnError('CRYPTO', 'ChaCha20-Poly1305 authentication failed');
+      }
+      return result;
+    }
+  } catch (e) {
+    if (e instanceof CairnError) throw e;
+    throw new CairnError('CRYPTO', `AEAD decrypt error: ${e}`);
+  }
+}