@agentdance/node-webrtc-ice 1.0.0

package/src/candidate.ts

@@ -0,0 +1,175 @@
+import * as crypto from 'node:crypto';
+import type { CandidateType, IceCandidate, TransportProtocol } from './types.js';
+
+// ---------------------------------------------------------------------------
+// RFC 8445 Section 5.1.2.1 – Candidate priority
+// priority = (2^24) * type_pref + (2^8) * local_pref + (256 - component)
+// type_pref: host=126, srflx=100, prflx=110, relay=0
+// ---------------------------------------------------------------------------
+
+const TYPE_PREFERENCES: Record<CandidateType, number> = {
+  host: 126,
+  prflx: 110,
+  srflx: 100,
+  relay: 0,
+};
+
+export function computePriority(
+  type: CandidateType,
+  localPref: number,
+  component: number,
+): number {
+  const typePref = TYPE_PREFERENCES[type];
+  return ((1 << 24) * typePref + (1 << 8) * localPref + (256 - component)) >>> 0;
+}
+
+// ---------------------------------------------------------------------------
+// RFC 8445 Section 5.1.1 – Candidate foundation
+// Foundation is a string that groups candidates that have the same type,
+// base address, protocol and STUN/TURN server.
+// ---------------------------------------------------------------------------
+
+export function computeFoundation(
+  type: CandidateType,
+  baseAddress: string,
+  protocol: TransportProtocol,
+): string {
+  const input = `${type}:${baseAddress}:${protocol}`;
+  return crypto.createHash('md5').update(input).digest('hex').slice(0, 8);
+}
+
+// ---------------------------------------------------------------------------
+// RFC 8445 Section 6.1.2.3 – Candidate pair priority
+// priority = 2^32 * min(G,D) + 2*max(G,D) + (G>D ? 1 : 0)
+// ---------------------------------------------------------------------------
+
+export function computePairPriority(
+  controlling: IceCandidate,
+  controlled: IceCandidate,
+): bigint {
+  const g = BigInt(controlling.priority >>> 0);
+  const d = BigInt(controlled.priority >>> 0);
+  const minVal = g < d ? g : d;
+  const maxVal = g > d ? g : d;
+  const gtFlag = g > d ? 1n : 0n;
+  return (1n << 32n) * minVal + 2n * maxVal + gtFlag;
+}
+
+// ---------------------------------------------------------------------------
+// Parse candidate from SDP attribute value string
+// a=candidate:<foundation> <component> <transport> <priority> <address> <port> typ <type> [...]
+// ---------------------------------------------------------------------------
+
+export function parseCandidateAttribute(value: string): IceCandidate {
+  const parts = value.trim().split(/\s+/);
+
+  if (parts.length < 8) {
+    throw new Error(`Invalid candidate attribute: ${value}`);
+  }
+
+  const foundation = parts[0]!;
+  const component = parseInt(parts[1]!, 10) as 1 | 2;
+  const transport = parts[2]!.toLowerCase() as TransportProtocol;
+  const priority = parseInt(parts[3]!, 10);
+  const address = parts[4]!;
+  const port = parseInt(parts[5]!, 10);
+  // parts[6] should be 'typ'
+  const type = parts[7]! as CandidateType;
+
+  const candidate: IceCandidate = {
+    foundation,
+    component,
+    transport,
+    priority,
+    address,
+    port,
+    type,
+  };
+
+  // Parse optional extension attributes
+  let i = 8;
+  while (i < parts.length - 1) {
+    const key = parts[i]!;
+    const val = parts[i + 1]!;
+    switch (key) {
+      case 'raddr':
+        candidate.relatedAddress = val;
+        break;
+      case 'rport':
+        candidate.relatedPort = parseInt(val, 10);
+        break;
+      case 'tcptype':
+        candidate.tcpType = val as 'active' | 'passive' | 'so';
+        break;
+      case 'generation':
+        candidate.generation = parseInt(val, 10);
+        break;
+      case 'ufrag':
+        candidate.ufrag = val;
+        break;
+      case 'network-id':
+        candidate.networkId = parseInt(val, 10);
+        break;
+    }
+    i += 2;
+  }
+
+  return candidate;
+}
+
+// ---------------------------------------------------------------------------
+// Serialize candidate to SDP attribute value
+// ---------------------------------------------------------------------------
+
+export function serializeCandidateAttribute(candidate: IceCandidate): string {
+  let s =
+    `${candidate.foundation} ${candidate.component} ${candidate.transport} ` +
+    `${candidate.priority} ${candidate.address} ${candidate.port} typ ${candidate.type}`;
+
+  if (candidate.relatedAddress !== undefined) {
+    s += ` raddr ${candidate.relatedAddress}`;
+  }
+  if (candidate.relatedPort !== undefined) {
+    s += ` rport ${candidate.relatedPort}`;
+  }
+  if (candidate.tcpType !== undefined) {
+    s += ` tcptype ${candidate.tcpType}`;
+  }
+  if (candidate.generation !== undefined) {
+    s += ` generation ${candidate.generation}`;
+  }
+  if (candidate.ufrag !== undefined) {
+    s += ` ufrag ${candidate.ufrag}`;
+  }
+  if (candidate.networkId !== undefined) {
+    s += ` network-id ${candidate.networkId}`;
+  }
+
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Generate random ICE ufrag and password
+// ---------------------------------------------------------------------------
+
+const ICE_CHARS =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function randomIceString(length: number): string {
+  const bytes = crypto.randomBytes(length);
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += ICE_CHARS[bytes[i]! % ICE_CHARS.length];
+  }
+  return result;
+}
+
+// 4 chars minimum per RFC 5245 §15.4
+export function generateUfrag(): string {
+  return randomIceString(4);
+}
+
+// 22 chars minimum per RFC 5245 §15.4
+export function generatePassword(): string {
+  return randomIceString(22);
+}

