freehop 0.1.0-alpha.0

package/SDK.md

@@ -0,0 +1,113 @@
+# Freehop SDK: integrating it into an application
+
+Freehop is built to be consumed. Any application uses the same five pieces. Redline Wars is
+a planned consumer and test environment, using the same public API. Nothing below is
+game-specific.
+
+```
+ your backend            your gate host            every client               hosts (optional)
+ ───────────             ─────────────             ────────────               ────────────────
+ createAuthority()  ───► freehop-gate (gate)  ◄── connect(ticket)        hostSession(ticket)
+   openRoom / ticket       signalling only          media P2P / via a          desktop app or server
+   kick (rotate)           never media              session gateway            that hosts the session
+        │                                                ▲
+        └──────── tickets over YOUR authenticated channel┘     desktop apps: installFreehopGateway()
+```
+
+## 1. Backend: decide who is in a room (`freehop/authority`)
+```js
+import { createAuthority } from 'freehop/authority';
+const authority = createAuthority({
+  app: 'my-app',                                   // namespaces room keys
+  gates: ['wss://example.com/freehop'],           // one or more gates (yours, community, bt+wss:// trackers)
+  gateTokenSecrets: { 'wss://example.com/freehop': process.env.FREEHOP_GATE_TOKEN_SECRET },
+  stun: ['stun:example.com:3478']                    // application-approved discovery servers
+});
+await authority.openRoom(roomId);                  // creates the room secret (never leaves the backend except in tickets)
+const ticket = await authority.ticket(roomId, memberId);   // for members your app admitted
+const { tickets } = await authority.kick(roomId, memberId); // rotates the secret; deliver new tickets to the rest
+```
+A ticket (`{ v, app, roomId, epoch, gates, secret, auth?, stun?, expires }`) is a bearer credential for the
+room. Deliver it only to that member, over the application's own authenticated channel.
+`auth` maps exact gate URLs to audience-bound tokens; community gates without a configured signing key receive no token. `stun` lists approved STUN URLs: clients ignore gate-supplied STUN hints.
+`encodeTicket`/`decodeTicket` (`freehop/ticket`) turn it into a compact string.
+
+## 2. Gate: run the signalling service (`bin/freehop-gate.mjs`)
+```sh
+FREEHOP_GATE_PORT=8787 FREEHOP_GATE_PUBLIC_HOST=example.com FREEHOP_GATE_STUN='0.0.0.0:3478,[::]:3478' \
+FREEHOP_GATE_TOKEN_SECRET=… FREEHOP_GATE_TOKEN_AUDIENCE=wss://example.com/freehop FREEHOP_GATE_TRUST_PROXY=1 node bin/freehop-gate.mjs
+```
+Put it behind your TLS proxy (`deploy/Caddyfile.snippet`, `deploy/freehop-gate.service`). It
+carries sealed signalling only: about 15–35 KB per peer pair at setup, roughly zero
+afterwards. More gates mean more resilience. Clients use every gate in the ticket, and a call
+survives all gates going down. Public trackers can replace your own gate; configure approved STUN separately. Keepalives, tracker discovery and recovery still contribute signalling traffic.
+
+## 3. Client: join with the ticket (`freehop/sdk`)
+
+This runs in the browser or Electron renderer. Bundle the package import with your frontend build tool, fetch the ticket from your authenticated backend, and join from a user control on an HTTPS page (localhost works for development). The callbacks below are UI placeholders; the media, update and leave calls illustrate separate controls, not a startup sequence. Node.js 22 or newer is needed for the backend/gate/host helpers, not for browser execution.
+
+```js
+import { connect } from 'freehop';
+const session = await connect(ticket, { media: { audio: true, video: false }, adaptiveVideo: true });
+session.on('peer', ({ id }) => …);                       // an authenticated member appeared
+session.on('track', ({ peer, track }) => session.attach(track, elementFor(peer)));
+session.on('path', ({ peer, kind, via }) => …);          // direct | gateway | relay | bridged | unreachable
+session.on('peer-left', ({ id, reason }) => …);
+await session.setMicrophone(false); await session.setCamera(true);
+const levels = await session.levels();                   // speaking indicators
+await session.update(newTicket, { dropped: [kickedPeerId] });   // after a kick
+await session.switchDevice('audio', deviceId);      // another microphone or camera, no renegotiation
+await session.send({ type: 'chat', text: 'hi' });   // app data to everyone (or { to: peerId })
+session.on('message', ({ from, data }) => …);      // untrusted input: render as text
+session.on('video-quality', ({ peer, direction, level, reason }) => …);
+await session.setAdaptiveVideo(false);              // disable at runtime
+await session.refresh(reissuedTicket);   // same epoch, fresh gate tokens for long calls
+await session.leave();                   // also releases the room on a desktop gateway
+```
+`session.disconnectPeer(peerId)` removes only a local connection. It does not revoke membership. The former `session.kick()` throws a migration error; use `authority.kick()` and distribute replacement tickets for removal.
+
+`adaptiveVideo` is opt-in and defaults to `false`. When enabled, Freehop uses per-link WebRTC statistics to lower video after sustained packet loss, dropped frames, encoder CPU limitation or a low outgoing bitrate estimate. It never changes audio. It can ask the other endpoint on that link to lower video too; peers that did not opt in ignore the request. Recovery requires 25 seconds of healthy samples and moves one level at a time. Severe sustained pressure can pause video; a minimal-quality probe checks for recovery before restoring it. A manual `setCamera(false)` remains authoritative.
+
+The `video-quality` event reports `{ peer, direction: 'send'|'receive', level: 'normal'|'reduced'|'minimal'|'paused', reason }`. `reason` is `monitoring`, `cpu`, `bandwidth`, `peer-request`, `recovery-probe`, `recovery` or `disabled`. Browser support and stats availability vary; missing measurements leave the current quality unchanged.
+
+Map your member ids to Freehop peer ids (`session.id`) in your backend, so that a kick can
+name the peer the remaining clients must drop.
+
+Audio packets arriving does not guarantee sound playback. `attach()` attempts playback, but browsers may block it. Check `element.play()` and offer a button that retries it directly from a click; preserve an existing audio attachment when only video changes. See the [browser playback example](https://jolynstudios.github.io/freehop/docs/sdk/client#audio-playback-in-the-browser).
+
+## 4. Desktop apps: become reachable (`freehop/electron`)
+Main process:
+```js
+import { installFreehopGateway } from 'freehop/electron';
+const freehop = installFreehopGateway({ ipcMain, allowedOrigins: ['https://play.example.com'] });
+app.on('will-quit', () => freehop.close());
+new BrowserWindow({ webPreferences: { preload: require.resolve('freehop/electron/preload'),
+  additionalArguments: ['--freehop-origins=https://play.example.com'], contextIsolation: true } });
+```
+`connect()` finds `window.freehopGateway` automatically. It starts the gateway (TURN plus a
+PCP/NAT-PMP/UPnP router mapping) on first use, allows that room, and offers it to the room's
+peers with per-peer credentials. Participants behind hard NATs or UDP-blocking networks can then
+reach the desktop participant without any third party. The minting key stays in the main process; the renderer requests short-lived credentials through an origin-checked broker. HTTPS origins are required except for loopback development. A raw gateway integration supplies `credentialsFor(tag, peer)` alongside its public `info()` metadata, rather than sending the key to a page.
+
+The gateway relays only between allocations on itself (`relayScope: 'internal'`, the default), so room members cannot use it to reach other internet hosts. A window's rooms are released when its page leaves, navigates away or closes.
+
+## 5. Hosts: let the session's own host relay for it (`freehop/host`)
+Whoever hosts a session can make its machine the session's gateway: an app server, a
+community server, or a desktop app that hosts. It needs a public address or a router mapping.
+```js
+import { hostSession } from 'freehop/host';
+const host = await hostSession(hostTicket);         // host.available === false when unreachable
+await host.update(nextTicket, { dropped: [peerId] });
+await host.close();
+```
+Never call this on infrastructure whose bandwidth you do not want to spend. The operator's own
+servers should not host sessions' media.
+
+## Runnable reference
+`examples/minimal/` is a complete consumer: backend, gate on the same origin, and a page with
+join, mic/camera, per-peer path and level, and kick through the app's API. Run it with
+`node examples/minimal/server.mjs` and open it in several windows. `test/browser/example-app.mjs`
+drives it with three real browsers and asserts the mesh, the kick rotation and the removal.
+
+---
+Documentation licensed under CC BY 4.0. Copyright 2026 Jolyn Studios. Provided as is, without warranty of any kind.

package/bin/freehop-gate.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Freehop gate service. Configuration by environment:
+//   FREEHOP_GATE_HOST=127.0.0.1   FREEHOP_GATE_PORT=8787   FREEHOP_GATE_PATH=/freehop
+//   FREEHOP_GATE_PUBLIC_HOST=gate.example.com   (advertised in stun: URLs)
+//   FREEHOP_GATE_STUN=0.0.0.0:3478[,[::]:3478]  (optional STUN Binding responders)
+//   FREEHOP_GATE_TOKEN_SECRET=...               (32+ characters: only clients with valid tokens)
+//   FREEHOP_GATE_TOKEN_AUDIENCE=wss://gate.example.com/freehop   (required with a token secret)
+//   FREEHOP_GATE_TRUST_PROXY=1                  (behind a local reverse proxy: use X-Forwarded-For)
+//   FREEHOP_GATE_ALLOW_ANONYMOUS=1              (or FREEHOP_GATE_ANONYMOUS=1: open gate beyond loopback)
+// TLS is terminated by the reverse proxy (Caddy) in front of it.
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+import { createGate } from '../src/gate/gate.mjs';
+
+const env = process.env;
+const log = (event, details) => console.error(JSON.stringify({ at: new Date().toISOString(), event, ...details }));
+const fail = message => { console.error(`freehop-gate: ${message}`); process.exit(1); };
+const flag = name => { const v = env[name] ?? ''; if (!['', '0', '1'].includes(v)) fail(`${name} must be 0 or 1`); return v === '1'; };
+const portNumber = (value, name) => { const n = Number(value); if (!/^\d+$/.test(String(value)) || !Number.isInteger(n) || n < 1 || n > 65535) fail(`${name} must be a port from 1 to 65535`); return n; };
+
+const host = env.FREEHOP_GATE_HOST ?? '127.0.0.1';
+if (!host) fail('FREEHOP_GATE_HOST is empty; set 0.0.0.0 or :: to listen on every interface');
+const port = portNumber(env.FREEHOP_GATE_PORT ?? 8787, 'FREEHOP_GATE_PORT');
+const tokenSecret = env.FREEHOP_GATE_TOKEN_SECRET || undefined;
+if (tokenSecret && tokenSecret.length < 32) fail('FREEHOP_GATE_TOKEN_SECRET must be at least 32 characters, for example from: openssl rand -base64 32');
+if (tokenSecret && !/^wss?:\/\//.test(env.FREEHOP_GATE_TOKEN_AUDIENCE ?? '')) fail('Set FREEHOP_GATE_TOKEN_AUDIENCE to the exact public WebSocket gate URL');
+const trustProxy = flag('FREEHOP_GATE_TRUST_PROXY');
+const anonymous = [flag('FREEHOP_GATE_ALLOW_ANONYMOUS'), flag('FREEHOP_GATE_ANONYMOUS')].includes(true);
+// Reachable beyond loopback: the listen address is (or resolves to) anything but loopback, or a
+// proxy or public host name is configured. Such a gate needs tokens or an explicit anonymous mode.
+const loopback = address => /^(127\.|::1$|::ffff:127\.)/i.test(address);
+const addresses = isIP(host) ? [host] : await lookup(host, { all: true }).then(list => list.map(a => a.address), () => fail(`FREEHOP_GATE_HOST ${host} does not resolve`));
+if ((trustProxy || env.FREEHOP_GATE_PUBLIC_HOST || !addresses.every(loopback)) && !tokenSecret && !anonymous)
+  fail('A gate reachable beyond loopback needs FREEHOP_GATE_TOKEN_SECRET, or FREEHOP_GATE_ALLOW_ANONYMOUS=1 for an open gate');
+const stun = (env.FREEHOP_GATE_STUN ?? '').split(',').filter(Boolean).map(spec => {
+  const m = /^\[?([^\]]+?)\]?:(\d+)$/.exec(spec.trim());
+  if (!m) fail(`Bad FREEHOP_GATE_STUN entry: ${spec}`);
+  return { host: m[1], port: portNumber(m[2], 'FREEHOP_GATE_STUN') };
+});
+if (!tokenSecret) log('warning', { message: 'anonymous gate: no FREEHOP_GATE_TOKEN_SECRET, so any client can use it' });
+const gate = await createGate({
+  host, port, path: env.FREEHOP_GATE_PATH ?? '/freehop',
+  publicHost: env.FREEHOP_GATE_PUBLIC_HOST, stun, tokenSecret,
+  tokenAudience: env.FREEHOP_GATE_TOKEN_AUDIENCE,
+  trustProxy,
+  log
+});
+console.log(JSON.stringify({ event: 'listening', url: gate.url(), stun: gate.stunUrls }));
+const report = setInterval(() => console.log(JSON.stringify({ event: 'stats', ...gate.stats() })), 300000);
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, async () => { clearInterval(report); await gate.close(); process.exit(0); });

