freehop 0.1.0-alpha.0

package/PROTOCOL.md

@@ -0,0 +1,310 @@
+# Freehop protocol, version 1
+
+Freehop connects small groups with audio, video and data. `maxPeers` defaults to eight other participants; larger supported sizes require benchmarks. Its operator invariant:
+**no server that the application operator runs ever carries media.** Media goes peer-to-peer.
+When no direct route exists, it goes through a machine that belongs to the same session —
+a participant, a participant's own gateway or the session's host node. Volunteers may be
+added by configuration. The operator's servers ("gates") only introduce peers.
+
+This document is normative for the wire formats and behaviour. `README.md` covers usage and
+measured results.
+
+## 1. Roles
+
+| Role | Runs on | Carries | Never carries |
+|---|---|---|---|
+| **Gate** | Any server (operator, community, anyone). Any number per room. | Sealed signalling envelopes (opaque bytes), STUN Binding answers | Media, plaintext SDP/candidates/credentials |
+| **Peer** | Browser or desktop renderer (WebRTC) | Its own media, plus forwarded media when bridging (§9) | — |
+| **Gateway** | A peer's own machine (desktop app main process) or the session host node; TURN server + router port mapping | Relayed packets of the session's peers, DTLS-SRTP encrypted end to end | Anything for peers outside its session (credentials are per room and per peer) |
+| **Gateway member** | The session's host node (a participant's desktop app, or a community server hosting the session) | Joins the room through gates without media and offers its gateway | Media of its own |
+
+Cost rule: a byte of media only crosses machines that belong to the call. These are the
+two endpoints, another participant, or the session's own host. The operator's gate count
+is bounded by construction (§4.5) and measured in every lab run.
+
+## 2. Identifiers and keys
+
+- **Room secret**: ≥128 bits, generated by the application's room service when a room is
+  created. It is handed to members together with the room information they already
+  receive. The app need not display it, but members can extract and share it. A share link is a bearer credential.
+- `salt = "peerlane/v1/" + app`, where `app` namespaces applications.
+- `roomTag = base64url(HKDF-SHA256(secret, salt, info="room-tag", 32 bytes))`. This is the
+  only room identifier a gate sees.
+- `envelopeKey = HKDF-SHA256(secret, salt, info="envelope-key")` as an AES-256-GCM key.
+- **Peer id**: 16 random bytes, base64url (22 characters), fresh for every join. Gateway
+  members use ids that start with `gw_` (22 characters in total). The prefix is a hint;
+  their role is only accepted from sealed caps.
+
+Kicking a member means the application issues a new room secret to the remaining members.
+Every remaining member closes old-key links and reconnects under the new secret; previous-key envelopes are rejected immediately. Host nodes and desktop gateways revoke the entire old room epoch, including aliases. Rotation briefly interrupts media. Update every remaining member and host; any machine still using the old secret can communicate with its holders.
+
+## 3. Sealed envelopes
+
+```
+box = base64url( iv[12] || AES-256-GCM(envelopeKey, iv, plaintext, aad) )
+aad = "peerlane/v1|" + roomTag + "|" + from + "|" + to
+plaintext = JSON { kind, n, ...body }
+```
+
+- `to` is the recipient's peer id. The AAD binds room, sender and recipient. A gate that
+  re-labels or re-routes an envelope makes it fail authentication.
+- `n` is a per-sender counter. Receivers keep a 1024-wide replay window per sender and drop
+  duplicates. The same envelope legitimately arrives via several gates and the mesh.
+- Kinds: `caps`, `description`, `candidate`, `bye`, `restart-request`, `video-quality`, `bridge-request`,
+  `bridge-offer`, `bridge-accept`, `bridge-confirm`, `bridge-ready`, `bridge-active`, `bridge-release`, `bridge-fail`,
+  `forward-map`, `forward-unmap`, `app`. Unknown kinds are dropped. `app` carries application data
+  (`session.send`): at most 4096 characters of JSON, and each receiver accepts at most 20 per
+  second from one sender (burst 40). Tracker gates add a
+  room-broadcast `hello` (to `*`).
+- **Adaptive video request.** A receiver that opted in sends `{kind:"video-quality", level:"normal"|"reduced"|"minimal"|"paused"}` to the peer sending video. Requests are sealed peer-to-peer envelopes, ordered by the envelope counter and rate-limited to one accepted change per second. `normal` releases the request; other levels cap or pause video on this link only. Audio is never changed. A peer that did not opt in ignores requests, and older implementations drop the unknown kind.
+- **Admission.** Gate rosters and arrival events are unauthenticated hints. A hint only makes a
+  peer greet the hinted id with its sealed caps, at most once per 20 s and for at most 64
+  hints. A peer becomes a member, with `peer` events, a link and a slot, only after an
+  envelope from it authenticates. A gate cannot authenticate an invented member, but can still prevent discovery or disrupt recovery by dropping traffic. Roster presence alone does not prove membership.
+
+## 4. Gate protocol (WebSocket, UTF-8 JSON text frames)
+
+### 4.1 Messages
+
+| Direction | Message | Notes |
+|---|---|---|
+| C→G | `{"t":"hello","v":1,"auth"?:string}` | Must be the first frame, within 5 s |
+| G→C | `{"t":"welcome","v":1,"stun":[url],"limits":{...}}` | Informational only; clients use application/ticket STUN configuration |
+| C→G | `{"t":"join","room":tag,"peer":id}` | At most 4 rooms per socket |
+| G→C | `{"t":"peers","room":tag,"peers":[id]}` | Current members |
+| G→C | `{"t":"peer","room":tag,"peer":id,"on":bool}` | Arrivals and departures |
+| C→G | `{"t":"send","room":tag,"to":id or "*","box":string}` | The box is opaque base64url |
+| G→C | `{"t":"recv","room":tag,"from":id,"box":string}` | `from` is the socket's own peer id |
+| C→G | `{"t":"leave","room":tag}` / `{"t":"ping"}` | |
+| G→C | `{"t":"error","code":string}` | `schema`, `rate`, `auth`, `auth-expired`, `busy`, `room-full`, `room-not-allowed`, `no-such-peer`, `not-joined`, … |
+
+### 4.2 Admission
+A gate is either open or token-gated. A token is
+`base64url(JSON claims) "." base64url(HMAC-SHA256(gateSecret, body))` with claims
+`{exp, room?, aud}`. A token with `room` may only join that room tag. An application mints room-bound tokens for its admitted members. Tokens require a future safe-integer `exp`, and both parts must be canonical unpadded base64url. An expired socket is closed at its next request, heartbeat or delivery, whichever comes first. A client renews its token for the same epoch with `session.refresh(ticket)`; the new token is used at the next (re)connect.
+
+### 4.3 Multiple gates and tracker gates
+Clients connect to every gate in their list and announce on each. Peers that share no gate
+still meet through the mesh: §6 introduction. Established calls do not depend on any
+gate. Lab evidence shows all gates shut down while media continues.
+
+A gate URL `bt+wss://…` names a public WebTorrent tracker used as a gate.
+- `info_hash` is the first 20 ASCII characters of the hex-encoded, decoded room tag (80 bits of tag material), and `peer_id` is a random
+  20-character ASCII string.
+- Hellos travel as announced offers, `"pl1:<peer id>:<sealed hello>"`. Envelopes travel as
+  answers addressed by `to_peer_id`.
+- A peer's tracker address is bound only after its envelope authenticates. Hellos carry the
+  sender's counter and fall under the replay window.
+
+### 4.4 Liveness and proxies
+- Clients send `{"t":"ping"}` every 30 s, and the gate also pings at the WebSocket level.
+  Each gate ping carries a fresh random nonce; only a pong that echoes it counts as activity.
+- Output the gate has handed to a socket but not yet flushed is bounded: 1 MiB per socket
+  and 32 MiB for the whole gate. Over the gate-wide budget, the receiver that has been
+  behind the longest is closed first.
+- Behind a local reverse proxy (`trustProxy`), per-address limits use the last
+  `X-Forwarded-For` hop.
+- After a network change a join can briefly meet `peer-taken`; clients retry with backoff.
+
+### 4.5 STUN
+A gate may answer RFC 8489 Binding requests on UDP, IPv4 and IPv6. It answers Binding
+only, rate-limits per source address and globally, and never relays.
+
+### 4.6 Bounds
+A gate frame is at most 64 KiB and a box at most 48 KiB. Each socket gets a token bucket
+over the bytes it makes the gate forward, fan-out included: 512 KiB burst, 2 KiB/s
+refill. Each socket is also limited to 40 messages/s (burst 400). Further limits: 16 peers
+per room, 32 sockets per source address (an IPv6 /64 counts as one address), 1024
+admitted sockets, and a 90 s idle timeout. Sockets that have not been admitted yet have
+their own budget (256 in total, 8 per address, 64 frames or 64 KiB queued while admission
+is pending), so silent sockets cannot lock admitted clients out; refused and timed-out
+sockets are torn down within 1 s. These limits make media tunnelling through a gate
+impractical, while one five-peer join needs about 100 KB.
+
+## 5. Capabilities (`caps` envelope)
+
+```
+{ v:1, role?:"gateway", forward:bool, peers:[id], gateway: null |
+  { urls:["turn:host:port?transport=udp", "turn:host:port?transport=tcp"],
+    username, credential, external:[ip], internal: ip|null } }
+```
+- `peers` lists the sender's connected links. It is used for mesh routing and introductions.
+- `forward` means the sender may bridge other pairs (§9).
+- `gateway` holds credentials minted **for the recipient** (§8.2). A gateway member sets
+  `role:"gateway"`.
+
+A peer sends caps to every peer it discovers (through gates), on every new data channel,
+and when its link set changes. It also embeds caps in every `description` envelope.
+
+Gate admission tokens include `aud`, the exact gate URL, and `room`. Tickets carry an `auth` map keyed by URL. Each gate rejects another audience even when signing keys are shared. Behind a reverse proxy configure the public `tokenAudience`. Clients never apply `welcome.stun`; the application or ticket pins its own STUN list.
+
+## 6. Signalling transport
+
+1. Every link carries a pre-negotiated data channel (`negotiated:true, id:0`, label
+   `peerlane`). Once it is open, all envelopes for that peer go over it as
+   `{"t":"env","from","to","box"}`.
+2. Otherwise the envelope is sent through every gate on which the recipient is present.
+3. Otherwise it goes through a connected neighbour whose caps list the recipient:
+   `{"t":"env",...,"hop":1}`. The neighbour forwards it once as `hop:2`, limited to 600
+   per minute per link. This is how peers introduce each other without a common gate.
+4. Otherwise it waits in an outbox: 32 envelopes per peer, for 20 s. The outbox is flushed
+   when the peer appears on a gate or its link opens.
+
+A data channel is trusted alone only while its link is connected. A dead connection's
+channel can read `open` for tens of seconds, so gates carry the envelope as well.
+
+## 7. Path ladder (per pair)
+
+Negotiation follows W3C *perfect negotiation*. The peer with the lexicographically greater
+id is *polite*. A link created to answer an incoming offer suppresses its own first offer.
+A suppressed `negotiationneeded` is re-checked once the state is stable again.
+
+| Phase | ICE servers | Expected route | Leaves the phase when |
+|---|---|---|---|
+| 0 ENDPOINT | Application-approved STUN + own gateway (internal URL) + remote peer's gateway | host/LAN, IPv6, srflx/prflx, or one endpoint's own gateway | not connected 5 s after the description, with one grace period if checks receive answers |
+| 1 SESSION | + gateways of connected participants and of gateway members (max 2 added) | `relay` through a session gateway | 7 s without connection, with one extra 7 s grace period if checks receive answers |
+| 2 BRIDGED | unchanged | media forwarded by a connected participant (§9) | the direct or session route later succeeds |
+| unreachable | unchanged | none (no bridge candidate) | ICE restart retries with exponential backoff (30 s … 300 s) |
+
+- Escalation adds gateways with `setConfiguration`. Only the impolite side restarts ICE.
+  The polite side applies the same servers and takes over after `restartFallbackMs`
+  (2.5 s) if no restart offer arrived. Simultaneous restarts collide, and a rolled-back
+  restart offer was observed to leave Chromium senders silent (lab finding, §12).
+- Descriptions carry `phase` and `gateways` (the ids of extra gateways in use). The receiver
+  adds those servers **before** answering, so both sides gather against the same relays.
+- Candidates for an unknown ICE generation are buffered until the matching description
+  arrives: at most 128, oldest evicted first.
+- Descriptions apply in envelope-counter order. An older one never overtakes a newer one,
+  whatever route each took.
+- An offer that receives no answer within 8 s is rolled back and sent again, and an ICE
+  restart is re-requested, so a lost envelope cannot deadlock the pair.
+- Media watchdog: if a connected link's live track sends no packets for two 5 s checks, it is
+  restarted. The polite side sends `restart-request` instead of restarting itself.
+- Departures: a member that has been absent from every gate for 8 s, and whose link is not
+  connected, is dropped as `gone`. Its replay window is kept, and it may return by
+  authenticating again. `bye` and kicks are final.
+- On `disconnected` the link waits 4 s, then restarts. On `failed` it restarts immediately.
+  Both follow the single-initiator rule.
+
+Path classification uses the selected candidate pair: `direct` (no relay on either side),
+`gateway` (relay owned by one endpoint), `relay` (relay owned by another session member),
+`bridged` (§9) or `unreachable`. A local peer-reflexive candidate whose `relayProtocol` is
+set still rides a relay.
+
+## 8. Gateways
+
+### 8.1 Reachability
+The gateway runs a TURN server (RFC 8656 subset: UDP relay allocations over UDP and TCP
+client transports) on the peer's LAN address. It asks the router for mappings: PCP (RFC 6887),
+then NAT-PMP (RFC 6886), then UPnP IGD v1/v2. It requests the same external port as the internal
+one, for the listener (UDP and TCP) and for each relayed port on demand. A host with a public
+address skips mapping. If the router reports a private or CGNAT external address, the gateway
+is not offered.
+
+### 8.2 Credentials (TURN REST convention, room-scoped)
+`username = "<unix expiry>:<room tag[0..8]>:<label>"`,
+`credential = base64(HMAC-SHA1(secret, username))`. `label` is the recipient's peer id, or
+`self` for the owner's own allocations via the internal URL.
+- The signing key stays in the privileged gateway process. `info()` exposes no key; an origin- and room-checked broker returns bounded credentials to the renderer.
+- The gateway accepts only rooms it was told to serve (`allowRoom`). Individual peers can be
+  revoked on kick or leave (`revokePeer`), which tears down their allocations. A whole room
+  is revoked on key rotation or when the session ends, tearing down every old allocation.
+- Credentials are issued only to authenticated members, never in response to a hint.
+- Default TTL is 2 h, renewed at half-life; configurable from 1 second to 24 hours. The server rejects even correctly signed expiry values beyond that configured horizon.
+- Peer revocations are kept per room (up to 256) until previously minted credentials expire. A room that exceeds its bound is revoked as a whole; other rooms are never affected. A host member only revokes peers it issued credentials to.
+- Revoking a room records a floor: credentials minted before it are refused even if the same room is allowed again later.
+
+### 8.3 Policy and hairpinning
+- **A gateway relays only inside the session.** With its default `relayScope: 'internal'`,
+  a gateway relays only between allocations on itself and refuses every other destination
+  (403). Every path in §7 meets on the same gateway, including the owner's own `self`
+  allocation, so credentials cannot be used to send traffic to other internet hosts.
+  `relayScope: 'public'` restores general-purpose TURN behaviour; use it only when every
+  member is trusted.
+- The TURN server's general peer policy (`peerScope: 'public'`) refuses loopback,
+  link-local, multicast and private peers, plus 6to4, Teredo, local-use NAT64, 192.0.0.0/24,
+  198.18.0.0/15 and site-local prefixes, and unwraps IPv4-mapped, IPv4-translated and NAT64
+  forms before deciding.
+- The gateway machine's own addresses are reachable only relay↔relay. Services on the host
+  stay unreachable.
+- Traffic between two allocations on the same gateway is delivered internally. Many home
+  routers lack NAT hairpinning, and the owner's own `self` allocation therefore reaches
+  remote allocations without it.
+- The TURN server answers unauthenticated UDP at a bounded rate per source and globally, to
+  bound reflection. Binding answers and challenge or error answers have separate global
+  budgets, and addresses that authenticated in the last 10 minutes are exempt from the global
+  budgets (not from their per-source limit), so a flood cannot starve renewals.
+- It bounds TCP connections per source address (16), with a 10 s absolute pre-authentication deadline, unaffected by incoming bytes. A TCP connection closes when its allocation ends.
+- Media stays DTLS-SRTP encrypted end to end. The gateway relays ciphertext.
+
+## 9. Participant bridging
+
+When a pair (A,B) has no route, and no untried session gateway, the lower id asks
+connected participants that report a link to the other peer (`bridge-request`). The first
+`bridge-offer` wins (`bridge-accept`). Forwarder C then:
+
+1. asks B with `bridge-confirm` and waits for its `bridge-ready`; B validates that C is eligible and its A link is still unreachable;
+2. sends `bridge-active` to both endpoints to establish the forwarding relationship;
+3. sends `forward-map {origin, stream}` to each side before renegotiating;
+4. adds the origin's received tracks to its link with the other side, which re-encodes them.
+
+Receivers attribute tracks by stream id. When the direct route later connects, an endpoint sends
+`bridge-release`. C removes the forwarded tracks, stopping their transceivers so SDP does not
+grow, and sends `forward-unmap`. If C leaves or its link drops, the endpoints re-escalate.
+
+Hardening:
+- A forwarder accepts `bridge-accept` only for an offer it made to that endpoint, within
+  30 s, while forwarding is enabled and under its bridge limit.
+- An endpoint accepts `bridge-active` only from the eligible forwarder it already consented to. Unsolicited and conflicting activations are released. Pending second-endpoint consent expires after 30 seconds. All three participants must run this consent handshake; upgrade clients together.
+- `forward-map` is accepted only for an origin the receiver cannot reach itself, and only
+  from that pair's forwarder. A forwarder is a participant of the same call, so it
+already receives both media streams. Bridging exposes nothing new to it. Forwarded video is
+capped at 200 kbit/s.
+
+## 9a. SDK roles
+`SDK.md` describes how applications consume the protocol:
+- an **authority** (application backend) issues per-member **tickets**
+  `{v, app, roomId, epoch, gates, secret, auth?, stun?, expires}` and rotates the room on kick;
+- clients `connect(ticket)` and `update(newTicket, {dropped})`;
+- hosts run `hostSession(ticket)` (gateway member);
+- desktop apps expose their gateway through the Electron preload (`window.freehopGateway`,
+  restricted by exact HTTPS origins (HTTP only on loopback) in both the preload and main-process IPC handlers; subframes are rejected).
+
+## 10. Media profile (defaults)
+- Audio: Opus, echo cancellation, noise suppression and AGC, max 32 kbit/s.
+- Video: 640×360 at up to 24 fps, max 300 kbit/s per link.
+- Muting the microphone disables the track (no renegotiation). Turning the camera off
+  stops the track and replaces it with `null`.
+- Mesh upstream at 5 participants with video ≈ 4 × 332 kbit/s before overhead.
+
+## 11. Security considerations
+- **Gates** learn: socket IP addresses, opaque room tags and peer ids, envelope sizes and
+  timing. They cannot read SDP, ICE candidates, caps or credentials. They cannot forge or
+  re-route envelopes without detection, and cannot inject peers into a room. A hostile gate
+  can drop or delay traffic; using several gates mitigates that.
+- **Room members** are mutually trusted for signalling: any member can forge envelopes in
+  the room's name. Per-peer signatures are a possible v2 addition. Removal requires a secret
+  rotation (§2). SDK ticket expiry does not erase copies of the shared secret or end established media; it is not a replacement for rotation.
+- **Gateways**: credentials are per peer and short-lived. The peer policy prevents use as a
+  proxy into private networks. Quotas: 6 allocations per username, 4 Mbit/s per
+  allocation, 32 allocations and 20 Mbit/s per room, 40 Mbit/s in total, separately per direction; at most 64 allocations overall. Room quotas aggregate every alias in that room; global limits still apply. By default a gateway relays only between allocations on itself, so a member cannot use its credentials to reach other internet hosts (§8.3). Expiry blocks further authenticated requests; existing allocations may continue until their granted lifetime ends. Revocation ends them immediately, and a participant's desktop gateway releases a room when the participant leaves.
+- **IP privacy**: direct paths expose network addresses to other participants. Gate and tracker operators also see connecting IP addresses. The SDK does not provide an IP-anonymity mode.
+
+## 12. Known limits
+- A network that permits traffic only to the gate host cannot carry media without the gate
+  operator carrying it. Freehop reports `unreachable`. A gate operator who *chooses* to also
+  run a gateway (community gates) can serve such users; the application operator's own gates
+  do not.
+- Two browser-only participants that are both behind hard NATs or UDP-blocking networks, with
+  no IPv6, no gateway in the session and no third participant, cannot connect. A session host node reachable by both endpoints can provide a TURN relay path.
+- Chromium, lab finding: simultaneous ICE restarts (glare) intermittently left the polite
+  side's RTP senders silent after its restart offer was rolled back. Freehop avoids
+  simultaneous restarts (§7).
+- Playwright 1.62's WebKit build rejects `?transport=` in TURN URLs (WebKit bug 320931). The
+  client detects this and degrades to UDP-only TURN URLs for that engine.
+- Desktop apps can alternatively pin WebRTC's UDP port range
+  (`webContents.setWebRTCUDPPortRange`, Electron ≥ 28) and map it directly. Freehop's
+  gateway approach needs no Chromium cooperation.
+
+---
+Documentation licensed under CC BY 4.0. Copyright 2026 Jolyn Studios. Provided as is, without warranty of any kind.

