Roxxie tracker

The tracker is Roxxie's low-bandwidth control plane. It performs registration, validation-gated automatic approval, node health validation, discovery, and WebRTC offer/answer forwarding. It never relays proxy payload traffic and does not persist browser IP addresses, requests, destinations, or sessions.

Architecture

Browsers try the public /v1/browser WSS endpoint first and use the HTTPS candidate/session endpoints only when WSS transport fails. Nodes maintain one outbound WSS connection to /v1/nodes/control; therefore a volunteer node does not require port forwarding or its own TLS certificate. Browser-to-node proxy traffic uses WebRTC only. This design has no TURN relay, so WebRTC can still fail for some symmetric-NAT or firewall combinations; browsers retry another candidate.

Browser discovery is public and has no per-user rate limit. Conservative whole-process safety ceilings protect a small AWS instance: 2,000 browser control sockets and 2,000 total node control sockets, of which at most 128 may be unauthenticated (four per IPv4 address or IPv6 /64), eight simultaneous node validations, 256 new in-flight validating identities, 512 simultaneous browser signaling operations, and 512 short-lived idempotency entries. A source may create four public registrations per hour. Automated validation failures are retried at the configured interval, retained up to a bounded default, and compacted in small batches; explicit admin rejections and revocations remain permanent. Source buckets are bounded, memory-only, and never appear in logs or SQLite. These are process-safety bounds, not browser-user quotas.

The tracker and volunteer-node package support Node.js 20 or newer. On Node 20-23 the tracker uses its optional better-sqlite3 binding; Node 24 and newer use the built-in SQLite API. Do not omit optional dependencies on Node 20-23. Reinstall production dependencies after changing Node.js major versions so the native SQLite and WebRTC addons match the active runtime.

Initialize and run

sudo install -d -m 0700 /etc/roxxie-tracker
sudo roxxie-tracker init \
  --public-url https://203.0.113.10 \
  --config /etc/roxxie-tracker/tracker.json
sudo roxxie-tracker serve --config /etc/roxxie-tracker/tracker.json

The generated configuration listens on 127.0.0.1:8788. Use the Roxxie Debian deployment bundle to put Caddy in front of it on ports 80/443; never expose port 8788 directly. The exported tracker.example.json is structural reference material only and deliberately contains an invalid master secret. Never deploy it directly; always use roxxie-tracker init to generate a unique protected secret and update-signing keypair.

Local administrator CLI

No administrative HTTP API is exposed. These commands open the local SQLite database specified by the protected configuration file:

roxxie-tracker nodes pending
roxxie-tracker nodes approve NODE_UUID
roxxie-tracker nodes reject NODE_UUID
roxxie-tracker nodes revoke NODE_UUID
roxxie-tracker nodes list approved
roxxie-tracker network status
roxxie-tracker counters
roxxie-tracker doctor

Add --config /etc/roxxie-tracker/tracker.json or set ROXXIE_TRACKER_CONFIG when using a non-default path. An eligible direct npm global node installation creates and protects its UUID and bootstrap secret, starts the native service, and submits registration automatically; setup remains the explicit fallback and no administrator token is needed. The tracker stores only the credential hash, bounds public registration work, validates the complete proxy path, and atomically approves a successful node. nodes approve remains available only for legacy pending records created by an older tracker.

Public admission is bounded without keeping source addresses: at most four new or failed-auth attempts are accepted per source and hour by default, IPv6 sources share a canonical /64, and only four unauthenticated node sockets per source may remain open. The tracker also caps active validation work and the total validating queue. Source keys exist only in bounded, expiring memory; the database receives aggregate refusal and admission counters only. Explicit administrator rejections and revocations remain permanent. Old automated validation failures are compacted in small maintenance batches once their configured retention ceiling is exceeded.

Admission and health

The tracker itself creates an ordered WebRTC data channel, completes the Adrift protocol handshake, and sends an HTTPS request through the candidate node to a one-time in-memory nonce endpoint. A successful full-path test atomically approves the node and rotates its credential; it is not returned to browsers until the live agent acknowledges that credential. Failed initial validation leaves the node validating, unhealthy, and undiscoverable. The tracker retries through the same bounded validation queue after validationIntervalMs; a later pass atomically approves it without node-operator or tracker-operator action. Approved nodes are periodically retested; failed nodes become unhealthy and automatically return after a later passing test.

IP certificate renewal

IP certificates require Certbot 5.4+ and Let's Encrypt's shortlived profile. They are valid for 160 hours, so renewal must be automated. The Roxxie Debian deployment bundle configures Certbot, its renewal timer, and Caddy TLS termination; the tracker remains a loopback-only control plane.

Signed node updates

init creates a tracker-specific Ed25519 update keypair. Keep the private key restricted to the tracker. Node setup downloads and pins the public key through the authenticated HTTPS IP endpoint. Publishing is explicit:

roxxie-tracker updates publish \
  --tarball ./roxxie-node-1.2.3.tgz \
  --url https://registry.example/roxxie-node-1.2.3.tgz \
  --version 1.2.3 \
  --minimum-node 20.0.0 \
  --private-key /etc/roxxie-tracker/updates/node-update-private.pem

Nodes verify the Ed25519 signature and SHA-512 digest, retain their previous installation, health-check the update, and roll back on failure.