freehop 0.1.0-alpha.0

package/src/client/tracker-client.mjs

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// A WebTorrent (BitTorrent-over-WebSocket) tracker used as a gate, so a room can run on
+// public infrastructure that already exists. Trackers relay opaque WebRTC offers/answers
+// between peers of a swarm; Freehop places its sealed envelopes in those fields:
+//   offer  = "pl1:<peer id>:<sealed hello>"   (announced, delivered to random swarm members)
+//   answer = "pl1:<peer id>:<sealed envelope>" (addressed to one peer via to_peer_id)
+// The swarm's info_hash is derived from the room tag, so only room members can find it, and
+// every envelope is authenticated by the room key before it is trusted.
+import { Emitter } from './gate-client.mjs';
+import { fromBase64Url } from './crypto.mjs';
+
+const PREFIX = 'pl1:';
+const PEER_ID = /^[A-Za-z0-9_-]{22}$/;
+// Trackers treat info_hash/peer_id as 20-byte strings. ASCII-only values avoid tracker
+// implementations that mishandle raw bytes in JSON text frames.
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const random20 = () => [...globalThis.crypto.getRandomValues(new Uint8Array(20))].map(b => ALPHABET[b % 62]).join('');
+const hex = bytes => [...bytes].map(b => b.toString(16).padStart(2, '0')).join('');
+
+export class TrackerClient extends Emitter {
+  constructor(url, { room, peer, hello, needsIntroduction = () => false, bootstrapMs = [8000, 24000],
+    WebSocketImpl = globalThis.WebSocket, announceMs = 30000, offers = 6,
+    backoffMs = [1000, 2000, 5000, 10000, 30000, 60000] } = {}) {
+    super();
+    Object.assign(this, { url, room, peer, hello, needsIntroduction, bootstrapMs, WebSocketImpl, announceMs, offers, backoffMs });
+    this.infoHash = hex(fromBase64Url(room)).slice(0, 20);
+    this.trackerPeerId = random20();
+    this.trackerIds = new Map();   // peerlane id -> tracker peer_id (binary string)
+    this.state = 'idle'; this.closed = false; this.ws = null; this.attempt = 0; this.stun = []; this.started = false;
+    this.counters = { sent: 0, received: 0, bytesOut: 0, bytesIn: 0, errors: 0, connects: 0, announces: 0 };
+  }
+  connect() {
+    if (this.closed || this.ws) return;
+    this.state = 'connecting';
+    let ws;
+    try { ws = new this.WebSocketImpl(this.url); } catch { this.#retry(); return; }
+    this.ws = ws;
+    ws.onopen = () => {
+      if (ws !== this.ws) return;
+      this.state = 'joined'; this.attempt = 0; this.counters.connects++; this.started = false;
+      this.emit('joined', { gate: this, peers: [], stun: [] });
+      this.announce();
+      clearInterval(this.timer);
+      this.timer = setInterval(() => this.announce(), this.announceMs);
+      // Trackers commonly request a 120 s interval. A missed first offer would leave a
+      // new meeting empty that long, so make two bounded introduction retries.
+      this.bootstrapTimers = this.bootstrapMs.map(ms => setTimeout(() => {
+        if (this.state === 'joined' && this.needsIntroduction()) this.announce();
+      }, ms));
+    };
+    ws.onmessage = event => {
+      if (ws !== this.ws || typeof event.data !== 'string' || event.data.length > 200000) return;
+      this.counters.bytesIn += event.data.length;
+      let m; try { m = JSON.parse(event.data); } catch { return; }
+      this.#handle(m);
+    };
+    ws.onclose = () => {
+      if (ws !== this.ws) return;
+      this.ws = null; clearInterval(this.timer);
+      for (const timer of this.bootstrapTimers ?? []) clearTimeout(timer);
+      this.bootstrapTimers = [];
+      const was = this.state; this.state = 'idle';
+      if (was === 'joined') this.emit('left', { gate: this });
+      this.#retry();
+    };
+    ws.onerror = () => { this.counters.errors++; };
+  }
+  #retry() {
+    if (this.closed) return;
+    const delay = this.backoffMs[Math.min(this.attempt++, this.backoffMs.length - 1)];
+    this.retryTimer = setTimeout(() => { this.retryTimer = null; this.connect(); }, delay * (0.75 + Math.random() / 2));
+  }
+  #raw(message) {
+    if (this.ws?.readyState !== 1) return false;
+    const text = JSON.stringify(message);
+    this.ws.send(text); this.counters.bytesOut += text.length;
+    return true;
+  }
+  async announce() {
+    if (this.state !== 'joined') return;
+    const offers = [];
+    for (let i = 0; i < this.offers; i++) offers.push({ offer_id: random20(), offer: { type: 'offer', sdp: PREFIX + this.peer + ':' + await this.hello() } });
+    this.#raw({ action: 'announce', info_hash: this.infoHash, peer_id: this.trackerPeerId, numwant: this.offers,
+      uploaded: 0, downloaded: 0, left: 1, ...(this.started ? {} : { event: 'started' }), offers });
+    this.started = true; this.counters.announces++;
+  }
+  #handle(m) {
+    if (m?.action !== 'announce' || m.info_hash !== this.infoHash) return;
+    if (Number.isFinite(m.interval) && m.interval * 1000 > this.announceMs && m.interval < 3600) {
+      this.announceMs = m.interval * 1000; clearInterval(this.timer); this.timer = setInterval(() => this.announce(), this.announceMs);
+    }
+    const payload = m.offer?.sdp ?? m.answer?.sdp;
+    if (typeof payload !== 'string' || !payload.startsWith(PREFIX) || typeof m.peer_id !== 'string' || m.peer_id === this.trackerPeerId) return;
+    const rest = payload.slice(PREFIX.length), split = rest.indexOf(':');
+    const from = rest.slice(0, split), box = rest.slice(split + 1);
+    if (box.length > 49152 || split !== 22 || !PEER_ID.test(from) || from === this.peer || !/^[A-Za-z0-9_-]+$/.test(box)) return;
+    // The tracker address is remembered only once the room authenticated this sender (bind()),
+    // so a swarm member cannot redirect envelopes by impersonating a peer id.
+    this.counters.received++;
+    if (m.offer) this.emit('hello', { gate: this, from, box, route: m.peer_id });
+    else this.emit('recv', { gate: this, from, box, route: m.peer_id });
+  }
+  bind(peer, route) {
+    if (typeof route !== 'string' || route.length !== 20) return;
+    if (!this.trackerIds.has(peer) && this.trackerIds.size >= 64) this.trackerIds.delete(this.trackerIds.keys().next().value);
+    this.trackerIds.set(peer, route);
+  }
+  send(to, box) {
+    const target = this.trackerIds.get(to);
+    if (this.state !== 'joined' || !target) return false;
+    const ok = this.#raw({ action: 'announce', info_hash: this.infoHash, peer_id: this.trackerPeerId, to_peer_id: target,
+      answer: { type: 'answer', sdp: PREFIX + this.peer + ':' + box }, offer_id: random20() });
+    if (ok) this.counters.sent++;
+    return ok;
+  }
+  close() {
+    this.closed = true; clearInterval(this.timer); clearTimeout(this.retryTimer);
+    for (const timer of this.bootstrapTimers ?? []) clearTimeout(timer);
+    this.bootstrapTimers = [];
+    const ws = this.ws; this.ws = null; this.state = 'closed';
+    if (ws) { try { if (ws.readyState === 1) ws.send(JSON.stringify({ action: 'announce', info_hash: this.infoHash, peer_id: this.trackerPeerId, event: 'stopped', numwant: 0, uploaded: 0, downloaded: 0, left: 1 })); ws.close(1000); } catch {} }
+  }
+}