package/deploy/Caddyfile.snippet

@@ -0,0 +1,6 @@
+# Inside the existing site block for play.example.com: the gate shares the TLS origin.
+# UDP 3478 (STUN) must be open in the host firewall; no TURN/relay ports are needed.
+# Caddy replaces X-Forwarded-For with the client address, which FREEHOP_GATE_TRUST_PROXY=1 relies on.
+handle /freehop {
+	reverse_proxy 127.0.0.1:8787
+}

package/deploy/freehop-gate.service

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+# Freehop gate: signalling-only rendezvous. It never carries media; its traffic is a few
+# KB per call setup. Runs unprivileged, loopback-only behind Caddy, plus a public STUN port.
+[Unit]
+Description=Freehop gate (signalling only)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=freehop
+Group=freehop
+WorkingDirectory=/opt/freehop
+Environment=FREEHOP_GATE_HOST=127.0.0.1
+Environment=FREEHOP_GATE_PORT=8787
+Environment=FREEHOP_GATE_PATH=/freehop
+Environment=FREEHOP_GATE_PUBLIC_HOST=play.example.com
+Environment=FREEHOP_GATE_STUN=0.0.0.0:3478,[::]:3478
+Environment=FREEHOP_GATE_TRUST_PROXY=1
+Environment=FREEHOP_GATE_TOKEN_AUDIENCE=wss://play.example.com/freehop
+EnvironmentFile=-/etc/freehop/gate.env
+ExecStart=/usr/bin/node /opt/freehop/bin/freehop-gate.mjs
+Restart=on-failure
+RestartSec=2
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectKernelLogs=true
+ProtectControlGroups=true
+ProtectClock=true
+RestrictNamespaces=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+CapabilityBoundingSet=
+UMask=0077
+# V8 uses JIT executable memory; do not enable MemoryDenyWriteExecute here.
+# The gate's default limits need about 225 MiB at worst, plus garbage from bursts (src/gate/gate.mjs).
+MemoryMax=512M
+LimitNOFILE=8192
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "freehop",
+  "version": "0.1.0-alpha.0",
+  "description": "Peer-to-peer voice, video and data where your servers never carry or pay for media: blind gates for signalling, session-owned gateways and forwarding instead of operator relays.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./src/sdk/client.mjs",
+    "./client": "./src/client/peerlane.mjs",
+    "./gate": "./src/gate/gate.mjs",
+    "./relay": "./src/relay/agent.mjs",
+    "./turn": "./src/relay/turn-server.mjs",
+    "./port-mapper": "./src/relay/port-mapper.mjs",
+    "./member": "./src/relay/member.mjs",
+    "./stun": "./src/shared/stun.mjs",
+    "./sdk": "./src/sdk/client.mjs",
+    "./authority": "./src/sdk/authority.mjs",
+    "./host": "./src/sdk/host.mjs",
+    "./ticket": "./src/sdk/ticket.mjs",
+    "./electron": "./src/electron/main.mjs",
+    "./electron/preload": "./src/electron/preload.cjs",
+    "./tokens": "./src/shared/tokens.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:browsers": "node test/browser/smoke.mjs chromium,firefox,webkit --tls && node test/browser/multigate.mjs && node test/browser/rekey.mjs && node test/browser/example-app.mjs",
+    "gate": "node bin/freehop-gate.mjs",
+    "example": "node examples/minimal/server.mjs"
+  },
+  "author": "Jolyn Studios",
+  "homepage": "https://jolynstudios.github.io/freehop/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jolynstudios/freehop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jolynstudios/freehop/issues"
+  },
+  "keywords": [
+    "webrtc",
+    "p2p",
+    "peer-to-peer",
+    "voice-chat",
+    "video-chat",
+    "nat-traversal",
+    "turn",
+    "stun",
+    "upnp",
+    "pcp",
+    "nat-pmp",
+    "signalling",
+    "games",
+    "sdk"
+  ],
+  "bin": {
+    "freehop-gate": "bin/freehop-gate.mjs"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "deploy/",
+    "README.md",
+    "ARCHITECTURE.md",
+    "PROTOCOL.md",
+    "SDK.md",
+    "LICENSE",
+    "LICENSE-docs",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "playwright": "1.62.0"
+  }
+}