package/README.md

@@ -0,0 +1,221 @@
+<div align="center">
+
+# Freehop
+
+### Voice and video between your users, without your servers carrying the call.
+
+**[Live demo](https://jolynstudios.github.io/freehop/demo)** ·
+**[Documentation](https://jolynstudios.github.io/freehop/)** ·
+**[Quickstart](#quickstart)** ·
+**[Architecture](ARCHITECTURE.md)** ·
+**[Protocol](PROTOCOL.md)**
+
+![License: Apache-2.0](https://img.shields.io/badge/code-Apache--2.0-303055)
+![Docs: CC BY 4.0](https://img.shields.io/badge/docs-CC%20BY%204.0-303055)
+![Original lab matrix: 40/40](https://img.shields.io/badge/original%20lab%20matrix-40%2F40-096e72)
+![Unit tests: 151/151](https://img.shields.io/badge/unit%20tests-151%2F151-096e72)
+![Status: alpha](https://img.shields.io/badge/status-alpha-ef3b2c)
+
+</div>
+
+---
+
+Adding voice or video to a game or app comes with a hidden bill. WebRTC connects people
+directly when it can. When it can't, because of strict NATs or firewalls that block UDP, the
+standard answer is a **TURN relay that you run and pay for**. Every byte of those calls flows
+through your servers. Historical measurements from 2015–2017 found relay use in roughly one fifth of calls or conferences on those services; they are not a current prediction
+([callstats.io: ~22%](https://webrtchacks.com/usage-stats/),
+[appear.in: ~17.7%](https://medium.com/@fippo/what-kind-of-turn-server-is-being-used-d67dbfc2ff5d)),
+and managed TURN is billed per gigabyte (e.g.
+[$0.05/GB](https://developers.cloudflare.com/realtime/turn/)).
+
+**Freehop removes your servers from the media path entirely.** Your infrastructure only runs
+small *gates* that introduce people to each other: tens of kilobytes of sealed signalling per
+call, plus presence announcements and connection recovery. When a direct connection is impossible, the call hops through machines that
+**already belong to the session**: a desktop participant's own router-mapped gateway, the machine
+hosting the session, or another participant. The cost of a call stays with the people on it.
+
+## Why Freehop
+
+| | |
+|---|---|
+| 💸 **Zero media on your servers** | Gates carry sealed signalling only. In every lab run, gate traffic for an entire scenario stayed between 30 and 210 KB, with no media at all. |
+| 🧱 **Connects the "impossible" pairs** | Two strict (symmetric) NATs, or a network that blocks UDP, can't connect directly. Freehop routes them through a session member's gateway or the session host, still with no operator relay. |
+| 🛰️ **No single point of failure** | Run one gate or many, operated by you, your community, or public WebTorrent trackers. Peers on different gates still find each other. **Calls keep running when every gate is down.** |
+| 🔐 **Private by construction** | Signalling is sealed (HKDF + AES-256-GCM), so gates can't read or forge envelopes. Direct and gateway paths preserve end-to-end DTLS-SRTP; a forwarding participant decodes and re-encodes media. |
+| ⚙️ **Automatic** | No manual room link is required in a ticket-based integration. Your backend issues a ticket, and the SDK takes the cheapest path that works: direct, then gateway, then relay, then bridge. |
+| 📦 **Small and open** | Zero-dependency browser client; a gate with one dependency (`ws`); TURN gateway and PCP / NAT-PMP / UPnP port mapping in plain Node. Apache-2.0. |
+
+## How it works
+
+```mermaid
+flowchart LR
+  subgraph session["One session (a call)"]
+    A["🏠 Participant A<br/>(browser)"]
+    B["🏠 Participant B<br/>(phone, strict NAT)"]
+    H["🗼 Host node or<br/>desktop gateway"]
+  end
+  G["📮 Gate<br/>(your server)"]
+  A -. "sealed envelopes (KB)" .-> G
+  B -. "sealed envelopes (KB)" .-> G
+  A == "media: direct when possible" ==> B
+  A == "or via a session gateway" ==> H
+  H ==> B
+```
+
+1. **Your backend issues tickets.** `createAuthority()` owns each room's secret. A member gets a ticket over your own authenticated channel.
+2. **Gates introduce.** Clients announce on every gate in the ticket and exchange sealed envelopes. Once linked, signalling moves onto the peers' own data channels. A gate can be your own small server or a public WebTorrent tracker: the envelopes ride in the offer and answer messages that trackers already pass between browsers ([how](https://jolynstudios.github.io/freehop/docs/concepts/trackers)).
+3. **The path ladder finds a route.** Freehop tries direct first (LAN, IPv6, STUN). If that fails it uses an endpoint's own gateway, then a gateway of another session member, then forwarding through a participant. A failure is reported honestly as `unreachable`.
+4. **Kicks rotate keys.** `authority.kick()` issues a new room secret; remaining members `update()` and drop the kicked peer.
+
+## Proof, not promises
+
+The original qualification ran in an isolated Linux lab with real **Chromium 151, Firefox 153 and WebKit 26.5**.
+Each browser sits behind its own kernel NAT router profile, with fake camera and microphone.
+Every run asserts the path taken and that audio *and* video actually arrive.
+
+| Network situation | Result | Route Freehop chose |
+|---|---|---|
+| Two home routers | ✅ 3/3 | direct |
+| IPv6 available, IPv4 UDP blocked | ✅ 3/3 (+ Firefox/WebKit) | direct over IPv6 |
+| Two strict/symmetric NATs + a third participant | ✅ 3/3 (+ cross-browser) | forwarded by the participant |
+| Strict NAT ↔ desktop participant behind a UPnP router | ✅ 3/3 (+ cross-browser) | the desktop's own gateway |
+| Two strict NATs + a desktop participant | ✅ 3/3 (+ cross-browser) | relay through that participant's gateway |
+| UDP-blocking firewall ↔ desktop participant | ✅ 3/3 (+ cross-browser) | gateway over TCP |
+| Two UDP-blocked peers + a desktop participant | ✅ 3/3 | relay over TCP |
+| Two strict NATs, session hosted on a server node | ✅ 3/3 (+ cross-browser) | the host node's gateway |
+| Two UDP-blocked peers, server-hosted session | ✅ 3/3 | the host node's gateway |
+| Two strict NATs and nobody else | ✅ 3/3 | `unreachable` (correctly reported) |
+| A network that can only reach the gate | ✅ 3/3 | `unreachable` (no route exists without your server) |
+
+**40/40 lab runs passed** on the current revision, re-run on 2 October 2026 after security hardening, including gateways that relay only inside their session. Other checks:
+- **151/151 unit tests**, including the RFC 5769 STUN vectors and the security regressions.
+- **coturn's own test client** against Freehop's TURN server: 800/800 messages over UDP and 800/800 over TCP, 0 lost.
+- **Browser suites:** multi-gate with every gate shut down mid-call, kick/rekey, a public WebTorrent tracker as the only gate, and the SDK example app.
+
+Full details are in [RESULTS.md](RESULTS.md).
+
+## Example consumer: Redline Wars
+
+[**Redline Wars**](https://redlinewars.online) is a real-time strategy game that runs in the
+browser and as a desktop app ([source](https://github.com/jolynstudios/redlinewars)). It is
+one planned consumer of Freehop. The game is integrating the independent SDK
+**through the public SDK only**, exactly like any other app would:
+
+- the match host acts as the session's gateway;
+- desktop participants open their own front door through their router;
+- browser participants simply join.
+
+Freehop is an independent project; any app can use the same public SDK.
+
+## Quickstart
+
+```bash
+npm install github:jolynstudios/freehop    # npm registry release follows with 1.0
+```
+
+**Backend:** decide who is in a room.
+```js
+import { createAuthority } from 'freehop/authority';
+const authority = createAuthority({
+  app: 'my-app',
+  gates: ['wss://example.com/freehop'],
+  gateTokenSecrets: { 'wss://example.com/freehop': process.env.FREEHOP_GATE_TOKEN_SECRET },
+  stun: ['stun:example.com:3478']
+});
+await authority.openRoom('room-42');
+const ticket = await authority.ticket('room-42', userId);   // send over your own channel
+```
+
+**Client:** join the call.
+```js
+import { connect } from 'freehop';
+const session = await connect(ticket, { media: { audio: true } });
+session.on('track', ({ peer, track }) => session.attach(track, audioElementFor(peer)));
+session.on('path', ({ peer, kind }) => console.log(peer, 'is', kind));  // direct | gateway | relay | bridged | unreachable
+```
+
+**Gate:** the signalling service. Set `FREEHOP_GATE_TOKEN_SECRET` to the same private signing key (at least 32 characters) in the backend and gate environments, and put the gate behind your TLS proxy.
+```bash
+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_SECRET" \
+FREEHOP_GATE_TOKEN_AUDIENCE=wss://example.com/freehop \
+FREEHOP_GATE_TRUST_PROXY=1 ./node_modules/.bin/freehop-gate
+```
+Run the installed copy, not `npx freehop-gate`: Freehop is not on npm, so npx could fetch a stranger's package and hand it your token secret.
+
+Desktop apps (Electron) and session hosts get one call each. See [SDK.md](SDK.md). For a
+complete runnable consumer, run `npm run example` and open it in two windows. Existing integrations should follow the [security model](PROTOCOL.md): gateway credentials now come from a privileged broker, tokens name their gate, and STUN servers come from application configuration. Use `authority.kick()` for membership revocation; `disconnectPeer()` is local removal only.
+
+## How Freehop compares
+
+Every option below can put people in a call. What differs is where the audio and video go when
+two people cannot connect directly, and who pays for that traffic.
+
+| Option | What it is | When a direct route fails, media goes through | Your media bill | Built for | License |
+|---|---|---|---|---|---|
+| **Freehop** | Peer-to-peer SDK plus small signalling gates | Machines in the session: a participant's desktop gateway, the host node, or a forwarding participant | **No operator media bill; session machines carry the traffic** | 2 to 8 people (mesh) | Apache-2.0 |
+| WebRTC + your own TURN | The browser API, plus the servers you build (e.g. coturn) | Your TURN server | Every relayed byte | Small groups (mesh), more with an SFU you add | coturn: BSD-3-Clause |
+| [PeerJS](https://peerjs.com) | Library for one-to-one connections by peer id, with PeerServer signalling | A TURN server you supply; its free TURN service closed in December 2023 | Yours, once you add TURN | One-to-one; groups are a mesh you build | MIT |
+| [Trystero](https://github.com/dmotz/trystero) | Serverless peer-to-peer matchmaking library | A TURN server you add; without one, hard-NAT pairs fail | Yours, once you add TURN | Small groups (mesh) | MIT |
+| [LiveKit](https://livekit.io) | Open-source SFU server and SDKs, or LiveKit Cloud | Every stream goes through the SFU, with built-in TURN | Your servers' bandwidth, or Cloud pricing per minute and GB | Large rooms, livestreams, AI agents | Apache-2.0 |
+| [Jitsi Meet](https://jitsi.org) | Complete meeting app: Videobridge SFU with XMPP signalling | With 2 people it tries a direct link; with 3 or more, every stream goes through the Videobridge | Your servers' bandwidth, or 8x8's hosted JaaS | Meetings with dozens of people | Apache-2.0 |
+| [mediasoup](https://mediasoup.org) | SFU library for Node.js or Rust, with a C++ media worker | Always your SFU server | Your servers' bandwidth | Large rooms you build yourself | ISC |
+| Hosted video APIs | Daily, Agora, Twilio Video, Cloudflare Realtime and others | The provider's servers: most send every stream through them | Per participant-minute, or per GB (Cloudflare) | Large rooms, nothing to run | Proprietary |
+
+Freehop is built for products where **people in the session can help carry their own call**:
+games, small-group voice and video, communities. If you need 50-person rooms, recording, or a
+guarantee on networks that block everything except your server, an SFU or a paid relay is the
+right tool. The [full comparison](https://jolynstudios.github.io/freehop/docs/comparison) adds
+signalling and encryption, with sources.
+
+## Honest limits
+
+- **Room size needs admission control.** The initial target is rooms of 2 to 8 people; eight was chosen for that target, not established by a capacity benchmark. The SDK's
+  `limits.maxPeers` defaults to 8 remote peers per client; it is not a room-size cap.
+  Your backend must limit membership before issuing tickets. Excess peers are silently
+  ignored, which can leave a larger room only partly connected.
+- **Unrouteable networks.** A network that lets a user reach *only* your gate has no route
+  for media without your server carrying it. Freehop reports `unreachable` instead of
+  silently paying for a relay.
+- **Hard NATs need someone with a reachable route.** Two browser-only users, both behind
+  strict NATs or UDP-blocking networks, with no IPv6 and nobody else in the session, cannot
+  connect.
+- **Lab-qualified, not field-proven yet.** Real ISPs, 4G/5G carrier NAT, corporate networks
+  and mobile browsers are being tested next. Status: **alpha**.
+- **Forwarded media is re-encoded.** When a participant forwards the call, it re-encodes the
+  media. That participant is in the call anyway.
+
+## Repository map
+
+| Path | What |
+|---|---|
+| `src/client/` | Browser client: rooms, sealed signalling, path ladder, bridging, media |
+| `src/sdk/` | SDK: `authority` (backend), `connect` (client), `host`, tickets |
+| `src/gate/` + `bin/freehop-gate.mjs` | Gate service with optional STUN |
+| `src/relay/` | TURN gateway, PCP / NAT-PMP / UPnP port mapper, host-node member |
+| `src/electron/` | Desktop helper (main + preload) |
+| `examples/minimal/` | A complete reference app |
+| `lab/` | Disposable Linux NAT lab that reproduces every result |
+| `website/` | The documentation site (Docusaurus) |
+
+## Get involved
+
+- ⭐ **Star the repo** to follow progress toward the field-tested 1.0.
+- 🎮 **Try the [live demo](https://jolynstudios.github.io/freehop/demo)**: a real call between two
+  browser tabs, introduced through public trackers with no server of ours.
+- 🛠️ **Building a game or app on Freehop?** [Open an issue](https://github.com/jolynstudios/freehop/issues)
+  and tell us about your use case. Integration reports directly shape the SDK.
+
+## License and warranty
+
+- Code: **Apache License 2.0** ([LICENSE](LICENSE)).
+- Documentation and protocol specification: **CC BY 4.0** ([LICENSE-docs](LICENSE-docs)).
+- Attributions: [NOTICE](NOTICE).
+
+> **No warranty.** Freehop is provided "as is", without warranties or conditions of any kind.
+> You use it entirely at your own risk.
+
+Copyright 2026 Jolyn Studios. Freehop was developed under the codename *Peerlane*; some protocol
+identifiers keep that name.