package/src/electron/main.mjs

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// Electron main-process helper: runs the participant's gateway (TURN + router port mapping) and
+// exposes it to the app's renderer through IPC. Pair it with preload.cjs. The gateway starts
+// lazily, the first time a renderer asks for it, so participants who never use voice pay nothing.
+//
+//   import { installFreehopGateway } from 'freehop/electron';
+//   const peerlane = installFreehopGateway({ ipcMain, allowedOrigins: ['https://play.example.com'] });
+//   app.on('will-quit', () => peerlane.close());
+//   new BrowserWindow({ webPreferences: { preload: preloadPath,
+//     additionalArguments: ['--freehop-origins=https://play.example.com'] } });
+import { startGateway } from '../relay/agent.mjs';
+
+const TAG = /^[A-Za-z0-9_-]{8,64}$/, PEER = /^[A-Za-z0-9_-]{22}$/;
+
+export function installFreehopGateway({ ipcMain, allowedOrigins, options = {}, log = () => {} }) {
+  if (!Array.isArray(allowedOrigins) || !allowedOrigins.length || !allowedOrigins.every(origin => {
+    try { const url = new URL(origin); return (url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) && url.origin === origin; }
+    catch { return false; }
+  })) throw new TypeError('Specify allowedOrigins as exact HTTPS origins (HTTP is allowed only on loopback) for the gateway renderer.');
+  const origins = new Set(allowedOrigins);
+  // Validate at the privileged boundary too: a preload check alone cannot authorize IPC.
+  const trusted = event => {
+    try { return !closed && event.senderFrame === event.sender.mainFrame && origins.has(new URL(event.senderFrame.url).origin); }
+    catch { return false; }
+  };
+  const grants = new WeakMap();
+  // A window's rooms are released on the gateway when its page navigates away, its origin
+  // changes or the window is destroyed: a page that never called leave() leaves nothing behind.
+  const releaseAll = grant => { if (!grant) return; for (const tag of grant.tags) gateway?.revokeRoom(tag); grant.tags.clear(); };
+  const watched = new WeakSet();
+  const watch = sender => {
+    if (watched.has(sender) || typeof sender?.on !== 'function') return;
+    watched.add(sender);
+    sender.on('did-navigate', () => releaseAll(grants.get(sender)));   // main-frame navigations only (not in-page)
+    sender.once?.('destroyed', () => { releaseAll(grants.get(sender)); grants.delete(sender); });
+  };
+  const roomsFor = event => {
+    const origin = new URL(event.senderFrame.url).origin;
+    let grant = grants.get(event.sender);
+    if (!grant || grant.origin !== origin) { releaseAll(grant); grant = {origin, tags: new Set()}; grants.set(event.sender, grant); watch(event.sender); }
+    return grant.tags;
+  };
+  let gateway = null, starting = null, closed = false;
+  const ensure = () => {
+    if (closed) return Promise.reject(new Error('closed'));
+    if (gateway) return Promise.resolve(gateway);
+    starting ??= startGateway({ ...options, log }).then(g => (gateway = g)).catch(error => { starting = null; throw error; });
+    return starting;
+  };
+  ipcMain.handle('freehop:gateway-info', async event => { if (!trusted(event)) return null; try { const g = await ensure(); return trusted(event) ? g.info() : null; } catch (error) { log('gateway-unavailable', { message: error.message }); return null; } });
+  ipcMain.handle('freehop:allow-room', async (event, tag) => { if (trusted(event) && typeof tag === 'string' && TAG.test(tag)) { const origin = new URL(event.senderFrame.url).origin; const g = await ensure(); if (trusted(event) && new URL(event.senderFrame.url).origin === origin) { const rooms = roomsFor(event); if (rooms.size >= 64 && !rooms.has(tag)) return; g.allowRoom(tag); rooms.add(tag); } } });
+  ipcMain.handle('freehop:credentials', async (event, tag, peer) => {
+    if (!trusted(event) || typeof tag !== 'string' || !TAG.test(tag) || typeof peer !== 'string' || !(peer === 'self' || PEER.test(peer)) || !roomsFor(event).has(tag)) return null;
+    const g = await ensure();
+    return trusted(event) && roomsFor(event).has(tag) ? g.credentialsFor(tag, peer) : null;
+  });
+  ipcMain.handle('freehop:revoke-peer', async (event, tag, peer) => {
+    if (trusted(event) && gateway && typeof tag === 'string' && TAG.test(tag) && roomsFor(event).has(tag) && typeof peer === 'string' && PEER.test(peer)) gateway.revokePeer(tag, peer);
+  });
+  ipcMain.handle('freehop:revoke-room', async (event, tag) => { if (trusted(event) && gateway && typeof tag === 'string' && TAG.test(tag) && roomsFor(event).has(tag)) { gateway.revokeRoom(tag); roomsFor(event).delete(tag); } });
+  return {
+    get gateway() { return gateway; },
+    async close() {
+      closed = true;
+      for (const channel of ['freehop:gateway-info', 'freehop:credentials', 'freehop:allow-room', 'freehop:revoke-peer', 'freehop:revoke-room']) ipcMain.removeHandler(channel);
+      const g = gateway ?? await starting?.catch(() => null);
+      await g?.close();
+    }
+  };
+}