package/src/checklist.ts

@@ -0,0 +1,142 @@
+import type {
+  CandidatePair,
+  IceCandidate,
+  IceRole,
+} from './types.js';
+import { CandidatePairState } from './types.js';
+import { computePairPriority } from './candidate.js';
+
+// ---------------------------------------------------------------------------
+// Pair ID generation
+// ---------------------------------------------------------------------------
+
+export function makePairId(local: IceCandidate, remote: IceCandidate): string {
+  return `${local.foundation}:${local.port}|${remote.foundation}:${remote.port}`;
+}
+
+// ---------------------------------------------------------------------------
+// Form candidate pairs from local × remote candidates (same component)
+// sorted descending by priority
+// ---------------------------------------------------------------------------
+
+export function formCandidatePairs(
+  localCandidates: IceCandidate[],
+  remoteCandidates: IceCandidate[],
+  role: IceRole,
+): CandidatePair[] {
+  const pairs: CandidatePair[] = [];
+
+  for (const local of localCandidates) {
+    for (const remote of remoteCandidates) {
+      if (local.component !== remote.component) continue;
+      // ts-rtc uses UDP-only transport; skip TCP remote candidates
+      if (remote.transport !== 'udp') continue;
+      if (local.transport !== 'udp') continue;
+      // ts-rtc binds a udp4 socket; IPv6 candidates will silently fail — skip them
+      if (remote.address.includes(':')) continue;
+
+      const controlling = role === 'controlling' ? local : remote;
+      const controlled = role === 'controlling' ? remote : local;
+      const priority = computePairPriority(controlling, controlled);
+
+      const pair: CandidatePair = {
+        id: makePairId(local, remote),
+        local,
+        remote,
+        state: CandidatePairState.Frozen,
+        priority,
+        nominated: false,
+        valid: false,
+        nominateOnSuccess: false,
+        retransmitCount: 0,
+      };
+
+      pairs.push(pair);
+    }
+  }
+
+  // Sort by priority descending
+  pairs.sort((a, b) => {
+    if (b.priority > a.priority) return 1;
+    if (b.priority < a.priority) return -1;
+    return 0;
+  });
+
+  return pairs;
+}
+
+// ---------------------------------------------------------------------------
+// Unfreeze the highest priority pair per component (RFC 8445 §6.1.2.6)
+// ---------------------------------------------------------------------------
+
+export function unfreezeInitialPairs(pairs: CandidatePair[]): void {
+  const seenComponents = new Set<number>();
+  for (const pair of pairs) {
+    if (
+      !seenComponents.has(pair.local.component) &&
+      pair.state === CandidatePairState.Frozen
+    ) {
+      pair.state = CandidatePairState.Waiting;
+      seenComponents.add(pair.local.component);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Find pair by address/port tuples
+// ---------------------------------------------------------------------------
+
+export function findPairByAddresses(
+  pairs: CandidatePair[],
+  localAddr: string,
+  localPort: number,
+  remoteAddr: string,
+  remotePort: number,
+): CandidatePair | undefined {
+  return pairs.find(
+    (p) =>
+      p.local.address === localAddr &&
+      p.local.port === localPort &&
+      p.remote.address === remoteAddr &&
+      p.remote.port === remotePort,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Get or create a candidate pair
+// ---------------------------------------------------------------------------
+
+export function getOrCreatePair(
+  pairs: CandidatePair[],
+  local: IceCandidate,
+  remote: IceCandidate,
+  role: IceRole,
+): { pair: CandidatePair; isNew: boolean } {
+  const existing = pairs.find(
+    (p) =>
+      p.local.address === local.address &&
+      p.local.port === local.port &&
+      p.remote.address === remote.address &&
+      p.remote.port === remote.port,
+  );
+  if (existing) return { pair: existing, isNew: false };
+
+  const controlling = role === 'controlling' ? local : remote;
+  const controlled = role === 'controlling' ? remote : local;
+  const priority = computePairPriority(controlling, controlled);
+
+  const pair: CandidatePair = {
+    id: makePairId(local, remote),
+    local,
+    remote,
+    state: CandidatePairState.Waiting,
+    priority,
+    nominated: false,
+    valid: false,
+    nominateOnSuccess: false,
+    retransmitCount: 0,
+  };
+
+  return { pair, isNew: true };
+}
+

package/src/gather.ts

@@ -0,0 +1,224 @@
+import * as os from 'node:os';
+import * as dgram from 'node:dgram';
+import {
+  AttributeType,
+  MessageClass,
+  decodeMessage,
+  encodeMessage,
+  createBindingRequest,
+  isStunMessage,
+  decodeXorMappedAddress,
+} from '@agentdance/node-webrtc-stun';
+import type { StunAttribute } from '@agentdance/node-webrtc-stun';
+import { computeFoundation, computePriority } from './candidate.js';
+import type { IceCandidate, TransportProtocol } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Interface tier classification
+//
+// Mirrors pion/ice's approach (RFC 8421 §4.1 "Interface Type Preferences"):
+//   loopback  → tier 0 (highest localPref base = 65535)
+//   physical  → tier 1 (Ethernet / WiFi)
+//   virtual   → tier 2 (VPN tunnels, Docker bridges, VM adapters)
+//
+// Within each tier, interfaces are assigned descending localPref values so
+// the first enumerated interface of each tier gets the highest priority.
+// localPref for interface i = tierBase - i, where tierBase is spaced 1024
+// apart so tiers never overlap: loopback ≥ 65535, physical 64511..63488,
+// virtual 63487..62464.
+//
+// This ensures:
+//   loopback↔loopback pair > physical↔physical pair > virtual pair
+//   (all host candidates; type_pref=126 is the same for all)
+// ---------------------------------------------------------------------------
+
+const TIER_BASE: Record<0 | 1 | 2, number> = {
+  0: 65535,    // loopback
+  1: 64511,    // physical (Ethernet / WiFi)
+  2: 63487,    // virtual  (VPN, Docker, VM)
+};
+
+// Heuristics for "virtual" interface detection that work across platforms
+// without requiring OS-specific syscalls.
+const VIRTUAL_PREFIXES = [
+  'docker',
+  'br-',      // Docker bridge networks
+  'veth',     // Docker container-side veth
+  'virbr',    // libvirt bridges
+  'vmnet',    // VMware host-only
+  'vboxnet',  // VirtualBox host-only
+  'tun',      // OpenVPN / WireGuard tun
+  'tap',      // tap adapters
+  'utun',     // macOS utun (WireGuard / built-in VPN)
+  'ipsec',
+  'ppp',
+];
+
+// On macOS, en0 is typically WiFi/Ethernet. We treat the generic "en"
+// prefix as physical; everything else that is non-loopback, non-virtual
+// is also treated as physical.
+function classifyInterface(name: string): 0 | 1 | 2 {
+  if (name === 'lo' || name === 'lo0') return 0;
+  for (const prefix of VIRTUAL_PREFIXES) {
+    if (name.startsWith(prefix)) return 2;
+  }
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Local address enumeration (includes loopback, excludes IPv6)
+// ---------------------------------------------------------------------------
+
+export interface LocalAddress {
+  address: string;
+  family: 4 | 6;
+  name: string;
+  tier: 0 | 1 | 2;
+}
+
+export function getLocalAddresses(): LocalAddress[] {
+  const ifaces = os.networkInterfaces();
+  const result: LocalAddress[] = [];
+
+  for (const [name, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      // IPv4 only – ts-rtc binds udp4 sockets
+      if (addr.family !== 'IPv4') continue;
+      const tier = addr.internal ? 0 : classifyInterface(name);
+      result.push({ address: addr.address, family: 4, name, tier });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Gather host candidates from all local interfaces
+//
+// Candidates are sorted by tier (loopback first) and within a tier by
+// enumeration order. localPref is assigned so that loopback always gets the
+// highest value, physical interfaces are in the middle, and virtual/VPN
+// interfaces are lowest – matching pion's RFC 8421 §4.1 intent.
+// ---------------------------------------------------------------------------
+
+export async function gatherHostCandidates(
+  port: number,
+  component: 1 | 2,
+  protocol: TransportProtocol,
+): Promise<IceCandidate[]> {
+  const addrs = getLocalAddresses();
+
+  // Sort: loopback(0) < physical(1) < virtual(2) so localPref decrements
+  // in the right order within each tier.
+  addrs.sort((a, b) => a.tier - b.tier);
+
+  // Track per-tier counter for localPref assignment
+  const tierCount: Record<0 | 1 | 2, number> = { 0: 0, 1: 0, 2: 0 };
+
+  const candidates: IceCandidate[] = [];
+
+  for (const addr of addrs) {
+    const localPref = TIER_BASE[addr.tier] - tierCount[addr.tier];
+    tierCount[addr.tier]++;
+
+    candidates.push({
+      foundation: computeFoundation('host', addr.address, protocol),
+      component,
+      transport: protocol,
+      priority: computePriority('host', localPref, component),
+      address: addr.address,
+      port,
+      type: 'host',
+    });
+  }
+
+  return candidates;
+}
+
+// ---------------------------------------------------------------------------
+// Gather server-reflexive candidate via STUN binding request
+// ---------------------------------------------------------------------------
+
+export async function gatherSrflxCandidate(
+  socket: dgram.Socket,
+  localCandidate: IceCandidate,
+  stunServer: { host: string; port: number },
+): Promise<IceCandidate | null> {
+  return new Promise((resolve) => {
+    const req = createBindingRequest();
+    const buf = encodeMessage(req);
+    const txId = req.transactionId;
+
+    const timeout = setTimeout(() => {
+      socket.removeListener('message', onMessage);
+      resolve(null);
+    }, 3000);
+
+    function onMessage(msg: Buffer, rinfo: dgram.RemoteInfo): void {
+      if (!isStunMessage(msg)) return;
+
+      let decoded;
+      try {
+        decoded = decodeMessage(msg);
+      } catch {
+        return;
+      }
+
+      // Match transaction ID
+      if (!decoded.transactionId.equals(txId)) return;
+      if (decoded.messageClass !== MessageClass.SuccessResponse) return;
+
+      clearTimeout(timeout);
+      socket.removeListener('message', onMessage);
+
+      // Extract XOR-MAPPED-ADDRESS
+      const xorAttr = decoded.attributes.find(
+        (a: StunAttribute) => a.type === AttributeType.XorMappedAddress,
+      );
+      if (!xorAttr) {
+        resolve(null);
+        return;
+      }
+
+      let mapped;
+      try {
+        mapped = decodeXorMappedAddress(xorAttr.value, decoded.transactionId);
+      } catch {
+        resolve(null);
+        return;
+      }
+
+      const foundation = computeFoundation(
+        'srflx',
+        localCandidate.address,
+        localCandidate.transport,
+      );
+      const priority = computePriority('srflx', 65535, localCandidate.component);
+
+      const srflx: IceCandidate = {
+        foundation,
+        component: localCandidate.component,
+        transport: localCandidate.transport,
+        priority,
+        address: mapped.address,
+        port: mapped.port,
+        type: 'srflx',
+        relatedAddress: localCandidate.address,
+        relatedPort: localCandidate.port,
+      };
+
+      resolve(srflx);
+    }
+
+    socket.on('message', onMessage);
+
+    socket.send(buf, stunServer.port, stunServer.host, (err) => {
+      if (err) {
+        clearTimeout(timeout);
+        socket.removeListener('message', onMessage);
+        resolve(null);
+      }
+    });
+  });
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './candidate.js';
+export * from './gather.js';
+export * from './transport.js';
+export * from './checklist.js';
+export * from './agent.js';

package/src/transport.ts

@@ -0,0 +1,88 @@
+import * as dgram from 'node:dgram';
+import { EventEmitter } from 'node:events';
+
+// ---------------------------------------------------------------------------
+// Packet type detection (RFC 7983 / RFC 5764)
+// STUN:  first byte 0x00-0x03
+// DTLS:  first byte 0x14-0x19 (ContentType: change_cipher_spec=20...23=heartbeat)
+// RTP/RTCP: first byte 0x80-0xFF (version 2 flag set)
+// ---------------------------------------------------------------------------
+
+export function detectPacketType(
+  buf: Buffer,
+): 'stun' | 'dtls' | 'rtp' | 'unknown' {
+  if (buf.length === 0) return 'unknown';
+  const b = buf[0]!;
+  if (b <= 0x03) return 'stun';
+  if (b >= 0x14 && b <= 0x19) return 'dtls';
+  if (b >= 0x80) return 'rtp';
+  return 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// UdpTransport – single UDP socket with packet demultiplexing
+// ---------------------------------------------------------------------------
+
+export declare interface UdpTransport {
+  on(event: 'stun', listener: (buf: Buffer, rinfo: dgram.RemoteInfo) => void): this;
+  on(event: 'dtls', listener: (buf: Buffer, rinfo: dgram.RemoteInfo) => void): this;
+  on(event: 'rtp', listener: (buf: Buffer, rinfo: dgram.RemoteInfo) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+}
+
+export class UdpTransport extends EventEmitter {
+  private _socket!: dgram.Socket;
+  private _localPort = 0;
+  private _localAddress = '0.0.0.0';
+
+  get localPort(): number {
+    return this._localPort;
+  }
+
+  get localAddress(): string {
+    return this._localAddress;
+  }
+
+  async bind(port = 0, address = '0.0.0.0'): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const socket = dgram.createSocket('udp4');
+
+      socket.on('error', (err) => {
+        this.emit('error', err);
+      });
+
+      socket.on('message', (buf: Buffer, rinfo: dgram.RemoteInfo) => {
+        const type = detectPacketType(buf);
+        this.emit(type, buf, rinfo);
+      });
+
+      socket.bind(port, address, () => {
+        const addr = socket.address();
+        this._localPort = addr.port;
+        this._localAddress = addr.address;
+        this._socket = socket;
+        resolve();
+      });
+
+      socket.once('error', reject);
+    });
+  }
+
+  send(buf: Buffer, port: number, address: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this._socket.send(buf, port, address, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  close(): void {
+    try {
+      this._socket.close();
+    } catch {
+      // already closed
+    }
+  }
+}