package/src/client/crypto.mjs

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// The room secret never leaves the peers. HKDF derives an opaque room tag (the only room
+// identifier a gate sees) and an AES-GCM key that seals every signalling envelope end to end.
+const te = new TextEncoder(), td = new TextDecoder();
+const subtle = globalThis.crypto.subtle;
+
+export function toBase64Url(bytes) {
+  let s = ''; for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+export function fromBase64Url(text) {
+  const s = atob(text.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - text.length % 4) % 4));
+  const out = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+export const randomId = (bytes = 16) => toBase64Url(globalThis.crypto.getRandomValues(new Uint8Array(bytes)));
+
+/** deriveRoom(secret, app) -> { tag, key }. `secret` is a string or bytes with >=128 bits of entropy. */
+export async function deriveRoom(secret, app = 'peerlane') {
+  const raw = typeof secret === 'string' ? te.encode(secret) : secret;
+  if (!(raw instanceof Uint8Array) || raw.length < 16) throw new TypeError('Room secret must carry at least 16 bytes.');
+  const base = await subtle.importKey('raw', raw, 'HKDF', false, ['deriveBits', 'deriveKey']);
+  const salt = te.encode('peerlane/v1/' + app);
+  const tag = toBase64Url(new Uint8Array(await subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info: te.encode('room-tag') }, base, 256)));
+  const key = await subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt, info: te.encode('envelope-key') }, base,
+    { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+  return { tag, key };
+}
+
+// The additional data binds room, sender and recipient: a gate that re-routes or relabels an
+// envelope makes it fail authentication instead of reaching the wrong peer.
+const aad = (room, from, to) => te.encode(`peerlane/v1|${room.tag}|${from}|${to}`);
+
+export async function seal(room, from, to, payload) {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad(room, from, to) }, room.key, te.encode(JSON.stringify(payload))));
+  const out = new Uint8Array(12 + ct.length); out.set(iv); out.set(ct, 12);
+  return toBase64Url(out);
+}
+
+export async function open(room, from, to, box) {
+  try {
+    const bytes = fromBase64Url(box);
+    if (bytes.length < 29) return null;
+    const plain = await subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12), additionalData: aad(room, from, to) }, room.key, bytes.subarray(12));
+    const payload = JSON.parse(td.decode(plain));
+    return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : null;
+  } catch { return null; }
+}