package/src/electron/preload.cjs

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// Electron preload: exposes window.freehopGateway to the app's own pages only. The main
+// process passes the allowed origins as --freehop-origins=<origin>[,<origin>...]; any other
+// page (e.g. a link opened inside the window) never sees the gateway. Its signing secret stays in the main process.
+const { contextBridge, ipcRenderer } = require('electron');
+
+const arg = process.argv.find(a => a.startsWith('--freehop-origins='));
+const allowed = new Set((arg ? arg.slice('--freehop-origins='.length) : '').split(',').map(s => s.trim()).filter(Boolean));
+if (allowed.has(globalThis.location?.origin)) {
+  contextBridge.exposeInMainWorld('freehopGateway', Object.freeze({
+    info: () => ipcRenderer.invoke('freehop:gateway-info'),
+    credentialsFor: (tag, peer) => ipcRenderer.invoke('freehop:credentials', tag, peer),
+    allowRoom: tag => ipcRenderer.invoke('freehop:allow-room', tag),
+    revokePeer: (tag, peer) => ipcRenderer.invoke('freehop:revoke-peer', tag, peer),
+    revokeRoom: tag => ipcRenderer.invoke('freehop:revoke-room', tag)
+  }));
+}

package/src/gate/gate.mjs

@@ -0,0 +1,357 @@
+// SPDX-License-Identifier: Apache-2.0
+// Freehop gate: a blind rendezvous mailbox. It routes sealed envelopes between peers that
+// announce the same opaque room tag. It never sees SDP, candidates, credentials or media:
+// clients seal every envelope with a room key the gate does not have. Any number of
+// interchangeable gates may serve the same room; clients announce on several at once.
+import http from 'node:http';
+import { isIPv4, isIPv6 } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { verifyGateToken } from '../shared/tokens.mjs';
+
+export const GATE_PROTOCOL = 1;
+// Worst-case memory at these defaults (measured on Node 24): (1024 admitted + 256 pending or closing
+// sockets) x (64 KiB partial frame + ~28 KiB state) = 115 MiB, + 256 x 64 KiB queued behind admission
+// = 16 MiB, + 32 MiB unflushed output, + ~60 MiB runtime: ~225 MiB. Forwarding bursts add short-lived
+// garbage on top (up to ~250 MiB before GC), so deploy/freehop-gate.service sets MemoryMax=512M.
+export const GATE_LIMITS = Object.freeze({
+  frame: 65536,            // bytes per WebSocket frame
+  box: 49152,              // sealed envelope (base64url) characters
+  roomsPerSocket: 4,
+  peersPerRoom: 16,
+  socketsPerAddress: 32,   // every per-address limit counts an IPv4 address or an IPv6 /64
+  maxSockets: 1024,        // admitted sockets
+  maxPendingSockets: 256,  // sockets not admitted yet, plus sockets closing
+  pendingPerAddress: 8,
+  helloMs: 5000,
+  closeMs: 1000,           // a close handshake gets this long, then the socket is destroyed
+  idleMs: 90000,
+  pingMs: 30000,
+  // Token bucket over every byte a socket makes the gate forward (fan-out included).
+  // Signalling for a full five-peer join is ~100 KB; media needs megabytes per minute.
+  burstBytes: 524288,
+  refillBytesPerSec: 2048,
+  messagesPerSec: 40,      // pings and unsolicited pongs count too
+  messageBurst: 400,
+  maxBufferedBytes: 1048576,   // output handed to ws and not yet flushed, per socket
+  maxBufferedTotal: 33554432,  // the same, for the whole gate
+  maxPendingFrames: 64,        // frames queued behind an admission in progress
+  maxPendingBytes: 65536
+});
+
+const TAG = /^[A-Za-z0-9_-]{22,43}$/;   // base64url of 16..32 bytes
+const BOX = /^[A-Za-z0-9_-]+$/;
+const first = set => set.values().next().value;   // sets below iterate oldest first
+
+export { mintGateToken, verifyGateToken } from '../shared/tokens.mjs';
+
+class Bucket {
+  constructor(capacity, refillPerSec) { this.capacity = capacity; this.refill = refillPerSec; this.level = capacity; this.at = Date.now(); }
+  take(amount) {
+    const now = Date.now();
+    this.level = Math.min(this.capacity, this.level + (now - this.at) / 1000 * this.refill); this.at = now;
+    if (amount > this.level) return false;
+    this.level -= amount; return true;
+  }
+}
+
+// Per-address budgets key on an IPv4 address or an IPv6 /64: one host can use a whole /64.
+// Some proxies append a port ("ip:port", "[ip]:port"); it must not split one client into many.
+function addressKey(address) {
+  const ip = String(address).replace(/^\[([^\]]*)\](:\d+)?$/, '$1').replace(/^([\d.]+):\d+$/, '$1').replace(/%.*$/, '');
+  if (isIPv4(ip)) return ip;
+  if (!isIPv6(ip)) return String(address).slice(0, 64);
+  const v4 = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(ip);
+  const text = v4 ? `${ip.slice(0, v4.index)}${(v4[1] << 8 | v4[2]).toString(16)}:${(v4[3] << 8 | v4[4]).toString(16)}` : ip;
+  const [head, tail] = text.split('::');
+  const left = head ? head.split(':') : [], right = tail ? tail.split(':') : [];
+  const g = (tail === undefined ? left : [...left, ...Array(8 - left.length - right.length).fill('0'), ...right]).map(x => parseInt(x, 16));
+  // IPv4-mapped (::ffff:0:0/96) and well-known NAT64 (64:ff9b::/96) addresses stand for one IPv4 client.
+  if (!(g[0] | g[1] | g[2] | g[3] | g[4]) && g[5] === 0xffff || g[0] === 0x64 && g[1] === 0xff9b && !(g[2] | g[3] | g[4] | g[5]))
+    return `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+  return `${g.slice(0, 4).map(x => x.toString(16)).join(':')}::/64`;
+}
+
+/**
+ * createGate({ server?, host, port, path, stun, stunUrls, tokenSecret, tokenAudience, trustProxy, authorize, limits, log })
+ * - server: an existing http(s).Server to attach to (otherwise one is created on host:port)
+ * - stun: [{ host, port }] UDP STUN Binding responders started alongside (optional)
+ * - stunUrls: STUN URLs advertised to clients (defaults derived from `stun` + publicHost)
+ * - tokenSecret: when set, `hello.auth` must be a valid gate token (room-bound tokens restrict joins)
+ * - authorize(hello, request): custom admission hook, overrides tokenSecret when given
+ * Sockets that have not been admitted have their own budget (limits.maxPendingSockets), so
+ * sockets that never send a valid hello cannot lock admitted clients out.
+ */
+export async function createGate(options = {}) {
+  const limits = { ...GATE_LIMITS, ...options.limits };
+  const log = options.log ?? (() => {});
+  const path = options.path ?? '/freehop';
+  const stats = { sockets: 0, socketsTotal: 0, pending: 0, rooms: 0, joins: 0, framesIn: 0, bytesIn: 0, framesOut: 0, bytesOut: 0,
+    buffered: 0, envelopes: 0, refused: 0, rateLimited: 0, closedForAbuse: 0, evicted: 0 };
+  const rooms = new Map();          // roomTag -> Map(peerTag -> socketState)
+  const perAddress = new Map();     // address key -> { all, waiting } socket counts
+  const sockets = new Set();        // every open socket
+  const waiting = new Set();        // not admitted yet
+  const silent = new Set();         // waiting, and no frame received yet
+  const closing = new Set();        // close handshake in progress
+  const backlog = new Set();        // sockets with unflushed output, longest behind first
+  let admitted = 0, buffered = 0;
+
+  const ownServer = !options.server;
+  const server = options.server ?? http.createServer((req, res) => {
+    if (req.url === '/healthz') { res.writeHead(200, { 'content-type': 'text/plain' }); res.end('ok'); return; }
+    res.writeHead(404); res.end();
+  });
+  // autoPong is off so pong replies go through the output budget; closeTimeout bounds every close handshake.
+  const wss = new WebSocketServer({ noServer: true, maxPayload: limits.frame, perMessageDeflate: false, clientTracking: false,
+    autoPong: false, closeTimeout: limits.closeMs });
+  const onUpgrade = (request, socket, head) => {
+    let url;
+    try { url = new URL(request.url ?? '/', 'http://gate'); }
+    catch { socket.destroy(); stats.refused++; return; }
+    if (url.pathname !== path) { socket.destroy(); return; }
+    // Behind a local reverse proxy every socket comes from loopback: with trustProxy, the
+    // client address is the hop the proxy appended to X-Forwarded-For.
+    const direct = request.socket.remoteAddress ?? '?';
+    const forwarded = options.trustProxy && /^(127\.|::1$|::ffff:127\.)/.test(direct)
+      ? String(request.headers['x-forwarded-for'] ?? '').split(',').map(v => v.trim()).filter(Boolean).pop() : null;
+    const address = addressKey(forwarded || direct);
+    const count = perAddress.get(address);
+    // A full pending budget is refused only when no closing or silent socket can make room (see accept).
+    if (count && (count.all >= limits.socketsPerAddress || count.waiting >= limits.pendingPerAddress)
+      || waiting.size + closing.size >= limits.maxPendingSockets && !closing.size && !silent.size) { socket.destroy(); stats.refused++; return; }
+    wss.handleUpgrade(request, socket, head, ws => accept(ws, request, address));
+  };
+  server.on('upgrade', onUpgrade);
+
+  const stunResponders = [];
+  if (options.stun?.length) {
+    const { createStunResponder } = await import('./stun-responder.mjs');
+    for (const spec of options.stun) stunResponders.push(await createStunResponder({ ...spec, log }));
+  }
+  // A wildcard bind cannot be advertised: clients need the public host name or address.
+  const stunUrls = options.stunUrls ?? stunResponders.map(r => {
+    const a = r.address();
+    const host = options.publicHost ?? (a.address === '0.0.0.0' || a.address === '::' ? null : a.address);
+    if (!host) { log('stun-not-advertised', { reason: 'wildcard bind without publicHost' }); return null; }
+    return `stun:${host.includes(':') ? `[${host}]` : host}:${a.port}`;
+  }).filter(Boolean);
+
+  // Output accounting: bytes handed to ws and not yet flushed (its write callback has not run).
+  function queue(state, size, write) {
+    if (state.closed || state.ws.readyState !== 1) return false;
+    // A receiver that stops reading must not make the gate buffer without bound.
+    if (state.buffered + size > limits.maxBufferedBytes) { stats.closedForAbuse++; kill(state); return false; }
+    // Over the gate-wide budget, the receiver that has been behind the longest goes first,
+    // so stalled sockets cannot spend the budget of receivers that keep up.
+    while (buffered + size > limits.maxBufferedTotal && backlog.size) {
+      const slowest = first(backlog); stats.closedForAbuse++; kill(slowest);
+      if (slowest === state) return false;
+    }
+    if (!state.buffered) backlog.add(state);
+    state.buffered += size; buffered += size;
+    write(() => {
+      if (state.phase === 'gone') return;   // released in full on close
+      state.buffered -= size; buffered -= size;
+      if (!state.buffered) backlog.delete(state);
+    });
+    return true;
+  }
+  function send(state, message) {
+    const text = JSON.stringify(message);
+    if (!queue(state, Buffer.byteLength(text), done => state.ws.send(text, done))) return false;
+    stats.framesOut++; stats.bytesOut += text.length;
+    return true;
+  }
+  function emit(state, message) {
+    if (state.closed) return false;
+    // Expiry is checked on delivery too, so an expired socket stops receiving at once, not at the next heartbeat.
+    if (Date.now() >= state.expiresAt) { refuse(state, 'auth-expired', true); return false; }
+    return send(state, message);
+  }
+  function refuse(state, code, close = false) {
+    stats.refused++; send(state, { t: 'error', code });
+    if (close) { stats.closedForAbuse++; shut(state, 1008, code); }
+  }
+
+  // Socket phases: waiting (not admitted) -> admitted -> closing -> gone.
+  function leavePhase(state) {
+    if (state.phase === 'waiting') { waiting.delete(state); silent.delete(state); perAddress.get(state.address).waiting--; }
+    else if (state.phase === 'admitted') admitted--;
+    else if (state.phase === 'closing') closing.delete(state);
+  }
+  // Rooms are left in a microtask: an eviction inside a fan-out loop then cannot reorder its notifications.
+  function leaveRooms(state) {
+    if (state.leaving) return; state.leaving = true;
+    queueMicrotask(() => { for (const room of [...state.rooms.keys()]) leaveRoom(state, room); });
+  }
+  // Close frame now, destroyed after closeMs at most (ws closeTimeout). Closing sockets share the
+  // pending budget; over it, the oldest closing socket skips the rest of its grace period.
+  function shut(state, code, reason) {
+    if (state.closed) return;
+    leavePhase(state); state.phase = 'closing'; state.closed = true; closing.add(state);
+    if (waiting.size + closing.size > limits.maxPendingSockets) kill(first(closing));
+    if (state.phase !== 'closing') return;
+    state.ws.close(code, reason); leaveRooms(state);
+  }
+  function kill(state) { release(state); state.ws.terminate(); }
+  function release(state) {
+    if (state.phase === 'gone') return;
+    leavePhase(state); state.phase = 'gone'; state.closed = true;
+    clearTimeout(state.helloTimer); sockets.delete(state); backlog.delete(state);
+    buffered -= state.buffered; state.buffered = 0;
+    const count = perAddress.get(state.address); if (--count.all === 0) perAddress.delete(state.address);
+    leaveRooms(state);
+  }
+  function leaveRoom(state, room) {
+    const members = rooms.get(room); const peer = state.rooms.get(room);
+    state.rooms.delete(room);
+    if (!members || members.get(peer) !== state) return;
+    members.delete(peer);
+    for (const other of members.values()) emit(other, { t: 'peer', room, peer, on: false });
+    if (members.size === 0) { rooms.delete(room); stats.rooms = rooms.size; }
+  }
+
+  async function admit(state, hello, request) {
+    if (options.authorize) return !!(await options.authorize(hello, request));
+    if (!options.tokenSecret) return true;
+    const a = server.address();
+    const audience = options.tokenAudience ?? `${server.setSecureContext ? 'wss' : 'ws'}://${a.address.includes(':') ? `[${a.address}]` : a.address}:${a.port}${path}`;
+    const claims = verifyGateToken(options.tokenSecret, hello.auth, { audience });
+    if (!claims) return false;
+    state.boundRoom = claims.room ?? null;
+    state.expiresAt = claims.exp * 1000;
+    return true;
+  }
+
+  function accept(ws, request, address) {
+    // A full pending budget sheds a closing socket, else the oldest silent one. A real client
+    // sends hello within a round trip of the upgrade, so silent sockets cannot keep it out.
+    while (waiting.size + closing.size >= limits.maxPendingSockets) {
+      const victim = first(closing) ?? first(silent); if (!victim) break;
+      stats.evicted++; kill(victim);
+    }
+    const state = { ws, address, phase: 'waiting', rooms: new Map(), boundRoom: null, expiresAt: Infinity, closed: false,
+      bytes: new Bucket(limits.burstBytes, limits.refillBytesPerSec), messages: new Bucket(limits.messageBurst, limits.messagesPerSec),
+      lastSeen: Date.now(), nonce: null, buffered: 0, helloTimer: null, leaving: false };
+    const count = perAddress.get(address) ?? perAddress.set(address, { all: 0, waiting: 0 }).get(address);
+    count.all++; count.waiting++;
+    sockets.add(state); waiting.add(state); silent.add(state); stats.socketsTotal++;
+    state.helloTimer = setTimeout(() => { if (state.phase === 'waiting') shut(state, 1008, 'hello-timeout'); }, limits.helloMs);
+    ws.on('close', () => release(state));
+    ws.on('error', () => {});
+    ws.on('ping', data => {
+      if (state.closed) return;
+      if (!state.messages.take(1)) { stats.rateLimited++; return refuse(state, 'rate', true); }
+      queue(state, data.length + 2, done => ws.pong(data, false, done));
+    });
+    ws.on('pong', data => {
+      if (state.closed) return;
+      // Only an echo of the latest heartbeat nonce shows that the socket reads what it is sent.
+      if (state.nonce?.equals(data)) { state.nonce = null; state.lastSeen = Date.now(); }
+      else if (!state.messages.take(1)) { stats.rateLimited++; refuse(state, 'rate', true); }
+    });
+    let chain = Promise.resolve(), pendingFrames = 0, pendingBytes = 0;
+    ws.on('message', (data, isBinary) => {
+      if (state.closed) return;
+      silent.delete(state);
+      // Frames queued behind an admission in progress are bounded here. Admitted sockets answer to
+      // the message and byte budgets only, so a burst of frames in one TCP read is not a flood.
+      const queued = state.phase === 'waiting';
+      if (queued && ((pendingBytes += data.length) > limits.maxPendingBytes || ++pendingFrames > limits.maxPendingFrames) || !state.messages.take(1)) {
+        stats.rateLimited++; return refuse(state, 'rate', true);
+      }
+      chain = chain.then(() => handle(state, data, isBinary, request)).catch(error => {
+        log('gate-error', { message: error?.message }); refuse(state, 'internal', true);
+      }).finally(() => { if (queued) { pendingFrames--; pendingBytes -= data.length; } });
+    });
+  }
+
+  async function handle(state, data, isBinary, request) {
+    if (state.closed) return;
+    if (Date.now() >= state.expiresAt) return refuse(state, 'auth-expired', true);
+    stats.framesIn++; stats.bytesIn += data.length; state.lastSeen = Date.now();
+    if (isBinary) return refuse(state, 'binary', true);
+    let m; try { m = JSON.parse(data.toString('utf8')); } catch { return refuse(state, 'json', true); }
+    if (!m || typeof m !== 'object' || Array.isArray(m) || typeof m.t !== 'string') return refuse(state, 'schema', true);
+    if (state.phase === 'waiting') {
+      if (m.t !== 'hello' || m.v !== GATE_PROTOCOL) return refuse(state, 'hello', true);
+      if (!(await admit(state, m, request))) return refuse(state, 'auth', true);
+      if (state.closed) return;
+      if (admitted >= limits.maxSockets) { refuse(state, 'busy'); return shut(state, 1013, 'busy'); }
+      clearTimeout(state.helloTimer); leavePhase(state); state.phase = 'admitted'; admitted++;
+      return emit(state, { t: 'welcome', v: GATE_PROTOCOL, stun: stunUrls, limits: { box: limits.box, peersPerRoom: limits.peersPerRoom } });
+    }
+    switch (m.t) {
+      case 'join': {
+        if (Object.keys(m).length !== 3 || typeof m.room !== 'string' || typeof m.peer !== 'string' || !TAG.test(m.room) || !TAG.test(m.peer)) return refuse(state, 'schema', true);
+        if (state.boundRoom && state.boundRoom !== m.room) return refuse(state, 'room-not-allowed');
+        if (state.rooms.has(m.room)) return refuse(state, 'already-joined');
+        if (state.rooms.size >= limits.roomsPerSocket) return refuse(state, 'too-many-rooms');
+        let members = rooms.get(m.room);
+        if (members?.has(m.peer)) return refuse(state, 'peer-taken');
+        if ((members?.size ?? 0) >= limits.peersPerRoom) return refuse(state, 'room-full');
+        if (!members) { members = new Map(); rooms.set(m.room, members); stats.rooms = rooms.size; }
+        const peers = [...members.keys()];
+        members.set(m.peer, state); state.rooms.set(m.room, m.peer); stats.joins++;
+        if (!emit(state, { t: 'peers', room: m.room, peers })) return;
+        for (const other of members.values()) if (other !== state && !state.closed) emit(other, { t: 'peer', room: m.room, peer: m.peer, on: true });
+        return;
+      }
+      case 'leave':
+        if (Object.keys(m).length !== 2 || !state.rooms.has(m.room)) return refuse(state, 'schema');
+        return leaveRoom(state, m.room);
+      case 'send': {
+        if (Object.keys(m).length !== 4 || typeof m.box !== 'string' || m.box.length > limits.box || !BOX.test(m.box)) return refuse(state, 'schema', true);
+        const from = state.rooms.get(m.room);
+        if (!from) return refuse(state, 'not-joined');
+        const members = rooms.get(m.room);
+        const targets = m.to === '*' ? [...members.entries()].filter(([peer]) => peer !== from).map(([, s]) => s)
+          : TAG.test(m.to ?? '') && members.has(m.to) && m.to !== from ? [members.get(m.to)] : null;
+        if (!targets) return refuse(state, 'no-such-peer');
+        // Charge the sender for the full fan-out: the gate's cost is what it forwards.
+        if (!state.bytes.take(m.box.length * Math.max(1, targets.length))) { stats.rateLimited++; return refuse(state, 'rate', true); }
+        for (const target of targets) emit(target, { t: 'recv', room: m.room, from, box: m.box });
+        stats.envelopes += targets.length;
+        return;
+      }
+      case 'ping': return emit(state, { t: 'pong' });
+      default: return refuse(state, 'type', true);
+    }
+  }
+
+  const heartbeat = setInterval(() => {
+    const now = Date.now();
+    for (const state of sockets) {
+      if (state.closed) continue;   // closing sockets are destroyed within closeMs
+      if (now >= state.expiresAt) { refuse(state, 'auth-expired', true); continue; }
+      // An unanswered nonce means the socket did not read its last ping: unsolicited pongs do not count.
+      if (state.nonce || now - state.lastSeen > limits.idleMs) { kill(state); continue; }
+      const nonce = state.nonce = randomBytes(8);
+      queue(state, nonce.length + 2, done => state.ws.ping(nonce, false, done));
+    }
+  }, limits.pingMs);
+  heartbeat.unref?.();
+
+  if (ownServer) await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, options.host ?? '127.0.0.1', () => { server.off('error', reject); resolve(); });
+  });
+
+  return {
+    server, path, stunUrls,
+    url(host) { const a = server.address(); return `ws://${host ?? (a.address.includes(':') ? `[${a.address}]` : a.address)}:${a.port}${path}`; },
+    stats() { return { ...stats, sockets: sockets.size, pending: waiting.size, buffered, stun: stunResponders.map(r => r.stats()) }; },
+    rooms() { return rooms.size; },
+    async close() {
+      clearInterval(heartbeat);
+      server.off('upgrade', onUpgrade);
+      for (const state of sockets) state.ws.terminate();
+      wss.close();
+      await Promise.all(stunResponders.map(r => r.close()));
+      if (ownServer) await new Promise(resolve => server.close(() => resolve()));
+    }
+  };
+}
+
+export const randomTag = (bytes = 16) => randomBytes(bytes).toString('base64url');

