@displayxr/inline3d 1.47.5 → 1.48.0

package/signaling/README.md

@@ -0,0 +1,289 @@
+# `dxr-signal/1` — signalling for `@displayxr/inline3d/call`
+
+A small JSON-over-WebSocket protocol that gets up to four browsers into the same call and relays
+their WebRTC offers, answers and ICE candidates. It never carries media (that is peer-to-peer,
+DTLS-SRTP) and keeps nothing once a room is empty.
+
+| File | What |
+|---|---|
+| [`room.mjs`](room.mjs) | The room logic. Shared as-is by both servers below, so they cannot drift. |
+| [`gate.mjs`](gate.mjs) | Admission for one connect: key + origin ([`keys.mjs`](keys.mjs)), blocklist, join rate + room leases ([`limits.mjs`](limits.mjs)), the TURN budget ([`turn-budget.mjs`](turn-budget.mjs)). Shared too. |
+| [`worker.mjs`](worker.mjs) + [`wrangler.toml`](wrangler.toml) | Reference server: a Cloudflare Worker + Durable Objects (one per room, hibernating WebSockets; one per rate-limit subject; one budget) + a KV namespace for keys. The template is for self-hosting; [`deploy/displayxr.toml`](deploy/displayxr.toml) is the hosted DisplayXR instance and [`deploy/staging.toml`](deploy/staging.toml) its staging twin. |
+| [`dev-server.mjs`](dev-server.mjs) | A zero-dependency Node server with the same protocol **and the same admission** (limits, keys, budget — in memory), for local work and the test suite. Not for production. |
+| [`../tools/signal-keys.mjs`](../tools/signal-keys.mjs) | Issue / revoke / list publishable keys and block IPs, by hand, through `wrangler kv`. |
+
+Client side: `dxrSignaling(url, { key })` in [`js/call/signaling.js`](../js/call/signaling.js). Any
+other transport can be plugged into `addCall` by implementing the `SignalingAdapter` interface
+(`call.d.ts`); this protocol is just the one the SDK ships.
+
+**Hosted instance:** `wss://signal.displayxr.org` (the SDK's default since the release after
+1.32.0), with `wss://dxr-signal.displayxr.workers.dev` kept as an alias through the transition
+([`docs/signaling-domain.md`](../docs/signaling-domain.md)); the same Worker answers on every host
+and the SDK fails over between them (`DXR_SIGNAL_ALIASES` in
+`js/call/signaling.js`, internal). What it sees and
+keeps: [`docs/privacy-call.md`](../docs/privacy-call.md).
+
+## Local development
+
+```sh
+node signaling/dev-server.mjs            # ws://localhost:8787 (flags: --port, --host, --cap, --keys keys.json)
+python3 -m http.server 8000              # from the repo root
+# open http://localhost:8000/samples/call/ (the sample defaults to ws://localhost:8787 on localhost)
+```
+
+### From the npm package
+
+The dev server ships in `@displayxr/inline3d` (since 1.48) as `signaling/dev-server.mjs` plus the
+five modules it imports (`room`, `limits`, `turn-budget`, `keys`, `gate`). It is **not** an
+`exports` entry: run it by path, or copy the six files as they are.
+
+```sh
+node node_modules/@displayxr/inline3d/signaling/dev-server.mjs --port 8787
+```
+
+```js
+// programmatic (an app's dev script, a test harness)
+// By FILE path: `exports` does not list it, so Node refuses the bare
+// '@displayxr/inline3d/signaling/…' specifier (ERR_PACKAGE_PATH_NOT_EXPORTED).
+import { startDevServer } from './node_modules/@displayxr/inline3d/signaling/dev-server.mjs';
+const server = await startDevServer({ port: 8787, host: '127.0.0.1' }); // resolves once listening
+console.log(server.url); // ws://127.0.0.1:8787 — pass it to dxrSignaling()
+await server.close();
+```
+
+**Never bundle it.** The file starts the CLI when it is the script Node was started with
+(`import.meta.url === argv[1]`); a bundler inlining it into another script breaks that check and
+its relative imports. Keep it as separate, unbundled `.mjs` files (mark it external, or copy the
+six files), and import `startDevServer` from it by file path.
+
+`getUserMedia` needs a secure context: `localhost` counts; a LAN IP over plain `http` does not.
+The dev server applies the same limits as the hosted server (env vars below); for a flood test
+set e.g. `ANON_JOINS_PER_MIN=3`.
+
+## Protocol
+
+**Connect** to `<base>/v1/connect?k=<key>[&key=<pk_…>]`, where `k` is the lowercase hex SHA-256 of
+the room id and `key` an optional publishable key (§ *Access*). The room itself never appears in a
+URL (and so never in an access log): it travels in the `join` message, and the server checks it
+against the hash it was addressed by. The client's invite link carries the room in its `#room=`
+fragment, which browsers never send to any server.
+
+Every message is one JSON object with a `t` field.
+
+### Client → server
+
+| `t` | Fields | Meaning |
+|---|---|---|
+| `join` | `v: 1`, `room`, `id`, `max?` | Join `room` (16–64 base64url chars; generated rooms are 22 chars = 128 random bits) as peer `id` (8–32 base64url chars, chosen by the client, stable across reconnects). `max` = the room size the first joiner asks for, clamped to the server's cap. One join per connection. |
+| `signal` | `to`, `data` | Relay `data` (an opaque object: offer / answer / candidate / restart / bye) to peer `to` in the same room. |
+| `leave` | — | Leave; the server closes the socket. Closing the socket is equivalent. |
+| `ping` | — | Keep-alive (the client sends one every 20 s). |
+
+### Server → client
+
+**Ordering.** `welcome` is the first message a joined peer receives. The server may need a network
+round-trip between accepting a join and answering it (minting TURN credentials), and other peers can
+join or signal in that window; anything addressed to the joining peer is held and delivered, in
+order, right behind its welcome. `welcome.peers` is the room as the welcome is sent, so it includes
+peers that joined during that window. A client may therefore treat the first message on a socket as
+the outcome of its join (`welcome`, `full`, or `error`).
+
+| `t` | Fields | Meaning |
+|---|---|---|
+| `welcome` | `v: 1`, `id`, `peers: string[]`, `max`, `iceServers?`, `tier`, `key?`, `turn` | Joined. `peers` are the ids already in the room. `iceServers` = short-lived TURN credentials, when the server minted some for this session. `tier` = `'anon'` or `'key'`; `key` = the key id this session is attributed to; `turn` = `{ status, reason?, ttl? }` — the service-wide relay-budget state (`ok` / `degraded` / `off`) and, when there are no credentials, why: `unconfigured` (no TURN on this server), `budget` (anonymous session shed near the budget), `rate` (too many mints from this address), `cap` (the monthly cap — everyone), `mint-failed`. |
+| `full` | `max` | The room already has `max` peers. The server closes the socket (4003). |
+| `expired` | — | The room's lifetime is up (2 h anonymous / 8 h keyed, from its first join). The server closes every peer's socket (4004). Media already flowing is not touched. |
+| `peer-joined` | `id` | Someone joined after you — i.e. someone who is **not** in your `welcome.peers`. Each pair hears of the other exactly once: through one side's roster or the other side's `peer-joined`, never both. |
+| `peer-left` | `id` | Someone left (or their socket dropped). |
+| `signal` | `from`, `data` | Relayed from `from`. |
+| `pong` | — | Reply to `ping`. |
+| `error` | `code`, `message`, `retryMs?` | See the table below. |
+
+| `error.code` | When | Closes the socket with |
+|---|---|---|
+| `bad-message`, `bad-version`, `bad-room`, `bad-id`, `id-taken`, `too-big` | the join or a message is malformed / cannot be honoured | 4000 (`bad-message`, `too-big`, `not-joined`, `already-joined`, `no-such-peer` do not close) |
+| `rate-limited` | more than 300 messages in 10 s on one connection (4000); **or**, at connect, more joins per minute from this address than the tier allows — `retryMs` says when the window reopens | 4029 |
+| `quota` | at connect: this address (anonymous) or this key already has its maximum number of open rooms | 4030 |
+| `bad-key` | `?key=` is malformed, unknown or revoked | 4001 |
+| `origin-not-allowed` | the key exists but the page's `Origin` is not on its list (a non-browser client with no `Origin` never matches a key with a list) | 4001 |
+| `blocked` | the address is on the blocklist | 4040 |
+
+A refused connect is still a real WebSocket for a moment: the server accepts it, sends the one
+`error`, and closes with the code above — so a client always learns why, never hangs.
+
+### What the SDK puts in `signal.data`
+
+Informational — the server does not look inside. `{ kind: 'offer' | 'answer', sdp, gen }`,
+`{ kind: 'candidate', candidate, gen }`, `{ kind: 'restart', gen }` (the answerer asks the offerer
+to rebuild), `{ kind: 'bye', gen }`. Of each pair, the lexically smaller peer id is the offerer;
+`gen` is the connection generation, so a late candidate from a rebuilt connection is dropped.
+
+### Reconnects
+
+If the signalling socket drops mid-call, the client reconnects with backoff and re-joins with the
+**same** `id`. Media already flowing peer-to-peer is not interrupted: a pair whose connection is
+still up survives a `peer-left` from the server, and a pair that was also cut is rebuilt once
+both sides are back. A `rate-limited` / `quota` refusal on a reconnect is retried no sooner than
+its `retryMs`; `bad-key`, `origin-not-allowed`, `blocked` and `expired` end the session.
+
+## Access: anonymous tier and publishable keys (RFC 0003 §5a)
+
+| | Anonymous (no key) | Publishable key `pk_…` |
+|---|---|---|
+| Who | demos, localhost, the playground, first five minutes | a page that ships |
+| Origin check | none | the key's origin list, checked on `Origin` at connect |
+| TURN | yes, 600 s credentials, first to be shed under budget pressure | yes, 3600 s |
+| Limits | tight (below) | 10× the anonymous limits; adjustable per key |
+| Obtain | nothing | issued by hand (`tools/signal-keys.mjs`), revocable |
+
+A key is **public** (it sits in page source): attribution + a quota bucket + an origin binding
+that browsers enforce. A non-browser client can forge `Origin`, which is why quotas, not the key,
+are the actual protection. No secret ever goes in a client. Every session carries its key id, so
+usage is attributable per key from day one (billing identity; billing is off).
+
+Key records live in the Worker's `KEYS` KV namespace as `key:<pk_…>` → JSON:
+
+```json
+{ "id": "pk_…", "origins": ["https://app.example", "https://*.example.com", "http://localhost"],
+  "note": "Acme storefront", "createdAt": "2026-10-03T…", "revoked": false,
+  "limits": { "rooms": 100, "joinsPerMin": 400, "mintsPerHour": 600, "turnTtl": 7200, "roomTtlS": 43200 } }
+```
+
+Origins: exact; one-label wildcard (`https://*.example.com`); `http://localhost` / `http://127.0.0.1`
+(any port); `*` (any origin — attribution only). `limits` overrides the keyed tier's numbers for
+that key alone. KV is eventually consistent (~60 s).
+
+**Admin recipe (by hand):**
+
+```sh
+node tools/signal-keys.mjs issue --origins https://app.example,https://*.example.com --note "Acme"   # prints pk_…
+node tools/signal-keys.mjs revoke pk_…
+node tools/signal-keys.mjs list
+node tools/signal-keys.mjs block 203.0.113.9          # IP blocklist (abuse)
+# --env staging for the staging Worker; needs a logged-in wrangler, nothing else
+```
+
+The same records are reachable over HTTPS when the Worker has an `ADMIN_TOKEN` secret:
+`GET|PUT|DELETE /admin/keys/<pk_…>` with `Authorization: Bearer <token>`.
+
+## Limits (RFC 0003 §5b)
+
+| Limit | Anonymous | Keyed | Where it is counted | Env var |
+|---|---|---|---|---|
+| Joins per IP per minute | 20 | 200 | per-IP meter (separate windows per tier) | `ANON_JOINS_PER_MIN` / `KEY_JOINS_PER_MIN` |
+| Concurrent rooms | 5 per IP | 50 per key | per-IP / per-key meter (leases, expire by themselves) | `ANON_ROOMS` / `KEY_ROOMS` |
+| Room size | 4 (`MAX_PEERS`) | 4 | room | `MAX_PEERS` |
+| Room lifetime | 2 h → `expired` | 8 h | room (alarm, from the first joiner's tier) | `ANON_ROOM_TTL` / `KEY_ROOM_TTL` (seconds) |
+| TURN credential mints per IP per hour | 30 | 300 | per-IP meter (over it: the session joins STUN-only, `turn.reason = 'rate'`) | `ANON_MINTS_PER_HOUR` / `KEY_MINTS_PER_HOUR` |
+| TURN credential TTL | 600 s | 3600 s | — | `ANON_TURN_TTL` / `TURN_TTL` |
+| Messages per connection | 300 / 10 s | same | room | — |
+| Message size | 64 KiB | same | room | — |
+
+IPs are never stored: rate-limit state is keyed by a salted SHA-256 prefix of the address
+(`RATE_SALT`). The Node server also drops a socket idle for 60 s.
+
+## TURN budget and the monthly cap (RFC 0003 §5c)
+
+Only the ~10–20 % of calls that cannot go peer-to-peer use TURN, and TURN is the only real cost.
+The service meters it and enforces an org-wide monthly ceiling: the free tier
+(`TURN_FREE_GB`, 1000 GB) plus a **hard cap of `TURN_CAP_USD` = $100** beyond it at
+`TURN_PRICE_PER_GB` ($0.05) — **3000 GB a month** by default. Against that budget:
+
+| Month's usage | Status | Anonymous sessions | Keyed sessions |
+|---|---|---|---|
+| < 70 % | `ok` | TURN, 600 s | TURN, 3600 s |
+| 70 – 90 % | `degraded` | TURN, 300 s, 5 mints / IP / h | TURN, 3600 s |
+| 90 – 100 % | `degraded` | **no TURN** (`turn.reason = 'budget'`) → SDK `warning` `turn-shed` | TURN, 3600 s |
+| ≥ 100 % | `off` | **no TURN** (`turn.reason = 'cap'`) → SDK `error` `turn-cap` | **no TURN** (`cap`) → `turn-cap` |
+
+Direct P2P keeps working throughout — the welcome simply carries no `iceServers` — and relays
+already allocated run until their credentials expire. The health endpoint reports
+`turn: "ok" | "degraded" | "off" | "unconfigured"`.
+
+**How the usage figure is read.** Two figures exist, and the service uses the better one it has:
+
+- **Estimated** (always): every mint records `(key, ttl)`; `estimatedGB = Σ ttl-hours ×
+  TURN_EST_GB_PER_TTL_HOUR` (default 0.3 GB, ≈ 15 % of sessions relaying ~3.5 Mbps both ways).
+  Crude on purpose: a credential may relay nothing, or for its whole TTL.
+- **Actual** (when configured): Cloudflare exposes relay bytes per TURN key and per
+  `customIdentifier` through the GraphQL analytics dataset `callsTurnUsageAdaptiveGroups`
+  (`sum { egressBytes ingressBytes }`, filter `keyId`, `date_geq/date_leq`). Every credential is
+  minted with `customIdentifier = <key id | anon>`, so the figure is per key. The Worker's hourly
+  cron (`17 * * * *`) polls it and stores month-to-date GB in the Budget object; a figure younger
+  than 3 h is what counts, else the estimate. Needs two secrets: `CF_ANALYTICS_API_TOKEN` (an API
+  token with *Account Analytics: Read*) and `CF_ACCOUNT_ID`. `POST /admin/analytics` polls now.
+- **Override** (operator / tests): `POST /admin/usage {"overrideGB": 2850}` (or the
+  `TURN_FORCE_USAGE_GB` var) beats both; `{"overrideGB": null}` clears it. `GET /admin/usage`
+  shows everything: `usedGB`, `source`, `estimatedGB`, `actualGB`, `fraction`, `status`, and the
+  per-key month (`joins`, `mints`, `ttlSeconds`, `actualGB`).
+
+Usage is aggregated **per key and per month** — the business model's billing identity — while
+billing itself is off. Nothing here charges anyone.
+
+## Cloudflare deployment (template)
+
+1. Copy `wrangler.toml`, set `name` (and routes / a custom domain) for your account. Create the
+   KV namespace (`wrangler kv namespace create dxr-signal-keys`) and paste its id, or drop the
+   `[[kv_namespaces]]` block for an anonymous-only server.
+2. Optional: set `ALLOWED_ORIGINS` to the origins of your pages (comma-separated) — a
+   deployment-wide allowlist on top of per-key origins.
+3. Optional TURN (≈10–20 % of networks need a relay), with [Cloudflare Realtime TURN](https://developers.cloudflare.com/realtime/turn/):
+   - `TURN_KEY_ID` — the TURN key's id (a var or a secret).
+   - `TURN_KEY_API_TOKEN` — its API token. **A secret:** `wrangler secret put TURN_KEY_API_TOKEN`.
+     Never in `wrangler.toml`, never in a client.
+   - `TURN_TTL` / `ANON_TURN_TTL` — credential lifetimes (60–86400 s).
+
+   Each admitted `join` makes the Worker mint credentials
+   (`POST /v1/turn/keys/<id>/credentials/generate-ice-servers`, with `customIdentifier` = the key
+   id) and return them in `welcome`. The same variables work for `dev-server.mjs`.
+4. Optional: `wrangler secret put ADMIN_TOKEN` (the `/admin/*` surface), `RATE_SALT`,
+   `CF_ANALYTICS_API_TOKEN` + `CF_ACCOUNT_ID` (real usage).
+5. `wrangler deploy`, then `dxrSignaling('wss://<your-worker-host>')`.
+
+Health: `GET /` → `{ ok, protocol, turn, keys, limits }`.
+
+## Self-hosting
+
+Self-hosting is first-class and always free (RFC 0003 §5f):
+
+- **Cloudflare**, as above — your account, your TURN key, your limits (every var in
+  `wrangler.toml`), your keys. The $100 cap is just a number (`TURN_CAP_USD`).
+- **Node**, `node signaling/dev-server.mjs` — the same protocol and limits in one process, rooms
+  and counters in memory, no TLS (put it behind a TLS-terminating proxy: `wss://` is required from
+  an `https://` page). Fine for a small deployment; not multi-process.
+- **No TURN at all** (`TURN_KEY_ID` unset): everything works for the ~80–90 % of pairs that can
+  connect directly; the rest show as `unreachable` after ~10 s. The welcome says
+  `turn: { status: 'off', reason: 'unconfigured' }` and the SDK emits nothing for it.
+- **Bring your own TURN (coturn)** — hand the credentials to the widget instead of the server:
+  ```sh
+  # coturn, static-auth-secret mode (TURN REST API): the server mints time-limited credentials.
+  apt install coturn
+  cat >/etc/turnserver.conf <<'EOF'
+  listening-port=3478
+  tls-listening-port=5349
+  realm=turn.example.com
+  use-auth-secret
+  static-auth-secret=<a long random secret>
+  cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
+  pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem
+  fingerprint
+  no-multicast-peers
+  EOF
+  ```
+  Mint credentials in your backend (never in the page): `username = <expiry unix ts>:<anything>`,
+  `credential = base64(HMAC-SHA1(static-auth-secret, username))`, and pass them to the widget as
+  `iceServers: [{ urls: ['turn:turn.example.com:3478', 'turns:turn.example.com:5349'], username, credential }]`
+  (`mountCall(el, { iceServers })`; they override whatever the signalling server hands out). Or
+  plug the same minting into `room.mjs`'s `iceServers` hook if you run the Node server.
+
+**`dxr-signal/1` freezes at the `/call` stable gate** (RFC 0003 §7): self-hosters depend on it
+independently of the SDK version. Until then, additions are new optional fields only.
+
+## Staging and the C3 gate
+
+`deploy/staging.toml` is the hosted server's twin (`wss://dxr-signal-staging.displayxr.workers.dev`):
+own Durable Objects, own KV, and `TURN_FAKE = "1"` — dummy TURN credentials without any token, so
+the whole mint / meter / budget path runs. `test/e2e/signal-staging.e2e.mjs` is the RFC 0003 §7
+C3 gate against it (join flood → `rate-limited`, forced 90 % → anonymous shed only, forced cap →
+`turn-cap` with a direct headless call still connecting, optional forced relay). It needs the
+staging `ADMIN_TOKEN`.

package/signaling/dev-server.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+// signaling/dev-server.mjs — a zero-dependency Node server for the `dxr-signal/1` protocol, for
+// local development and the test suite. Same room logic (./room.mjs) and the same admission —
+// keys, rate limits, room leases, the TURN budget (./gate.mjs) — as the Cloudflare Worker; only
+// the socket plumbing and where the counters live differ. NOT for production: one process, rooms
+// and counters in memory, no TLS.
+//
+//   node signaling/dev-server.mjs [--port 8787] [--cap 4] [--keys keys.json]
+//   → ws://localhost:8787/v1/connect?k=<sha256(room)>[&key=pk_…]
+//
+// Optional TURN (same variables as the Worker): TURN_KEY_ID, TURN_KEY_API_TOKEN, TURN_TTL. The
+// limit and budget variables (README.md) are read from the environment too; `--keys` is a JSON
+// object `{ "pk_…": { "origins": [...] } }` for keyed sessions.
+//
+// The WebSocket framing below is the minimal RFC 6455 server subset: the upgrade handshake,
+// masked client frames (text, continuation, ping/pong, close), unmasked server text frames. That
+// is all a JSON signalling channel needs, and it keeps `npm install` out of a dev loop.
+
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { Room, DEFAULT_ROOM_CAP, MAX_MESSAGE_BYTES, mintTurnCredentials, refuseConn } from './room.mjs';
+import { Meter, limitsFromEnv } from './limits.mjs';
+import { TurnBudget, budgetFromEnv } from './turn-budget.mjs';
+import { mapKeyStore } from './keys.mjs';
+import { createGate } from './gate.mjs';
+
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const KEY_RE = /^[0-9a-f]{64}$/;
+const IDLE_MS = 60_000;
+
+/**
+ * Start a dev server. Resolves once listening.
+ * @param {{port?: number, host?: string, cap?: number, env?: object, keys?: Map<string, object>|object,
+ *          turn?: ((session: object|null) => Promise<object[]|null>)|null, blocklist?: Set<string>,
+ *          log?: (s: string) => void}} [opts]
+ *        `turn`: a minter to use instead of Cloudflare (tests: fake TURN without a token).
+ * @returns {Promise<{port: number, url: string, rooms: Map<string, Room>, budget: TurnBudget, meters: Map<string, Meter>, close(): Promise<void>}>}
+ */
+export function startDevServer({ port = 8787, host = '127.0.0.1', cap = DEFAULT_ROOM_CAP, env = process.env, keys = null, turn = undefined, blocklist = null, log = () => {} } = {}) {
+  /** @type {Map<string, Room>} */
+  const rooms = new Map();
+  const timers = new Map(); // room key -> lifetime timer
+  const sockets = new Set();
+  const raw = new Set(); // every upgraded TCP socket, destroyed on shutdown
+  const budget = new TurnBudget({ cfg: budgetFromEnv(env) });
+  /** @type {Map<string, Meter>} */
+  const meters = new Map();
+  const meterOf = (subject) => {
+    let m = meters.get(subject);
+    if (!m) meters.set(subject, (m = new Meter()));
+    return m;
+  };
+  const gate = createGate({
+    limits: limitsFromEnv(env),
+    keys: keys ? mapKeyStore(keys) : null,
+    budget: { snapshot: () => budget.snapshot(), cfg: budget.cfg },
+    meters: { exec: (subject, cmd) => meterOf(subject).exec(cmd) },
+    blocklist: blocklist ? { has: (ip) => blocklist.has(ip) } : null,
+    salt: env.RATE_SALT || '',
+  });
+  const cfTurn = env.TURN_KEY_ID && env.TURN_KEY_API_TOKEN;
+  const minter =
+    turn !== undefined
+      ? turn
+      : cfTurn
+        ? (s) => mintTurnCredentials(env, undefined, { ttl: s && s.turn && s.turn.ttl > 0 ? s.turn.ttl : undefined, customIdentifier: (s && s.key) || 'anon' })
+        : null;
+  const ice = minter
+    ? async (s) => {
+        const r = await minter(s);
+        if (r) budget.recordMint(s ? s.key : null, s && s.turn && s.turn.ttl > 0 ? s.turn.ttl : parseInt(env.TURN_TTL || '3600', 10) || 3600);
+        return r;
+      }
+    : null;
+
+  const server = createServer((req, res) => {
+    const u = new URL(req.url, 'http://x');
+    if (u.pathname === '/' || u.pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+      res.end(JSON.stringify({ ok: true, protocol: 'dxr-signal/1', rooms: rooms.size, turn: ice ? budget.snapshot().status : 'unconfigured', keys: !!keys }));
+      return;
+    }
+    res.writeHead(426, { 'Content-Type': 'text/plain' });
+    res.end('WebSocket endpoint: /v1/connect?k=<sha256(room) hex>\n');
+  });
+
+  server.on('upgrade', (req, socket) => {
+    const u = new URL(req.url, 'http://x');
+    const key = u.searchParams.get('k') || '';
+    const wsKey = req.headers['sec-websocket-key'];
+    if (u.pathname !== '/v1/connect' || !KEY_RE.test(key) || !wsKey || String(req.headers.upgrade).toLowerCase() !== 'websocket') {
+      socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+      return;
+    }
+    const accept = createHash('sha1').update(wsKey + WS_GUID).digest('base64');
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+        `Sec-WebSocket-Accept: ${accept}\r\n\r\n`
+    );
+    socket.setNoDelay(true);
+    raw.add(socket);
+    socket.on('close', () => raw.delete(socket));
+    let session = null;
+    let room = null;
+    let early = []; // messages that arrive while admission is still deciding (a join sent on open)
+    const conn = wrapSocket(socket, {
+      onText: (text) => (room ? room.onMessage(conn, text).catch(() => {}) : early && early.push(text)),
+      onClose: () => {
+        sockets.delete(conn);
+        if (room) {
+          room.onClose(conn);
+          if (room.size === 0 && rooms.get(key) === room) rooms.delete(key);
+        }
+        if (session) gate.release(session).catch(() => {});
+      },
+    });
+    sockets.add(conn);
+    gate
+      .admit({ ip: socket.remoteAddress || '', origin: String(req.headers.origin || ''), key: u.searchParams.get('key') || null, roomKey: key, wantTurn: !!ice })
+      .then((a) => {
+        if (!a.ok) {
+          log(`refuse ${a.code} k=${key.slice(0, 8)}…`);
+          return refuseConn(conn, a);
+        }
+        session = a.session;
+        budget.recordJoin(session.key);
+        room = rooms.get(key);
+        if (!room) {
+          const r = new Room({
+            key,
+            cap,
+            iceServers: ice,
+            hooks: {
+              onFirst: (s) => {
+                clearTimeout(timers.get(key));
+                const ttlS = s && s.roomTtlS > 0 ? s.roomTtlS : limitsFromEnv(env).anon.roomTtlS;
+                const t = setTimeout(() => r.expire(), ttlS * 1000);
+                t.unref();
+                timers.set(key, t);
+              },
+              onEmpty: () => {
+                clearTimeout(timers.get(key));
+                timers.delete(key);
+              },
+            },
+          });
+          rooms.set(key, r);
+          room = r;
+        }
+        room.attach(conn, session);
+        log(`connect k=${key.slice(0, 8)}… ${session.tier}${session.key ? ' ' + session.key : ''} (${rooms.size} rooms)`);
+        const replay = early;
+        early = null;
+        for (const text of replay) room.onMessage(conn, text).catch(() => {});
+      })
+      .catch(() => {
+        early = null;
+        refuseConn(conn, { code: 'bad-message', message: 'admission failed', closeCode: 4000 });
+      });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      const addr = server.address();
+      const p = typeof addr === 'object' && addr ? addr.port : port;
+      resolve({
+        port: p,
+        url: `ws://${host === '0.0.0.0' ? 'localhost' : host}:${p}`,
+        rooms,
+        budget,
+        meters,
+        close: () =>
+          new Promise((done) => {
+            for (const t of timers.values()) clearTimeout(t);
+            for (const c of sockets) c.close(1001, 'server shutting down');
+            for (const s of raw) s.destroy();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}
+
+/** Wrap a raw upgraded socket as a `{send(obj), close(code, reason)}` connection. */
+function wrapSocket(socket, { onText, onClose }) {
+  let buf = Buffer.alloc(0);
+  let frag = null; // continuation assembly: { chunks: Buffer[] }
+  let closed = false;
+  let idle = setTimeout(() => conn.close(1001, 'idle'), IDLE_MS);
+  const touch = () => {
+    clearTimeout(idle);
+    // Never re-armed after close: the client's close-frame reply still arrives as data.
+    if (!closed) idle = setTimeout(() => conn.close(1001, 'idle'), IDLE_MS);
+  };
+
+  const conn = {
+    send(obj) {
+      if (closed) return;
+      socket.write(frame(0x1, Buffer.from(JSON.stringify(obj))));
+    },
+    close(code = 1000, reason = '') {
+      if (closed) return;
+      closed = true;
+      clearTimeout(idle);
+      const r = Buffer.from(String(reason).slice(0, 100));
+      const p = Buffer.alloc(2 + r.length);
+      p.writeUInt16BE(code, 0);
+      r.copy(p, 2);
+      try {
+        socket.end(frame(0x8, p));
+      } catch {
+        /* ignore */
+      }
+      // Give the client a moment to answer the close frame, then drop the TCP socket regardless.
+      setTimeout(() => socket.destroy(), 1000).unref();
+      onClose();
+    },
+  };
+
+  socket.on('data', (chunk) => {
+    if (closed) return;
+    touch();
+    buf = Buffer.concat([buf, chunk]);
+    for (;;) {
+      if (buf.length < 2) return;
+      const fin = (buf[0] & 0x80) !== 0;
+      const op = buf[0] & 0x0f;
+      const masked = (buf[1] & 0x80) !== 0;
+      let len = buf[1] & 0x7f;
+      let off = 2;
+      if (len === 126) {
+        if (buf.length < 4) return;
+        len = buf.readUInt16BE(2);
+        off = 4;
+      } else if (len === 127) {
+        if (buf.length < 10) return;
+        const big = buf.readBigUInt64BE(2);
+        if (big > BigInt(MAX_MESSAGE_BYTES * 2)) return conn.close(1009, 'too big');
+        len = Number(big);
+        off = 10;
+      }
+      if (!masked) return conn.close(1002, 'client frames must be masked');
+      if (buf.length < off + 4 + len) return;
+      const mask = buf.subarray(off, off + 4);
+      const payload = Buffer.from(buf.subarray(off + 4, off + 4 + len));
+      for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+      buf = buf.subarray(off + 4 + len);
+
+      if (op === 0x8) return conn.close(1000, '');
+      if (op === 0x9) {
+        socket.write(frame(0xa, payload));
+        continue;
+      }
+      if (op === 0xa) continue;
+      if (op === 0x1 || op === 0x0) {
+        if (op === 0x1) frag = { chunks: [] };
+        if (!frag) return conn.close(1002, 'unexpected continuation');
+        frag.chunks.push(payload);
+        const total = frag.chunks.reduce((n, c) => n + c.length, 0);
+        if (total > MAX_MESSAGE_BYTES * 2) return conn.close(1009, 'too big');
+        if (fin) {
+          const text = Buffer.concat(frag.chunks).toString('utf8');
+          frag = null;
+          onText(text);
+        }
+        continue;
+      }
+      return conn.close(1003, 'unsupported frame');
+    }
+  });
+  socket.on('close', () => {
+    clearTimeout(idle);
+    if (!closed) {
+      closed = true;
+      clearTimeout(idle);
+      onClose();
+    }
+  });
+  socket.on('error', () => socket.destroy());
+  return conn;
+}
+
+function frame(op, payload) {
+  const len = payload.length;
+  let head;
+  if (len < 126) {
+    head = Buffer.from([0x80 | op, len]);
+  } else if (len < 65536) {
+    head = Buffer.alloc(4);
+    head[0] = 0x80 | op;
+    head[1] = 126;
+    head.writeUInt16BE(len, 2);
+  } else {
+    head = Buffer.alloc(10);
+    head[0] = 0x80 | op;
+    head[1] = 127;
+    head.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([head, payload]);
+}
+
+// CLI
+// pathToFileURL: a Windows argv path (C:\…) never string-matches file:///C:/…
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const arg = (name, dflt) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : dflt;
+  };
+  const port = parseInt(arg('port', process.env.PORT || '8787'), 10);
+  const cap = parseInt(arg('cap', '4'), 10);
+  const host = arg('host', '127.0.0.1');
+  const keysFile = arg('keys', '');
+  const keys = keysFile ? JSON.parse(readFileSync(keysFile, 'utf8')) : null;
+  startDevServer({ port, cap, host, keys, log: (s) => console.log(`[dxr-signal] ${s}`) }).then((s) => {
+    console.log(`[dxr-signal] dev server on ${s.url}/v1/connect (cap ${cap}${process.env.TURN_KEY_ID ? ', TURN on' : ''}${keys ? `, ${Object.keys(keys).length} keys` : ''})`);
+  });
+}