package/src/client/gate-client.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// One connection to one gate. Gates are interchangeable mailboxes: a room uses several at
+// once, reconnects each independently and never depends on any single one.
+export class Emitter {
+  #handlers = new Map();
+  on(type, fn) { (this.#handlers.get(type) ?? this.#handlers.set(type, new Set()).get(type)).add(fn); return () => this.off(type, fn); }
+  off(type, fn) { this.#handlers.get(type)?.delete(fn); }
+  emit(type, detail) { for (const fn of [...(this.#handlers.get(type) ?? [])]) { try { fn(detail); } catch (error) { console.error(error); } } }
+}
+
+export class GateClient extends Emitter {
+  constructor(url, { room, peer, auth, WebSocketImpl = globalThis.WebSocket, backoffMs = [500, 1000, 2000, 4000, 8000, 15000, 30000] } = {}) {
+    super();
+    Object.assign(this, { url, room, peer, auth, WebSocketImpl, backoffMs, pingMs: 30000 });
+    this.state = 'idle'; this.attempt = 0; this.ws = null; this.closed = false; this.stun = [];
+    this.counters = { sent: 0, received: 0, bytesOut: 0, bytesIn: 0, errors: 0, connects: 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 = async () => {
+      let auth;
+      try { auth = typeof this.auth === 'function' ? await this.auth(this.url) : typeof this.auth === 'object' && this.auth ? this.auth[this.url] : this.auth; }
+      catch { if (ws === this.ws) { this.counters.errors++; ws.close(); } return; }
+      if (ws !== this.ws) return;
+      this.#raw({ t: 'hello', v: 1, ...(auth ? { auth } : {}) });
+    };
+    ws.onmessage = event => {
+      if (ws !== this.ws || typeof event.data !== 'string' || event.data.length > 65536) return;
+      this.counters.bytesIn += event.data.length;
+      let m; try { m = JSON.parse(event.data); } catch { return; }
+      switch (m?.t) {
+        case 'welcome':
+          // STUN belongs to application configuration, never to an untrusted mailbox.
+          this.stun = [];
+          this.#raw({ t: 'join', room: this.room, peer: this.peer });
+          break;
+        case 'peers':
+          if (m.room !== this.room || !Array.isArray(m.peers) || m.peers.length > 64) return;
+          this.state = 'joined'; this.attempt = 0; this.joinAttempts = 0; this.counters.connects++;
+          // Application-level keepalive: the gate drops sockets it has not heard from.
+          clearInterval(this.pinger);
+          this.pinger = setInterval(() => this.#raw({ t: 'ping' }), this.pingMs);
+          this.emit('joined', { gate: this, peers: m.peers.filter(p => typeof p === 'string'), stun: this.stun });
+          break;
+        case 'peer': if (m.room === this.room) this.emit('peer', { gate: this, peer: m.peer, on: !!m.on }); break;
+        case 'recv':
+          if (m.room === this.room && typeof m.from === 'string' && typeof m.box === 'string' && m.box.length <= 49152) {
+            this.counters.received++; this.emit('recv', { gate: this, from: m.from, box: m.box });
+          }
+          break;
+        case 'error':
+          this.counters.errors++; this.emit('gate-error', { gate: this, code: m.code });
+          // After a network change the gate may still hold our previous socket for a moment.
+          if (m.code === 'peer-taken' && this.state !== 'joined' && (this.joinAttempts = (this.joinAttempts ?? 0) + 1) <= 8) {
+            setTimeout(() => { if (ws === this.ws && this.state !== 'joined') this.#raw({ t: 'join', room: this.room, peer: this.peer }); }, 1000 * this.joinAttempts);
+          }
+          break;
+      }
+    };
+    ws.onclose = () => {
+      if (ws !== this.ws) return;
+      clearInterval(this.pinger);
+      this.ws = null; 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.timer = setTimeout(() => { this.timer = 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;
+  }
+  send(to, box) {
+    if (this.state !== 'joined') return false;
+    const ok = this.#raw({ t: 'send', room: this.room, to, box });
+    if (ok) this.counters.sent++;
+    return ok;
+  }
+  close() {
+    this.closed = true; clearTimeout(this.timer); clearInterval(this.pinger);
+    const ws = this.ws; this.ws = null; this.state = 'closed';
+    if (ws) { try { if (ws.readyState === 1) ws.send(JSON.stringify({ t: 'leave', room: this.room })); ws.close(1000); } catch {} }
+  }
+}

package/src/client/ice-urls.mjs

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// Validate one ICE server URI, including host/port syntax; never accept lists in one URI.
+export function validIceUrl(value, kind) {
+  if (typeof value !== 'string' || value.length > 240) return false;
+  const m = /^(stun|stuns|turn|turns):(\[[0-9a-fA-F:.]+\]|[a-zA-Z0-9.-]+)(?::([0-9]{1,5}))?(?:\?transport=(udp|tcp))?$/.exec(value);
+  if (!m || !m[1].startsWith(kind) || kind === 'stun' && m[4] || m[3] && (Number(m[3]) < 1 || Number(m[3]) > 65535)) return false;
+  // Hostnames: dot-separated labels of 1-63 letters, digits or inner hyphens (no empty or edge-hyphen labels).
+  if (!m[2].startsWith('[') && !/^(?=.{1,253}$)([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)(\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.?$/.test(m[2])) return false;
+  try {
+    const url = new URL(`http://${m[2]}:${m[3] ?? 3478}`);
+    return !!url.hostname && !url.username && !url.password;
+  } catch { return false; }
+}
+export const validStunUrls = urls => Array.isArray(urls) && urls.length <= 4 && urls.every(url => validIceUrl(url, 'stun'));