package/src/gate/stun-responder.mjs

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// RFC 8489 Binding responder: tells a peer which public address its UDP socket maps to.
+// It answers Binding requests only, never relays anything, and rate-limits per source.
+import dgram from 'node:dgram';
+import { isStunMessage, decode, encode, encodeXorAddress, METHOD, CLASS, ATTR } from '../shared/stun.mjs';
+
+export async function createStunResponder({ host = '0.0.0.0', port = 3478, ratePerSec = 10, burst = 30, totalRatePerSec = 200, totalBurst = 400, software = 'peerlane-gate', log = () => {} } = {}) {
+  const type = host.includes(':') ? 'udp6' : 'udp4';
+  const socket = dgram.createSocket({ type, ipv6Only: type === 'udp6' });
+  const stats = { requests: 0, responses: 0, bytesIn: 0, bytesOut: 0, dropped: 0, rateLimited: 0 };
+  const buckets = new Map();
+  const total = { level: totalBurst, at: Date.now() };
+  const allow = address => {
+    const now = Date.now();
+    total.level = Math.min(totalBurst, total.level + (now - total.at) / 1000 * totalRatePerSec); total.at = now;
+    if (total.level < 1) return false;
+    let b = buckets.get(address);
+    if (!b) {
+      if (buckets.size > 50000) buckets.delete(buckets.keys().next().value);
+      b = { level: burst, at: now }; buckets.set(address, b);
+    }
+    b.level = Math.min(burst, b.level + (now - b.at) / 1000 * ratePerSec); b.at = now;
+    if (b.level < 1) return false;
+    b.level -= 1; total.level -= 1; return true;
+  };
+  socket.on('message', (buf, rinfo) => {
+    try {
+      stats.bytesIn += buf.length;
+      if (buf.length > 548 || !isStunMessage(buf)) { stats.dropped++; return; }
+      const msg = decode(buf);
+      if (!msg || msg.method !== METHOD.BINDING || msg.cls !== CLASS.REQUEST) { stats.dropped++; return; }
+      if (!allow(rinfo.address)) { stats.rateLimited++; return; }
+      stats.requests++;
+      const mapped = rinfo.address.startsWith('::ffff:') && rinfo.address.includes('.')
+        ? { family: 4, address: rinfo.address.slice(7), port: rinfo.port }
+        : { family: rinfo.family === 'IPv6' ? 6 : 4, address: rinfo.address, port: rinfo.port };
+      const out = encode({ method: METHOD.BINDING, cls: CLASS.SUCCESS, transactionId: msg.transactionId, attributes: [
+        { type: ATTR.XOR_MAPPED_ADDRESS, value: encodeXorAddress(mapped, msg.transactionId) },
+        { type: ATTR.SOFTWARE, value: Buffer.from(software) }
+      ] }, { fingerprint: true });
+      socket.send(out, rinfo.port, rinfo.address);
+      stats.responses++; stats.bytesOut += out.length;
+    } catch (error) { stats.dropped++; log('stun-error', { message: error?.message }); }
+  });
+  socket.on('error', error => log('stun-socket-error', { message: error?.message }));
+  await new Promise((resolve, reject) => { socket.once('error', reject); socket.bind(port, host, () => { socket.off('error', reject); resolve(); }); });
+  return {
+    address: () => socket.address(),
+    stats: () => ({ ...stats }),
+    close: () => new Promise(resolve => { try { socket.close(resolve); } catch { resolve(); } })
+  };
+}