@openchambery/relay-server 1.17.1-beta.10

package/DOCUMENTATION.md

@@ -0,0 +1,221 @@
+# Relay Server Package Documentation
+
+`packages/relay-server/` owns the self-hosted Layer 1 Relay server, the `openchamber-relay` CLI, and the package release and deployment contract.
+
+## Purpose and security boundary
+
+The Relay server brokers Layer 1 routing: Host control connections, client route requests, and matching Host data connections. It forwards opaque Layer 2/3 frames verbatim.
+
+Host and Client terminate the E2EE channel. Each Host authenticates Relay connections with its long-lived P-256 signing key. Pairing secrets and client bearer credentials continue through endpoint validation; Relay reachability grants transport access.
+
+Relay v1 admission accepts anonymous Client route requests. Per-IP, global, pending-connection, raw-socket, frame, and queue limits bound that public entry point. Configure limits for the expected traffic volume and keep the Relay behind TLS. Pair queues pause the fast sender at half the per-connection byte limit so a slow peer applies TCP backpressure instead of filling memory until `4029`. Ready pairs send one frame per tick so one tunnel cannot monopolize the event loop.
+
+The Relay keeps process-local routing state only. Hosts reconnect after Relay restarts, and a control disconnect retains its Host route for the 30-second grace period.
+
+## Quick deployment
+
+Install the package, then start the Relay:
+
+```sh
+npm install -g @openchambery/relay-server
+openchamber-relay
+```
+
+The default listener is `127.0.0.1:8787` and the WebSocket path is `/ws`. Deploy with the default loopback listener and a TLS reverse proxy. Set the public URL to the same public scheme, host, and path:
+
+```sh
+openchamber-relay --public-url wss://relay.example.com/ws
+```
+
+### Caddy
+
+```caddyfile
+relay.example.com {
+    reverse_proxy 127.0.0.1:8787 {
+        header_up X-Forwarded-For {remote_host}
+    }
+}
+```
+
+Run the Relay with `--public-url wss://relay.example.com/ws`. Caddy proxies WebSocket upgrades for `/ws` and serves `/healthz` and `/readyz` through the same upstream. `header_up X-Forwarded-For {remote_host}` replaces the inbound value with the single client source IP.
+
+### Nginx
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name relay.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8787;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+Run the Relay with `--public-url wss://relay.example.com/ws`. The `/ws` path in the public URL and Relay configuration must match. `proxy_set_header X-Forwarded-For $remote_addr;` replaces the inbound value with the single client source IP.
+
+## Docker
+
+Each non-dry-run OpenChamber release publishes a multi-platform Relay image for `linux/amd64` and `linux/arm64` to Docker Hub. CI builds each architecture natively in parallel (`ubuntu-latest` and `ubuntu-24.04-arm`), then merges digests into a single multi-arch manifest tagged as:
+
+```text
+<DOCKERHUB_USERNAME>/openchamber-relay:<version>
+<DOCKERHUB_USERNAME>/openchamber-relay:latest
+```
+
+The release workflow reads the Docker Hub account from the `DOCKERHUB_USERNAME` GitHub Actions repository variable and authenticates with the `DOCKERHUB_TOKEN` repository secret. Use a Docker Hub personal access token with Read and Write permissions; Delete permission is not required. A failed image build or push blocks final publication of the GitHub Release.
+
+For an image-only republish of the current package version, run the `Relay Docker` workflow directly or dispatch the `Release` workflow with `relay_only` enabled. The image-only path does not create or modify a GitHub Release or any desktop and mobile artifacts.
+
+Pull and run a published image behind a host TLS reverse proxy:
+
+```sh
+docker pull <dockerhub-username>/openchamber-relay:<version>
+docker run -d \
+  --name openchamber-relay \
+  --restart unless-stopped \
+  --read-only \
+  --tmpfs /tmp \
+  --security-opt no-new-privileges:true \
+  -p 127.0.0.1:8787:8787 \
+  -e OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws \
+  <dockerhub-username>/openchamber-relay:<version>
+```
+
+Use an immutable version tag in production. Each non-dry-run release updates `latest` together with its immutable version tag.
+
+For a complete public deployment using the published immutable image, automatic HTTPS, and an internal-only Relay listener, use [`docker-compose.relay.remote.yml`](../../docker-compose.relay.remote.yml). Docker Compose 2.23.1 or later is required for its inline Caddy config. Point the domain's `A` and/or `AAAA` record at the server, allow inbound TCP ports 80 and 443 plus UDP port 443, then run:
+
+```sh
+OPENCHAMBER_RELAY_IMAGE='<dockerhub-username>/openchamber-relay:<version>@sha256:<manifest-digest>' \
+RELAY_DOMAIN=relay.example.com \
+ACME_EMAIL=admin@example.com \
+docker compose -f docker-compose.relay.remote.yml up -d
+```
+
+`OPENCHAMBER_RELAY_IMAGE` is required; the deployment file must never bind to a personal registry namespace. Supply an immutable version-and-manifest-digest reference in production. The file keeps Relay off host ports, replaces forwarded client IPs at Caddy, persists Caddy certificates and configuration, and enables trusted-proxy mode on Relay. Inspect startup and readiness with:
+
+```sh
+docker compose -f docker-compose.relay.remote.yml ps
+curl -fsS https://relay.example.com/healthz
+curl -fsS https://relay.example.com/readyz
+```
+
+From the repository root, build and start the supplied service. The compatibility assets are [`Dockerfile.relay`](../../Dockerfile.relay) and [`docker-compose.relay.yml`](../../docker-compose.relay.yml):
+
+```sh
+OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws \
+OPENCHAMBER_RELAY_PUBLISHED_PORT=8787 \
+docker compose -f docker-compose.relay.yml up -d --build
+```
+
+Compose publishes `127.0.0.1:${OPENCHAMBER_RELAY_PUBLISHED_PORT:-8787}` by default; use `OPENCHAMBER_RELAY_PUBLISHED_PORT` to select the host port. The Compose service uses an ephemeral filesystem and keeps Host identity keys on each OpenChamber Host. Its image health check calls `GET /healthz`. Terminate public TLS at an external reverse proxy and publish `wss://relay.example.com/ws`. A public Relay port binding requires firewall rules and TLS; loopback publishing with a TLS reverse proxy is the deployment path.
+
+## Connect Hosts
+
+Set the Relay URL on every OpenChamber Host, start the Host, then generate a Relay pairing link or enable Relay pairing in the application:
+
+```sh
+export OPENCHAMBER_RELAY_URL=wss://relay.example.com/ws
+openchamber
+```
+
+The **Add a device** dialog can select this endpoint per pairing. An owner UI session or the local Desktop shell (`desktop-local`) may persist a custom Host endpoint and switch the control connection; the effective `relayUrl` is embedded in the pairing-v2 candidate before the QR code. Endpoints must be `ws://` or `wss://` without userinfo; query and fragment are not part of identity and are stripped. `OPENCHAMBER_RELAY_URL` pins the endpoint and disables the override. The creating client remembers its last effective choice locally; consuming Mobile and Desktop clients persist the endpoint snapshot with the saved connection.
+
+Existing clients switch to a new Relay after a new pairing flow; generate a fresh pairing link when endpoint replacement is required.
+
+## Configuration
+
+Configuration precedence is command flags, then `OPENCHAMBER_RELAY_SERVER_*` variables, then defaults. `--host`, `--port`, `--path`, `--public-url`, `--trust-proxy`, `--no-trust-proxy`, `--json`, and `--quiet` are available.
+
+`OPENCHAMBER_RELAY_SERVER_PUBLIC_URL` affects startup output. `OPENCHAMBER_RELAY_SERVER_PATH` selects the actual WebSocket upgrade endpoint. Relay listens on loopback by default. Enable `OPENCHAMBER_RELAY_SERVER_TRUST_PROXY=true` when a trusted reverse proxy fully isolates Relay ingress and replaces any client-supplied `X-Forwarded-For` value with one canonical client IP. Relay accepts one forwarded IP in this mode.
+
+With correctly configured trusted proxying, client and admission limits use that canonical client IP. `OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS_PER_IP` always counts the TCP peer that connects to Relay; reverse-proxy deployments therefore count raw sockets against the proxy and require a higher value sized for aggregate concurrent traffic.
+
+For an IPv6 literal in a public URL, enclose the host in brackets: `wss://[2001:db8::1]/ws`.
+
+| Variable | Default | Unit / purpose |
+| --- | --- | --- |
+| `OPENCHAMBER_RELAY_SERVER_HOST` | `127.0.0.1` | Listener address |
+| `OPENCHAMBER_RELAY_SERVER_PORT` | `8787` | TCP port |
+| `OPENCHAMBER_RELAY_SERVER_PATH` | `/ws` | WebSocket upgrade path |
+| `OPENCHAMBER_RELAY_SERVER_PUBLIC_URL` | unset | Startup output URL; `ws://` or `wss://`, same path as `PATH` |
+| `OPENCHAMBER_RELAY_SERVER_TRUST_PROXY` | `false` | Read one canonical client IP from proxy-replaced `X-Forwarded-For` |
+| `OPENCHAMBER_RELAY_SERVER_MAX_URL_BYTES` | `4096` | bytes |
+| `OPENCHAMBER_RELAY_SERVER_MAX_FIELD_BYTES` | `512` | bytes per routing field |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOSTS` | `256` | active Host routes |
+| `OPENCHAMBER_RELAY_SERVER_MAX_SOCKETS` | `2048` | upgraded WebSockets |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONNECTIONS` | `1000` | global client connections |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CLIENTS_PER_HOST` | `100` | connections per Host |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CLIENTS_PER_IP` | `30` | connections per client IP |
+| `OPENCHAMBER_RELAY_SERVER_MAX_PENDING_CLIENTS` | `30` | clients awaiting Host data connection |
+| `OPENCHAMBER_RELAY_SERVER_PENDING_MS` | `15000` | ms awaiting Host data connection |
+| `OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS` | `4096` | accepted TCP sockets before upgrade |
+| `OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS_PER_IP` | `128` | TCP sockets per Relay TCP peer IP |
+| `OPENCHAMBER_RELAY_SERVER_GRACE_MS` | `30000` | ms Host control disconnect grace |
+| `OPENCHAMBER_RELAY_SERVER_TIMESTAMP_SKEW_MS` | `60000` | ms Host signature timestamp window |
+| `OPENCHAMBER_RELAY_SERVER_REPLAY_MS` | `120000` | ms replay-record lifetime; at least twice timestamp skew |
+| `OPENCHAMBER_RELAY_SERVER_MAX_REPLAY_ENTRIES` | `10000` | Host signature replay records |
+| `OPENCHAMBER_RELAY_SERVER_MAX_FRAME_BYTES` | `131072` | bytes per forwarded frame |
+| `OPENCHAMBER_RELAY_SERVER_MAX_QUEUED_BYTES_PER_CONNECTION` | `2097152` | bytes per client pair |
+| `OPENCHAMBER_RELAY_SERVER_MAX_GLOBAL_QUEUED_BYTES` | `33554432` | bytes across all queues |
+| `OPENCHAMBER_RELAY_SERVER_MAX_BUFFERED_AMOUNT` | `2097152` | bytes buffered by a WebSocket before pump retry |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONTROL_QUEUE_ENTRIES` | `256` | queued Host control messages |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONTROL_QUEUED_BYTES` | `2097152` | bytes queued for Host control |
+| `OPENCHAMBER_RELAY_SERVER_PUMP_RETRY_MS` | `25` | ms between backpressure retries |
+| `OPENCHAMBER_RELAY_SERVER_HEARTBEAT_MS` | `30000` | ms WebSocket ping interval |
+| `OPENCHAMBER_RELAY_SERVER_HANDSHAKE_MS` | `10000` | ms for TCP and WebSocket admission |
+| `OPENCHAMBER_RELAY_SERVER_CLOSE_DEADLINE_MS` | `5000` | ms before forced socket close |
+| `OPENCHAMBER_RELAY_SERVER_ADMISSION_WINDOW_MS` | `60000` | ms per-IP admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSIONS_PER_IP` | `120` | upgrades per role and IP per admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSION_ENTRIES` | `10000` | tracked role/IP admission records |
+| `OPENCHAMBER_RELAY_SERVER_ID_ATTEMPTS` | `4` | random connection-ID attempts |
+
+## Operations
+
+- `GET` and `HEAD` requests to `/healthz` return process health. `/readyz` returns ready status after the listener reaches running state.
+- `SIGTERM` and `SIGINT` begin graceful Relay shutdown. Docker grants a 30-second stop period.
+- Hosts automatically reconnect after a Relay process restart. Relay state remains ephemeral.
+- Keep logs and metrics snapshots free of URL query strings, `sig`, `pk`, `grant`, and encrypted payloads.
+
+### systemd
+
+Create `/etc/openchamber-relay.env`:
+
+```sh
+OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws
+```
+
+Create `/etc/systemd/system/openchamber-relay.service`:
+
+```ini
+[Unit]
+Description=OpenChamber Private Relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/openchamber-relay.env
+ExecStart=/usr/local/bin/openchamber-relay
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable it:
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now openchamber-relay
+```

package/README.md

@@ -0,0 +1,304 @@
+# OpenChamber Relay Server
+
+`openchamber-relay` is the self-hosted Layer 1 relay for OpenChamber remote access. It gives OpenChamber Hosts an outbound Relay connection and carries encrypted client traffic through that connection.
+
+The Relay routes opaque Layer 2/3 frames verbatim. E2EE terminates at the OpenChamber Host and Client, so the Relay has routing metadata and transport state while the endpoints hold application plaintext, pairing secrets, and client bearer credentials. Host Relay connections authenticate with the Host's long-lived P-256 signing key. Relay reachability grants transport access; endpoint validation continues to enforce pairing and client credentials.
+
+## Architecture and transport
+
+The components have the following responsibilities:
+
+- **Host** maintains an authenticated control WebSocket to the Relay, receives client connection requests, and opens matching Host data WebSockets.
+- **Control channel** associates a Host identity with its active route and communicates connection lifecycle events.
+- **Data channel** pairs one Host data WebSocket with one Client WebSocket and forwards opaque encrypted frames in both directions.
+- **Client** requests a route to a Host and multiplexes application traffic through its encrypted Relay tunnel.
+
+The tunneled application transport supports HTTP, streaming SSE, and WebSocket traffic. HTTP and SSE use the Client bearer credential through the encrypted tunnel. WebSockets use a short-lived URL-scoped credential (`oc_url_token`) minted by the Host endpoint.
+
+Relay state lives in process memory. Hosts reconnect after a Relay restart. A disconnected Host control connection retains its route during the configurable 30-second grace period.
+
+Relay v1 accepts anonymous Client route requests. Admission, connection, frame, queue, and socket limits bound this public entry point.
+
+## Requirements
+
+- `@openchambery/relay-server` installation: Node.js 22 or later and a supported package manager such as npm, pnpm, yarn, or Bun.
+- Single-file bundle build: Bun. This repository uses Bun 1.3.14.
+- Public deployment: a DNS name, TLS certificate, reverse proxy, and firewall policy appropriate for the deployment.
+
+## Install and quick start
+
+`openchamber-relay` ships as an executable in the public `@openchambery/relay-server` package.
+
+```sh
+npm install -g @openchambery/relay-server
+openchamber-relay --public-url wss://relay.example.com/ws
+```
+
+The default listener is `127.0.0.1:8787` and the default WebSocket upgrade path is `/ws`. Keep this loopback listener behind a TLS reverse proxy and set `--public-url` to the public `ws://` or `wss://` URL with the same path.
+
+### Build a standalone executable
+
+Run these commands from the repository root. `bun build --compile` creates a single executable for the current platform and architecture.
+
+```sh
+bun build --compile --outfile ./openchamber-relay ./packages/relay-server/bin/openchamber-relay.js
+sudo install -m 0755 ./openchamber-relay /usr/local/bin/openchamber-relay
+```
+
+Smoke-test the installed executable, process health, and readiness:
+
+```sh
+openchamber-relay --version
+openchamber-relay --host 127.0.0.1 --port 8787 --json > /tmp/openchamber-relay-startup.json 2> /tmp/openchamber-relay.stderr &
+relay_pid=$!
+curl -fsS http://127.0.0.1:8787/healthz
+curl -fsS http://127.0.0.1:8787/readyz
+kill -TERM "$relay_pid"
+wait "$relay_pid"
+```
+
+The executable remains independently deployable after compilation. `@openchambery/relay-server` owns its distribution and publishes the `openchamber-relay` executable.
+
+## Configure the listener and public URL
+
+Command flags take precedence over `OPENCHAMBER_RELAY_SERVER_*` environment variables, which take precedence over defaults.
+
+```sh
+openchamber-relay \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --path /relay \
+  --public-url wss://relay.example.com/relay
+```
+
+The public URL path and the configured Relay path must match. An IPv6 public URL uses brackets around the literal:
+
+```sh
+openchamber-relay --public-url wss://[2001:db8::1]/ws
+```
+
+Available CLI options:
+
+```text
+--host HOST
+--port PORT
+--path PATH
+--public-url WS_URL
+--trust-proxy | --no-trust-proxy
+--json
+--quiet, -q
+--help, -h
+--version, -v
+```
+
+## Connect OpenChamber Hosts
+
+Set the public Relay URL in every OpenChamber Host environment, then start the Host and create a Relay pairing link or enable Relay pairing in the application.
+
+```sh
+export OPENCHAMBER_RELAY_URL=wss://relay.example.com/ws
+openchamber
+```
+
+The **Add a device** dialog can override the Relay endpoint for a pairing. The Host persists and switches to the selected endpoint before it emits the QR code, unless `OPENCHAMBER_RELAY_URL` pins the deployment endpoint. The effective `relayUrl` is part of the pairing-v2 candidate and is saved by Mobile and Desktop clients for later reconnects.
+
+Existing Clients use a new pairing flow to receive a changed Relay endpoint. Create a fresh pairing link when endpoint replacement is required.
+
+## TLS reverse proxies
+
+The Relay serves loopback HTTP health endpoints and WebSocket upgrades. The public proxy terminates TLS and forwards HTTP, SSE, and WebSocket upgrade traffic to the Relay.
+
+### Caddy
+
+```caddyfile
+relay.example.com {
+    reverse_proxy 127.0.0.1:8787 {
+        header_up X-Forwarded-For {remote_host}
+    }
+}
+```
+
+Run the Relay with `--public-url wss://relay.example.com/ws`. Caddy forwards WebSocket upgrades and serves `/healthz` and `/readyz` from the same upstream. The `X-Forwarded-For` rule writes one canonical Client source IP.
+
+### Nginx
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name relay.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8787;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+Run the Relay with `--public-url wss://relay.example.com/ws`. Nginx writes one canonical Client source IP with `$remote_addr` and forwards WebSocket upgrades over HTTP/1.1.
+
+## Trusted proxies and capacity
+
+Enable `OPENCHAMBER_RELAY_SERVER_TRUST_PROXY=true` or `--trust-proxy` when a trusted reverse proxy fully isolates Relay ingress and replaces each inbound `X-Forwarded-For` value with one canonical Client IP.
+
+```sh
+OPENCHAMBER_RELAY_SERVER_TRUST_PROXY=true \
+openchamber-relay --public-url wss://relay.example.com/ws
+```
+
+Trusted-proxy mode accepts exactly one valid IP address in `X-Forwarded-For`. Client admission and per-Client-IP limits then use that address. Configure the proxy to replace the header, and restrict direct access to the Relay listener so proxy peer identity remains authoritative.
+
+`OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS_PER_IP` always counts the TCP peer connected to the Relay. A reverse proxy is that peer, so set this limit for the proxy's aggregate concurrent traffic rather than an individual public Client.
+
+## Environment variables
+
+| Variable | Default | Unit / purpose |
+| --- | --- | --- |
+| `OPENCHAMBER_RELAY_SERVER_HOST` | `127.0.0.1` | Listener address |
+| `OPENCHAMBER_RELAY_SERVER_PORT` | `8787` | TCP port |
+| `OPENCHAMBER_RELAY_SERVER_PATH` | `/ws` | WebSocket upgrade path |
+| `OPENCHAMBER_RELAY_SERVER_PUBLIC_URL` | unset | Startup output URL; `ws://` or `wss://`, same path as `PATH` |
+| `OPENCHAMBER_RELAY_SERVER_TRUST_PROXY` | `false` | Read one canonical Client IP from proxy-replaced `X-Forwarded-For` |
+| `OPENCHAMBER_RELAY_SERVER_MAX_URL_BYTES` | `4096` | bytes |
+| `OPENCHAMBER_RELAY_SERVER_MAX_FIELD_BYTES` | `512` | bytes per routing field |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOSTS` | `256` | active Host routes |
+| `OPENCHAMBER_RELAY_SERVER_MAX_SOCKETS` | `2048` | upgraded WebSockets |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONNECTIONS` | `1000` | global client connections |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CLIENTS_PER_HOST` | `100` | connections per Host |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CLIENTS_PER_IP` | `30` | connections per Client IP |
+| `OPENCHAMBER_RELAY_SERVER_MAX_PENDING_CLIENTS` | `30` | Clients awaiting a Host data connection |
+| `OPENCHAMBER_RELAY_SERVER_PENDING_MS` | `15000` | ms awaiting a Host data connection |
+| `OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS` | `4096` | accepted TCP sockets before upgrade |
+| `OPENCHAMBER_RELAY_SERVER_MAX_RAW_SOCKETS_PER_IP` | `128` | TCP sockets per Relay TCP peer IP |
+| `OPENCHAMBER_RELAY_SERVER_GRACE_MS` | `30000` | ms Host control disconnect grace |
+| `OPENCHAMBER_RELAY_SERVER_TIMESTAMP_SKEW_MS` | `60000` | ms Host signature timestamp window |
+| `OPENCHAMBER_RELAY_SERVER_REPLAY_MS` | `120000` | ms replay-record lifetime; at least twice timestamp skew |
+| `OPENCHAMBER_RELAY_SERVER_MAX_REPLAY_ENTRIES` | `10000` | Host signature replay records |
+| `OPENCHAMBER_RELAY_SERVER_MAX_FRAME_BYTES` | `131072` | bytes per forwarded frame |
+| `OPENCHAMBER_RELAY_SERVER_MAX_QUEUED_BYTES_PER_CONNECTION` | `2097152` | bytes per Client pair |
+| `OPENCHAMBER_RELAY_SERVER_MAX_GLOBAL_QUEUED_BYTES` | `33554432` | bytes across all queues |
+| `OPENCHAMBER_RELAY_SERVER_MAX_BUFFERED_AMOUNT` | `2097152` | bytes buffered by a WebSocket before pump retry |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONTROL_QUEUE_ENTRIES` | `256` | queued Host control messages |
+| `OPENCHAMBER_RELAY_SERVER_MAX_CONTROL_QUEUED_BYTES` | `2097152` | bytes queued for Host control |
+| `OPENCHAMBER_RELAY_SERVER_PUMP_RETRY_MS` | `25` | ms between backpressure retries |
+| `OPENCHAMBER_RELAY_SERVER_HEARTBEAT_MS` | `30000` | ms WebSocket ping interval |
+| `OPENCHAMBER_RELAY_SERVER_HANDSHAKE_MS` | `10000` | ms for TCP and WebSocket admission |
+| `OPENCHAMBER_RELAY_SERVER_CLOSE_DEADLINE_MS` | `5000` | ms before forced socket close |
+| `OPENCHAMBER_RELAY_SERVER_ADMISSION_WINDOW_MS` | `60000` | ms per-IP admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSIONS_PER_IP` | `120` | upgrades per role and IP per admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSION_ENTRIES` | `10000` | tracked role/IP admission records |
+| `OPENCHAMBER_RELAY_SERVER_ID_ATTEMPTS` | `4` | random connection-ID attempts |
+
+## systemd
+
+Create `/etc/openchamber-relay.env`:
+
+```sh
+OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws
+```
+
+Create `/etc/systemd/system/openchamber-relay.service`:
+
+```ini
+[Unit]
+Description=OpenChamber Private Relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/openchamber-relay.env
+ExecStart=/usr/local/bin/openchamber-relay
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and inspect the service:
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now openchamber-relay
+sudo systemctl status openchamber-relay
+```
+
+## Operations and security
+
+- `GET` and `HEAD` requests to `/healthz` report process health. `/readyz` reports ready status after the listener reaches the running state.
+- `SIGTERM` and `SIGINT` start graceful Relay shutdown. Hosts reconnect after a process restart.
+- Size Host, Client, pending, socket, frame, and queue limits for expected concurrency and message volume.
+- Keep the default loopback listener, terminate public TLS at a reverse proxy, restrict ingress with firewall rules, and publish the matching `wss://` URL.
+- Keep logs and metrics snapshots free of URL query strings, `sig`, `pk`, `grant`, encrypted payloads, pairing material, and bearer credentials.
+
+## Docker delivery assets
+
+Each non-dry-run OpenChamber release publishes a Docker Hub image for `linux/amd64` and `linux/arm64` as `<DOCKERHUB_USERNAME>/openchamber-relay:<version>` and `<DOCKERHUB_USERNAME>/openchamber-relay:latest`. The release pipeline requires the `DOCKERHUB_USERNAME` GitHub Actions repository variable and a `DOCKERHUB_TOKEN` repository secret with Docker Hub Read and Write permissions. Image publication must succeed before the GitHub Release is finalized.
+
+The `Relay Docker` workflow can republish only the current Relay package version without creating or modifying a GitHub Release or other platform artifacts.
+
+Pull and run an immutable release tag behind a host TLS reverse proxy:
+
+```sh
+docker pull <dockerhub-username>/openchamber-relay:<version>
+docker run -d \
+  --name openchamber-relay \
+  --restart unless-stopped \
+  --read-only \
+  --tmpfs /tmp \
+  --security-opt no-new-privileges:true \
+  -p 127.0.0.1:8787:8787 \
+  -e OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws \
+  <dockerhub-username>/openchamber-relay:<version>
+```
+
+For an end-to-end public deployment with Caddy-managed HTTPS, use [`docker-compose.relay.remote.yml`](../../docker-compose.relay.remote.yml) with Docker Compose 2.23.1 or later:
+
+```sh
+OPENCHAMBER_RELAY_IMAGE='<dockerhub-username>/openchamber-relay:<version>@sha256:<manifest-digest>' \
+RELAY_DOMAIN=relay.example.com \
+ACME_EMAIL=admin@example.com \
+docker compose -f docker-compose.relay.remote.yml up -d
+```
+
+`OPENCHAMBER_RELAY_IMAGE` is required so the repository never binds this reusable deployment file to a personal registry namespace. Use an immutable version-and-digest reference in production.
+
+The repository provides optional Docker delivery assets at [`Dockerfile.relay`](../../Dockerfile.relay) and [`docker-compose.relay.yml`](../../docker-compose.relay.yml). The Compose service publishes `127.0.0.1:${OPENCHAMBER_RELAY_PUBLISHED_PORT:-8787}` and accepts `OPENCHAMBER_RELAY_SERVER_PUBLIC_URL` plus selected Relay limits.
+
+```sh
+OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws \
+OPENCHAMBER_RELAY_PUBLISHED_PORT=8787 \
+docker compose -f docker-compose.relay.yml up -d --build
+```
+
+These assets define an optional follow-on deployment path. Validate the image, proxy integration, TLS configuration, and operational limits in the target environment before production use.
+
+## Troubleshooting
+
+| Symptom | Checks and resolution |
+| --- | --- |
+| Host or Client cannot connect | Confirm the public URL uses the deployed `wss://` scheme, host, and exact Relay path. Confirm DNS, certificate, firewall, and proxy upstream reachability. |
+| `/healthz` succeeds and `/readyz` fails | Wait for the listener startup to complete, then inspect process stderr and service logs for bind errors. |
+| Clients receive admission or connection limits | Review `MAX_CONNECTIONS`, per-Host, per-Client-IP, pending, admission, and raw-socket limits against current traffic. |
+| Many Clients share a reverse proxy | Increase `MAX_RAW_SOCKETS_PER_IP` for aggregate proxy-peer concurrency. |
+| Per-Client IP limits behave as proxy limits | Enable trusted-proxy mode, fully isolate Relay ingress behind that proxy, and configure a single replaced `X-Forwarded-For` IP. |
+| Existing clients continue using an earlier endpoint | Refresh the candidate or create a new pairing link after changing `OPENCHAMBER_RELAY_URL`. |
+| WebSocket application traffic fails while HTTP works | Confirm the Host endpoint mints and supplies a short-lived `oc_url_token` for the WebSocket path. |
+
+## Development and test coverage
+
+Run Relay package unit tests and Host/Client end-to-end coverage independently from the repository root:
+
+```sh
+bunx vitest run --project @openchamber/relay-server
+bunx vitest run --project @openchamber/web packages/web/server/lib/relay/relay-server.e2e.test.ts
+```
+
+`packages/web/server/lib/relay/relay-server.e2e.test.ts` builds a compiled Relay executable and exercises a real Host and TypeScript Client across authenticated HTTP, streaming SSE, URL-token WebSocket traffic, Relay restart recovery, and cleanup. Use this E2E coverage when validating Relay transport changes.

package/bin/cli-entry.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+function normalizeCliEntryPath(filePath, realpath = fs.realpathSync) {
+  if (typeof filePath !== 'string' || filePath.trim().length === 0) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  try {
+    return realpath(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+function isModuleCliExecution(
+  entryPath = process.argv[1],
+  moduleUrl,
+  realpath = fs.realpathSync,
+  expectedBinName,
+) {
+  if (typeof entryPath !== 'string' || entryPath.trim().length === 0) {
+    return false;
+  }
+  if (typeof moduleUrl !== 'string' || moduleUrl.trim().length === 0) {
+    return false;
+  }
+
+  try {
+    const normalizedEntryPath = normalizeCliEntryPath(entryPath, realpath);
+    const normalizedModulePath = normalizeCliEntryPath(fileURLToPath(moduleUrl), realpath);
+    if (!normalizedEntryPath || !normalizedModulePath) {
+      return false;
+    }
+    if (pathToFileURL(normalizedEntryPath).href === pathToFileURL(normalizedModulePath).href) {
+      return true;
+    }
+
+    if (typeof expectedBinName === 'string' && expectedBinName.trim().length > 0) {
+      const parsedEntryName = path.parse(normalizedEntryPath).name.toLowerCase();
+      return parsedEntryName === expectedBinName.trim().toLowerCase();
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  normalizeCliEntryPath,
+  isModuleCliExecution,
+};

package/bin/openchamber-relay.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import packageJson from '../package.json' with { type: 'json' };
+
+import { isModuleCliExecution } from './cli-entry.js';
+import { runRelayServerCli } from '../src/cli.js';
+
+const version = packageJson.version;
+
+if (isModuleCliExecution(process.argv[1], import.meta.url, undefined, 'openchamber-relay')) {
+  runRelayServerCli(process.argv.slice(2), { version }).then((code) => { process.exitCode = code; });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@openchambery/relay-server",
+  "version": "1.17.1-beta.10",
+  "description": "Self-hosted private relay server for OpenChamber",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "openchamber-relay": "./bin/openchamber-relay.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yee94/openchamber.git"
+  },
+  "homepage": "https://github.com/yee94/openchamber#readme",
+  "bugs": {
+    "url": "https://github.com/yee94/openchamber/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "DOCUMENTATION.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:node": "node test/node-smoke.js",
+    "type-check": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js",
+    "lint": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js",
+    "build:standalone": "bun build --compile --outfile dist/openchamber-relay bin/openchamber-relay.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,110 @@
+import { startPrivateRelayServer } from './index.js';
+import { isIP } from 'node:net';
+
+const LIMIT_KEYS = ['maxUrlBytes', 'maxFieldBytes', 'maxHosts', 'maxSockets', 'maxConnections', 'maxClientsPerHost', 'maxClientsPerIp', 'maxPendingClients', 'pendingMs', 'maxRawSockets', 'maxRawSocketsPerIp', 'graceMs', 'timestampSkewMs', 'replayMs', 'maxReplayEntries', 'maxFrameBytes', 'maxQueuedBytesPerConnection', 'maxGlobalQueuedBytes', 'maxBufferedAmount', 'maxControlQueueEntries', 'maxControlQueuedBytes', 'pumpRetryMs', 'heartbeatMs', 'handshakeMs', 'closeDeadlineMs', 'admissionWindowMs', 'maxAdmissionsPerIp', 'maxAdmissionEntries', 'idAttempts'];
+const upperSnake = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter}`).toUpperCase();
+const envName = (key) => `OPENCHAMBER_RELAY_SERVER_${upperSnake(key)}`;
+const fail = (name) => { throw new Error(`Invalid ${name}`); };
+
+export const parseRelayServerArgs = (argv = []) => {
+  const parsed = {};
+  const values = new Map([['--host', 'host'], ['--port', 'port'], ['--path', 'path'], ['--public-url', 'publicUrl']]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (values.has(arg)) { const value = argv[++index]; if (!value || value.startsWith('--')) fail(arg, value ?? ''); parsed[values.get(arg)] = value; continue; }
+    if (arg === '--trust-proxy') { parsed.trustProxy = true; continue; }
+    if (arg === '--no-trust-proxy') { parsed.trustProxy = false; continue; }
+    if (arg === '--json') { parsed.json = true; continue; }
+    if (arg === '--quiet' || arg === '-q') { parsed.quiet = true; continue; }
+    if (arg === '--help' || arg === '-h') { parsed.help = true; continue; }
+    if (arg === '--version' || arg === '-v') { parsed.version = true; continue; }
+    fail(arg, '');
+  }
+  return parsed;
+};
+
+const positive = (name, value) => {
+  if (!/^[1-9][0-9]*$/.test(String(value))) fail(name, value);
+  const number = Number(value); if (!Number.isSafeInteger(number)) fail(name, value);
+  return number;
+};
+const bool = (name, value) => {
+  if (value === undefined) return false;
+  if (value === 'true' || value === '1' || value === true) return true;
+  if (value === 'false' || value === '0' || value === false) return false;
+  fail(name, value);
+};
+const validPath = (name, value) => {
+  if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || value.includes('?') || value.includes('#') || new URL(value, 'http://relay').pathname !== value) fail(name, value);
+  return value;
+};
+const validHost = (name, value) => {
+  if (typeof value !== 'string' || value.trim() !== value || value.length === 0 || value.includes('/') || value.includes('\\') || value.includes('@') || value.includes(':') && !isIP(value) || (!isIP(value) && !/^(?=.{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(value))) fail(name, value);
+  return value;
+};
+const publicUrl = (name, value, path) => {
+  if (!value) return undefined;
+  let url; try { url = new URL(value); } catch { fail(name, value); }
+  if (!['ws:', 'wss:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash || url.pathname !== path) fail(name, value);
+  return url.toString();
+};
+
+export const buildRelayConfig = (parsed = {}, env = process.env) => {
+  const envValue = (key) => {
+    const value = env[envName(key)];
+    return typeof value === 'string' && value.trim().length === 0 ? undefined : value;
+  };
+  const pick = (key, fallback) => parsed[key] ?? envValue(key) ?? fallback;
+  const portValue = pick('port', 8787); const port = positive(parsed.port !== undefined ? '--port' : envName('port'), portValue);
+  if (port > 65535) fail(parsed.port !== undefined ? '--port' : envName('port'), portValue);
+  const path = validPath(parsed.path !== undefined ? '--path' : envName('path'), pick('path', '/ws'));
+  const host = validHost(parsed.host !== undefined ? '--host' : envName('host'), pick('host', '127.0.0.1'));
+  const outputPublicUrl = publicUrl(parsed.publicUrl !== undefined ? '--public-url' : envName('publicUrl'), pick('publicUrl', undefined), path);
+  const limits = {};
+  for (const key of LIMIT_KEYS) { const value = pick(key, undefined); if (value !== undefined) limits[key] = positive(parsed[key] !== undefined ? `--${upperSnake(key).toLowerCase().replaceAll('_', '-')}` : envName(key), value); }
+  const replayMs = limits.replayMs ?? 120_000; const timestampSkewMs = limits.timestampSkewMs ?? 60_000; const maxConnections = limits.maxConnections ?? 1_000;
+  if (replayMs < timestampSkewMs * 2) fail(parsed.replayMs !== undefined ? '--replay-ms' : envName('replayMs'), replayMs);
+  if ((limits.maxPendingClients ?? 30) > maxConnections) fail(parsed.maxPendingClients !== undefined ? '--max-pending-clients' : envName('maxPendingClients'), limits.maxPendingClients ?? 30);
+  if ((limits.maxClientsPerHost ?? 100) > maxConnections) fail(parsed.maxClientsPerHost !== undefined ? '--max-clients-per-host' : envName('maxClientsPerHost'), limits.maxClientsPerHost ?? 100);
+  return { host, port, path, publicUrl: outputPublicUrl, trustProxy: parsed.trustProxy ?? bool(envName('trustProxy'), envValue('trustProxy')), limits };
+};
+
+const helpText = 'Usage: openchamber-relay [--host HOST] [--port PORT] [--path PATH] [--public-url WS_URL] [--trust-proxy] [--json] [--quiet]\nEnable --trust-proxy only when public ingress reaches this relay through a trusted reverse proxy.\n';
+const writeJson = (stdout, payload) => stdout.write(`${JSON.stringify(payload)}\n`);
+
+export const runRelayServerCli = async (argv, dependencies = {}) => {
+  const processLike = dependencies.process ?? process; const stdout = dependencies.stdout ?? process.stdout; const stderr = dependencies.stderr ?? process.stderr; const version = dependencies.version ?? '0.0.0';
+  let parsed;
+  try { parsed = parseRelayServerArgs(argv ?? processLike.argv?.slice(2) ?? []); } catch (error) {
+    const json = (argv ?? processLike.argv?.slice(2) ?? []).includes('--json');
+    if (json) writeJson(stdout, { status: 'error', error: error.message }); else stderr.write(`${error.message}\n`);
+    processLike.exitCode = 1; return 1;
+  }
+  const json = parsed.json;
+  const respond = (payload, error = false, essential = false) => { if (json) writeJson(stdout, payload); else if (payload.message && (essential || !parsed.quiet || error)) (error ? stderr : stdout).write(`${payload.message}\n`); };
+  if (parsed.help) { respond(json ? { status: 'ok', help: helpText.trim() } : { message: helpText.trim() }, false, true); return 0; }
+  if (parsed.version) { respond(json ? { status: 'ok', version } : { message: version }, false, true); return 0; }
+  let config;
+  try { config = buildRelayConfig(parsed, processLike.env ?? {}); } catch (error) { respond({ status: 'error', error: error.message, message: error.message }, true); processLike.exitCode = 1; return 1; }
+  try {
+    const relay = await (dependencies.start ?? startPrivateRelayServer)(config);
+    const url = config.publicUrl ?? relay.wsUrl;
+    respond(json ? { status: 'ok', url, host: config.host, port: relay.address?.()?.port ?? config.port, path: config.path } : { message: `Relay listening at ${url}` });
+    let stopping = false;
+    const stop = async () => {
+      if (stopping) return Promise.resolve();
+      stopping = true;
+      processLike.off?.('SIGINT', stop); processLike.off?.('SIGTERM', stop);
+      try {
+        await relay.stop();
+        processLike.exit?.(0);
+      } catch {
+        processLike.exitCode = 1;
+        if (json) writeJson(stderr, { status: 'error', error: 'Relay stop failed' }); else stderr.write('Relay stop failed\n');
+        processLike.exit?.(1);
+      }
+    };
+    processLike.on?.('SIGINT', stop); processLike.on?.('SIGTERM', stop);
+    return 0;
+  } catch (error) { respond({ status: 'error', error: error.message, message: error.message }, true); processLike.exitCode = 1; return 1; }
+};

package/src/index.d.ts

@@ -0,0 +1,93 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export type RelaySocketRole = 'client' | 'host-control' | 'host-data';
+
+export interface Limits {
+  maxUrlBytes: number;
+  maxFieldBytes: number;
+  maxHosts: number;
+  maxSockets: number;
+  maxConnections: number;
+  maxClientsPerHost: number;
+  maxClientsPerIp: number;
+  maxPendingClients: number;
+  pendingMs: number;
+  maxRawSockets: number;
+  maxRawSocketsPerIp: number;
+  graceMs: number;
+  timestampSkewMs: number;
+  replayMs: number;
+  maxReplayEntries: number;
+  maxFrameBytes: number;
+  maxQueuedBytesPerConnection: number;
+  maxGlobalQueuedBytes: number;
+  maxBufferedAmount: number;
+  maxControlQueueEntries: number;
+  maxControlQueuedBytes: number;
+  pumpRetryMs: number;
+  heartbeatMs: number;
+  handshakeMs: number;
+  closeDeadlineMs: number;
+  admissionWindowMs: number;
+  maxAdmissionsPerIp: number;
+  maxAdmissionEntries: number;
+  idAttempts: number;
+}
+
+export interface SnapshotReasons {
+  authRejected: number;
+  policyRejected: number;
+  limited: number;
+  heartbeatReaped: number;
+  replayRejected: number;
+}
+
+export interface Snapshot {
+  state: 'idle' | 'starting' | 'running' | 'stopping' | 'stopped';
+  hosts: number;
+  sockets: number;
+  rawSockets: number;
+  controls: number;
+  clients: number;
+  pairs: number;
+  pending: number;
+  queuedBytes: number;
+  reasons: SnapshotReasons;
+}
+
+export interface Clock {
+  now: () => number;
+  setTimeout: typeof globalThis.setTimeout;
+  clearTimeout: typeof globalThis.clearTimeout;
+  setInterval: typeof globalThis.setInterval;
+  clearInterval: typeof globalThis.clearInterval;
+  setImmediate: typeof globalThis.setImmediate;
+}
+
+export interface Options {
+  host?: string;
+  port?: number;
+  path?: string;
+  trustProxy?: boolean;
+  requestHandler?: (request: IncomingMessage, response: ServerResponse) => boolean;
+  clock?: Partial<Clock>;
+  randomBytes?: (size: number) => Buffer;
+  logger?: Pick<Console, 'info' | 'warn' | 'error'>;
+  limits?: Partial<Limits>;
+  resolveClientIp?: (request: IncomingMessage) => string;
+  onSocketAccepted?: (connection: { socket: unknown; role: RelaySocketRole }) => void;
+}
+
+export interface ServerInstance {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  address(): string | AddressInfo | null | undefined;
+  readonly wsUrl: string | null;
+  getSnapshot(): Snapshot;
+}
+
+export function resolveRelayClientIp(request: IncomingMessage, trustProxy?: boolean): string;
+export function formatRelayWsUrl(host: string, port: number, relayPath: string): string;
+export function createPrivateRelayServer(options?: Options): ServerInstance;
+export function startPrivateRelayServer(options?: Options): Promise<ServerInstance>;

package/src/index.js

@@ -0,0 +1,366 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import { isIP } from 'node:net';
+import { WebSocketServer } from 'ws';
+
+const CLOSE = { replaced: 4001, duplicate: 4002, stuck: 4003, unavailable: 4008, auth: 4010, limit: 4029, away: 1012, malformed: 1008 };
+const B64 = /^[A-Za-z0-9_-]+$/;
+const SERVER_ID_BYTES = 32;
+const DEFAULT_LIMITS = {
+  maxUrlBytes: 4096, maxFieldBytes: 512, maxHosts: 256, maxSockets: 2048, maxConnections: 1000,
+  maxClientsPerHost: 100, maxClientsPerIp: 30, maxPendingClients: 30, pendingMs: 15_000,
+  maxRawSockets: 4096, maxRawSocketsPerIp: 128,
+  graceMs: 30_000, timestampSkewMs: 60_000, replayMs: 120_000, maxReplayEntries: 10_000,
+  maxFrameBytes: 128 * 1024, maxQueuedBytesPerConnection: 2 * 1024 * 1024,
+  maxGlobalQueuedBytes: 32 * 1024 * 1024, maxBufferedAmount: 2 * 1024 * 1024,
+  maxControlQueueEntries: 256, maxControlQueuedBytes: 2 * 1024 * 1024,
+  pumpRetryMs: 25, heartbeatMs: 30_000, handshakeMs: 10_000, closeDeadlineMs: 5_000,
+  admissionWindowMs: 60_000, maxAdmissionsPerIp: 120, maxAdmissionEntries: 10_000,
+  idAttempts: 4,
+};
+const fields = {
+  client: new Set(['v', 'role', 'serverId', 'grant']),
+  'host-control': new Set(['v', 'role', 'serverId', 'ts', 'sig', 'pk']),
+  'host-data': new Set(['v', 'role', 'serverId', 'connectionId', 'ts', 'sig', 'pk']),
+};
+const bytes = (value) => Buffer.byteLength(value, 'utf8');
+const canonical = (jwk) => JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });
+const b64 = (value, length) => {
+  if (typeof value !== 'string' || !B64.test(value)) return null;
+  try { const decoded = Buffer.from(value, 'base64url'); return decoded.length === length && decoded.toString('base64url') === value ? decoded : null; } catch { return null; }
+};
+
+export const resolveRelayClientIp = (request, trustProxy = false) => {
+  const remoteAddress = request.socket.remoteAddress ?? 'unknown';
+  if (!trustProxy) return remoteAddress;
+  const forwarded = request.headers['x-forwarded-for'];
+  const candidate = typeof forwarded === 'string' && !forwarded.includes(',') ? forwarded.trim() : '';
+  return isIP(candidate) ? candidate : remoteAddress;
+};
+
+export const formatRelayWsUrl = (host, port, relayPath) => `ws://${isIP(host) === 6 ? `[${host}]` : host}:${port}${relayPath}`;
+
+/** @param {string} encoded */
+const decodeJwk = (encoded) => {
+  const raw = b64(encoded, Buffer.byteLength(encoded, 'base64url'));
+  if (!raw) return null;
+  try {
+    const text = raw.toString('utf8'); const jwk = JSON.parse(text);
+    if (text !== canonical(jwk) || jwk.kty !== 'EC' || jwk.crv !== 'P-256' || !b64(jwk.x, 32) || !b64(jwk.y, 32)) return null;
+    return { jwk, key: crypto.createPublicKey({ key: jwk, format: 'jwk' }) };
+  } catch { return null; }
+};
+
+/**
+ * Creates the Layer 1 self-hosted relay. It routes opaque Layer 2/3 frames.
+ * @param {{ host?: string, port?: number, path?: string, trustProxy?: boolean, requestHandler?: (request: http.IncomingMessage, response: http.ServerResponse) => boolean, clock?: Partial<typeof globalThis>, randomBytes?: (size: number) => Buffer, logger?: Pick<Console, 'info'|'warn'|'error'>, limits?: Partial<typeof DEFAULT_LIMITS>, resolveClientIp?: (request: http.IncomingMessage) => string, onSocketAccepted?: ({ socket: import('ws').WebSocket, role: string }) => void }} options
+ */
+export const createPrivateRelayServer = (options = {}) => {
+  const limits = { ...DEFAULT_LIMITS, ...options.limits };
+  if (limits.replayMs < limits.timestampSkewMs * 2 || limits.maxReplayEntries < 1) throw new RangeError('invalid replay limits');
+  const clock = { now: Date.now, setTimeout, clearTimeout, setInterval, clearInterval, setImmediate, ...options.clock };
+  const randomBytes = options.randomBytes ?? crypto.randomBytes;
+  const hosts = new Map(); const replay = new Map(); const admissions = new Map(); const clientIpCounts = new Map(); const rawIpCounts = new Map();
+  const accepted = new Set(); const rawSockets = new Set();
+  const counts = { hosts: 0, sockets: 0, rawSockets: 0, controls: 0, clients: 0, pairs: 0, pending: 0, queuedBytes: 0 };
+  const reasons = { authRejected: 0, policyRejected: 0, limited: 0, heartbeatReaped: 0, replayRejected: 0 };
+  let server = null; let wss = null; let heartbeat = null; let startPromise = null; let stopPromise = null; let abortStart = null; let state = 'idle'; let generation = 0;
+  const addReason = (key) => { reasons[key] += 1; };
+  const snapshot = () => ({ state, ...counts, reasons: { ...reasons } });
+  const resolveClientIp = options.resolveClientIp ?? ((request) => resolveRelayClientIp(request, options.trustProxy));
+  const relayPath = options.path ?? '/ws';
+  const decrement = (map, key) => { const value = map.get(key) ?? 0; if (value <= 1) map.delete(key); else map.set(key, value - 1); };
+  const safeClose = (socket, code, reason = '') => {
+    if (socket.readyState === socket.CLOSED) return;
+    try {
+      if (socket.readyState === socket.OPEN || socket.readyState === socket.CONNECTING) socket.close(code, reason);
+      if (socket.readyState === socket.CLOSED) return;
+      if (socket.readyState !== socket.OPEN && socket.readyState !== socket.CONNECTING && socket.readyState !== socket.CLOSING) return;
+      if (!socket._relayCloseDeadline) socket._relayCloseDeadline = clock.setTimeout(() => {
+        socket._relayCloseDeadline = null;
+        if (socket.readyState !== socket.CLOSED) socket.terminate();
+      }, limits.closeDeadlineMs);
+    } catch { socket.terminate(); }
+  };
+  const purge = () => {
+    const now = clock.now();
+    for (const [key, expiry] of replay) if (expiry <= now) replay.delete(key);
+    for (const [key, record] of admissions) if (record.until <= now) admissions.delete(key);
+  };
+  const admitIp = (ip, role) => {
+    purge(); const key = `${role}:${ip}`; let record = admissions.get(key);
+    if (!record) {
+      if (admissions.size >= limits.maxAdmissionEntries) { addReason('limited'); return false; }
+      record = { count: 0, until: clock.now() + limits.admissionWindowMs }; admissions.set(key, record);
+    }
+    record.count += 1;
+    if (record.count > limits.maxAdmissionsPerIp) { addReason('limited'); return false; }
+    return true;
+  };
+  const removeSocket = (socket) => {
+    if (!accepted.delete(socket)) return;
+    counts.sockets -= 1;
+    if (socket._relayHandshake) clock.clearTimeout(socket._relayHandshake);
+    if (socket._relayCloseDeadline) clock.clearTimeout(socket._relayCloseDeadline);
+  };
+  const detachControl = (host, control, { code = CLOSE.away, reason = 'control closed', grace = true } = {}) => {
+    if (!control || hosts.get(host.serverId) !== host || host.control !== control || control.epoch !== host.epoch) return;
+    host.control = null;
+    counts.controls -= 1;
+    const queued = control.queuedBytes;
+    control.queue = []; control.queuedBytes = 0; control.busy = false;
+    counts.queuedBytes = Math.max(0, counts.queuedBytes - queued);
+    safeClose(control.socket, code, reason);
+    if (grace) beginGrace(host, control.epoch);
+  };
+  const controlPump = (host, message) => {
+    if (!host.control || host.control.epoch !== host.epoch) return;
+    const control = host.control; const payload = Buffer.from(JSON.stringify(message));
+    if (control.queue.length >= limits.maxControlQueueEntries || control.queuedBytes + payload.length > limits.maxControlQueuedBytes || counts.queuedBytes + payload.length > limits.maxGlobalQueuedBytes) {
+      addReason('limited'); detachControl(host, control, { code: CLOSE.limit, reason: 'control queue limit' }); return;
+    }
+    control.queue.push(payload); control.queuedBytes += payload.length; counts.queuedBytes += payload.length;
+    const pump = () => {
+      const control = host.control;
+      if (!control || control.epoch !== host.epoch || control.busy || !control.queue.length) return;
+      if (control.socket.readyState !== control.socket.OPEN) return detachControl(host, control, { code: CLOSE.away, reason: 'control unavailable' });
+      control.busy = true; const item = control.queue[0];
+      control.socket.send(item, { binary: false }, (error) => {
+        if (!host.control || host.control !== control || control.epoch !== host.epoch) return;
+        control.busy = false;
+        if (error) { detachControl(host, control, { code: CLOSE.away, reason: 'control send failure' }); return; }
+        control.queue.shift(); control.queuedBytes -= item.length; counts.queuedBytes = Math.max(0, counts.queuedBytes - item.length); pump();
+      });
+    };
+    pump();
+  };
+  const releasePump = (entry, pump) => {
+    if (pump.retry) clock.clearTimeout(pump.retry);
+    const total = pump.bytes; pump.queue = []; pump.bytes = 0; pump.busy = false; pump.retry = null;
+    entry.queuedBytes = Math.max(0, entry.queuedBytes - total);
+    counts.queuedBytes = Math.max(0, counts.queuedBytes - total);
+  };
+  const removeClient = (host, entry, code, reason, notify = true) => {
+    if (host.clients.get(entry.id) !== entry) return;
+    host.clients.delete(entry.id); counts.clients -= 1; decrement(clientIpCounts, entry.ip); if (entry.data) counts.pairs -= 1; else counts.pending -= 1;
+    if (entry.pendingTimer) clock.clearTimeout(entry.pendingTimer);
+    releasePump(entry, entry.toData); releasePump(entry, entry.toClient);
+    setRelayPaused(entry.client, false); setRelayPaused(entry.data, false);
+    if (entry.client) safeClose(entry.client, code, reason); if (entry.data) safeClose(entry.data, code, reason);
+    if (notify) controlPump(host, { type: 'disconnected', connectionId: entry.id });
+    if (!host.control && host.clients.size === 0 && !host.graceTimer && hosts.delete(host.serverId)) counts.hosts -= 1;
+  };
+  const expireHost = (host, epoch) => {
+    if (hosts.get(host.serverId) !== host || host.epoch !== epoch || host.control) return;
+    host.graceTimer = null;
+    for (const entry of [...host.clients.values()]) removeClient(host, entry, CLOSE.away, 'host went away', false);
+    if (hosts.get(host.serverId) === host && hosts.delete(host.serverId)) counts.hosts -= 1;
+  };
+  const beginGrace = (host, epoch) => {
+    if (hosts.get(host.serverId) !== host || host.epoch !== epoch || host.graceTimer) return;
+    host.graceTimer = clock.setTimeout(() => expireHost(host, epoch), limits.graceMs);
+  };
+  const pauseHigh = Math.max(1, Math.min(limits.maxQueuedBytesPerConnection - 1, Math.floor(limits.maxQueuedBytesPerConnection / 2)));
+  const pauseLow = Math.min(pauseHigh, Math.floor(limits.maxQueuedBytesPerConnection / 4));
+  const sourceOf = (entry, direction) => (direction === 'toData' ? entry.client : entry.data);
+  // Pause the fast sender when this direction's queue is above the high watermark.
+  const setRelayPaused = (socket, paused) => {
+    if (!socket || Boolean(socket._relayPaused) === paused) return;
+    if (paused && socket.readyState !== socket.OPEN) return;
+    try {
+      if (typeof socket.pause === 'function' && typeof socket.resume === 'function') {
+        if (paused) socket.pause();
+        else socket.resume();
+      } else {
+        const stream = socket._socket;
+        if (stream && typeof stream.pause === 'function') {
+          if (paused) stream.pause();
+          else stream.resume();
+        }
+      }
+    } catch { /* pause/resume only apply while OPEN */ }
+    socket._relayPaused = paused;
+  };
+  const applyBackpressure = (entry, direction) => {
+    const source = sourceOf(entry, direction);
+    if (!source) return;
+    const queued = entry[direction].bytes;
+    if (queued >= pauseHigh) setRelayPaused(source, true);
+    else if (queued <= pauseLow) setRelayPaused(source, false);
+  };
+  const fairReady = [];
+  let fairScheduled = false;
+  const requestPump = (host, entry, direction) => {
+    const channel = entry[direction];
+    if (channel.scheduled) return;
+    channel.scheduled = true;
+    fairReady.push({ host, entry, direction });
+    if (fairScheduled) return;
+    fairScheduled = true;
+    clock.setImmediate(runFairPump);
+  };
+  // One frame per ready pair per tick so a single tunnel cannot monopolize the event loop.
+  const runFairPump = () => {
+    fairScheduled = false;
+    const pending = fairReady.length;
+    for (let index = 0; index < pending; index += 1) {
+      const job = fairReady.shift();
+      if (!job) break;
+      job.entry[job.direction].scheduled = false;
+      sendOne(job.host, job.entry, job.direction);
+    }
+  };
+  const sendOne = (host, entry, direction) => {
+    const channel = entry[direction]; const target = direction === 'toData' ? entry.data : entry.client;
+    if (host.clients.get(entry.id) !== entry || channel.busy || !channel.queue.length) return;
+    if (!target || target.readyState !== target.OPEN || target.bufferedAmount > limits.maxBufferedAmount) {
+      if (!channel.retry) channel.retry = clock.setTimeout(() => { channel.retry = null; requestPump(host, entry, direction); }, limits.pumpRetryMs);
+      return;
+    }
+    channel.busy = true; const item = channel.queue[0];
+    target.send(item.data, { binary: item.binary }, (error) => {
+      if (host.clients.get(entry.id) !== entry || entry[direction] !== channel) return;
+      channel.busy = false;
+      if (error) { removeClient(host, entry, CLOSE.limit, 'send failure'); return; }
+      channel.queue.shift(); channel.bytes = Math.max(0, channel.bytes - item.data.length); entry.queuedBytes = Math.max(0, entry.queuedBytes - item.data.length); counts.queuedBytes = Math.max(0, counts.queuedBytes - item.data.length);
+      applyBackpressure(entry, direction);
+      if (channel.queue.length) requestPump(host, entry, direction);
+    });
+  };
+  const enqueue = (host, entry, direction, data, binary) => {
+    const payload = Buffer.from(data); const channel = entry[direction];
+    if (payload.length > limits.maxFrameBytes || entry.queuedBytes + payload.length > limits.maxQueuedBytesPerConnection || counts.queuedBytes + payload.length > limits.maxGlobalQueuedBytes) { addReason('limited'); removeClient(host, entry, CLOSE.limit, 'queue limit'); return; }
+    channel.queue.push({ data: payload, binary }); channel.bytes += payload.length; entry.queuedBytes += payload.length; counts.queuedBytes += payload.length;
+    applyBackpressure(entry, direction);
+    requestPump(host, entry, direction);
+  };
+  const bindClient = (host, entry, socket) => {
+    entry.client = socket;
+    socket.on('message', (data, binary) => enqueue(host, entry, 'toData', data, binary));
+    socket.on('close', () => removeClient(host, entry, 1000, '', true)); socket.on('error', () => {});
+  };
+  const bindData = (host, entry, socket) => {
+    entry.data = socket; counts.pending -= 1; counts.pairs += 1; if (entry.pendingTimer) clock.clearTimeout(entry.pendingTimer);
+    socket.on('message', (data, binary) => enqueue(host, entry, 'toClient', data, binary));
+    socket.on('close', () => { if (host.clients.get(entry.id) === entry && entry.data === socket) removeClient(host, entry, CLOSE.away, 'host data closed'); }); socket.on('error', () => {});
+    requestPump(host, entry, 'toData');
+  };
+  const parse = (request) => {
+    if (!request.url || bytes(request.url) > limits.maxUrlBytes) return null;
+    let url; try { url = new URL(request.url, 'http://relay'); } catch { return null; }
+    if (url.pathname !== relayPath) return null;
+    const role = url.searchParams.get('role'); const allowed = fields[role];
+    if (!allowed || url.searchParams.get('v') !== '1') return null;
+    for (const [key, value] of url.searchParams) if (!allowed.has(key) || url.searchParams.getAll(key).length !== 1 || bytes(value) > limits.maxFieldBytes) return null;
+    for (const key of allowed) if (key !== 'grant' && !url.searchParams.has(key)) return null;
+    const serverId = url.searchParams.get('serverId');
+    if (!b64(serverId, SERVER_ID_BYTES)) return null;
+    const connectionId = url.searchParams.get('connectionId');
+    if (connectionId && !b64(connectionId, 16)) return null;
+    return { role, serverId, connectionId, params: url.searchParams };
+  };
+  const authenticate = (parsed) => {
+    if (parsed.role === 'client') return true;
+    const ts = parsed.params.get('ts'); const sig = parsed.params.get('sig'); const pk = parsed.params.get('pk');
+    if (!/^(0|[1-9][0-9]{0,15})$/.test(ts ?? '')) return false;
+    const timestamp = Number(ts); if (!Number.isSafeInteger(timestamp) || Math.abs(clock.now() - timestamp) > limits.timestampSkewMs) return false;
+    const signature = b64(sig, 64); const publicKey = decodeJwk(pk);
+    if (!signature || !publicKey) return false;
+    const id = crypto.createHash('sha256').update(canonical(publicKey.jwk)).digest('base64url'); if (id !== parsed.serverId) return false;
+    const key = `${parsed.serverId}.${parsed.role}.${parsed.connectionId ?? ''}.${ts}`;
+    purge(); if (replay.has(key) || replay.size >= limits.maxReplayEntries) { addReason('replayRejected'); return false; }
+    const message = `${ts}.${parsed.serverId}.${parsed.role}.${parsed.connectionId ?? ''}`;
+    if (!crypto.verify('SHA256', Buffer.from(message), { key: publicKey.key, dsaEncoding: 'ieee-p1363' }, signature)) return false;
+    replay.set(key, clock.now() + limits.replayMs); return true;
+  };
+  const idFor = (host) => {
+    for (let attempt = 0; attempt < limits.idAttempts; attempt += 1) { const id = Buffer.from(randomBytes(16)).toString('base64url'); if (id.length === 22 && !host.clients.has(id)) return id; }
+    return null;
+  };
+  const attach = (socket, request, parsed) => {
+    const ip = resolveClientIp(request); socket._relayRole = parsed.role; socket._relayAlive = true;
+    socket.on('pong', () => { socket._relayAlive = true; });
+    if (parsed.role === 'host-control') {
+      let host = hosts.get(parsed.serverId);
+      if (!host && counts.hosts >= limits.maxHosts) { addReason('limited'); return safeClose(socket, CLOSE.limit, 'host limit'); }
+      if (!host) { host = { serverId: parsed.serverId, clients: new Map(), control: null, epoch: 0, graceTimer: null }; hosts.set(parsed.serverId, host); counts.hosts += 1; }
+      if (host.control) { const previous = host.control; host.epoch += 1; for (const entry of [...host.clients.values()]) removeClient(host, entry, CLOSE.replaced, 'control replaced', false); host.epoch -= 1; detachControl(host, previous, { code: CLOSE.replaced, reason: 'control replaced', grace: false }); }
+      if (host.graceTimer) { clock.clearTimeout(host.graceTimer); host.graceTimer = null; }
+      host.epoch += 1; const epoch = host.epoch; host.control = { socket, epoch, queue: [], queuedBytes: 0, busy: false }; counts.controls += 1;
+      socket.on('close', () => detachControl(host, host.control?.socket === socket ? host.control : null, { code: CLOSE.away, reason: 'control closed' })); socket.on('error', () => {});
+      controlPump(host, { type: 'sync', connectionIds: [...host.clients.keys()] }); return;
+    }
+    if (parsed.role === 'client') {
+      const host = hosts.get(parsed.serverId);
+      if (!host) return safeClose(socket, CLOSE.unavailable, 'host unavailable');
+      if (counts.clients >= limits.maxConnections || host.clients.size >= limits.maxClientsPerHost || counts.pending >= limits.maxPendingClients || (clientIpCounts.get(ip) ?? 0) >= limits.maxClientsPerIp) { addReason('limited'); return safeClose(socket, CLOSE.limit, 'client limit'); }
+      const id = idFor(host); if (!id) { addReason('limited'); return safeClose(socket, CLOSE.limit, 'id collision'); }
+      const entry = { id, ip, client: null, data: null, queuedBytes: 0, toData: { queue: [], bytes: 0, busy: false, retry: null, scheduled: false }, toClient: { queue: [], bytes: 0, busy: false, retry: null, scheduled: false }, pendingTimer: null };
+      host.clients.set(id, entry); counts.clients += 1; counts.pending += 1; clientIpCounts.set(ip, (clientIpCounts.get(ip) ?? 0) + 1); bindClient(host, entry, socket);
+      entry.pendingTimer = clock.setTimeout(() => { if (host.clients.get(id) === entry && !entry.data) removeClient(host, entry, CLOSE.limit, 'pending timeout'); }, limits.pendingMs);
+      controlPump(host, { type: 'connected', connectionId: id }); return;
+    }
+    const host = hosts.get(parsed.serverId); const entry = host?.clients.get(parsed.connectionId);
+    if (!host || !entry || entry.data) return safeClose(socket, CLOSE.duplicate, 'data attach');
+    bindData(host, entry, socket);
+  };
+  const reject = (request, socket, head, code) => wss.handleUpgrade(request, socket, head, (ws) => safeClose(ws, code, 'rejected'));
+  const start = () => {
+    if (state === 'running') return Promise.resolve(); if (state === 'stopping') return stopPromise.then(() => start()); if (startPromise) return startPromise;
+    state = 'starting'; const localGeneration = ++generation; const localServer = http.createServer((request, response) => {
+      if (options.requestHandler?.(request, response) || response.writableEnded) return;
+      const pathname = new URL(request.url ?? '/', 'http://relay').pathname;
+      const ready = pathname === '/readyz' && state === 'running';
+      const healthy = pathname === '/healthz';
+      response.setHeader('cache-control', 'no-store');
+      if ((healthy || ready) && (request.method === 'GET' || request.method === 'HEAD')) {
+        response.writeHead(200, { 'content-type': 'application/json' });
+        response.end(request.method === 'HEAD' ? undefined : '{"status":"ok"}');
+        return;
+      }
+      response.writeHead(404); response.end();
+    }); const localWss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: limits.maxFrameBytes }); server = localServer; wss = localWss;
+    localServer.on('connection', (socket) => {
+      const ip = socket.remoteAddress ?? 'unknown';
+      if (counts.rawSockets >= limits.maxRawSockets || (rawIpCounts.get(ip) ?? 0) >= limits.maxRawSocketsPerIp) { addReason('limited'); socket.destroy(); return; }
+      rawSockets.add(socket); counts.rawSockets += 1; rawIpCounts.set(ip, (rawIpCounts.get(ip) ?? 0) + 1); socket._relayRawIp = ip;
+      socket._relayTcpTimer = clock.setTimeout(() => socket.destroy(), limits.handshakeMs);
+      socket.on('close', () => { if (socket._relayTcpTimer) clock.clearTimeout(socket._relayTcpTimer); if (rawSockets.delete(socket)) { counts.rawSockets -= 1; decrement(rawIpCounts, ip); } });
+    });
+    localServer.on('upgrade', (request, socket, head) => {
+      if (socket._relayTcpTimer) { clock.clearTimeout(socket._relayTcpTimer); socket._relayTcpTimer = null; }
+      const parsed = parse(request); const ip = resolveClientIp(request);
+      if (!parsed) { addReason('policyRejected'); return reject(request, socket, head, CLOSE.malformed); }
+      if (!admitIp(ip, parsed.role)) return reject(request, socket, head, CLOSE.limit);
+      if (!authenticate(parsed)) { addReason('authRejected'); return reject(request, socket, head, CLOSE.auth); }
+      if (counts.sockets >= limits.maxSockets) { addReason('limited'); return reject(request, socket, head, CLOSE.limit); }
+      localWss.handleUpgrade(request, socket, head, (ws) => { accepted.add(ws); counts.sockets += 1; ws.on('close', () => removeSocket(ws)); ws._relayHandshake = clock.setTimeout(() => { if (!ws._relayRole) safeClose(ws, CLOSE.malformed, 'handshake timeout'); }, limits.handshakeMs); options.onSocketAccepted?.({ socket: ws, role: parsed.role }); attach(ws, request, parsed); if (ws._relayHandshake) { clock.clearTimeout(ws._relayHandshake); ws._relayHandshake = null; } });
+    });
+    heartbeat = clock.setInterval(() => { purge(); for (const socket of accepted) { if (socket.readyState !== socket.OPEN) continue; if (socket._relayPaused) socket._relayAlive = true; if (!socket._relayAlive) { addReason('heartbeatReaped'); safeClose(socket, socket._relayRole === 'host-control' ? CLOSE.stuck : CLOSE.away, 'heartbeat'); continue; } socket._relayAlive = false; try { socket.ping(); } catch { safeClose(socket, CLOSE.away, 'heartbeat'); } } }, limits.heartbeatMs);
+    startPromise = new Promise((resolve, rejectStart) => {
+      const fail = (error) => { if (localGeneration !== generation) return; localServer.off('listening', ready); cleanupStart(); rejectStart(error); };
+      const ready = () => { localServer.off('error', fail); if (localGeneration !== generation || state !== 'starting') return; state = 'running'; resolve(); };
+      const cleanupStart = () => { if (heartbeat) { clock.clearInterval(heartbeat); heartbeat = null; } localWss.close(); localServer.close(); if (server === localServer) { server = null; wss = null; } state = 'stopped'; };
+      abortStart = () => { if (state === 'starting') { cleanupStart(); rejectStart(new Error('relay stopped during start')); } };
+      localServer.once('error', fail); localServer.once('listening', ready); localServer.listen(options.port ?? 0, options.host ?? '127.0.0.1');
+    }).finally(() => { startPromise = null; abortStart = null; });
+    return startPromise;
+  };
+  const stop = () => {
+    if (stopPromise) return stopPromise;
+    if (state === 'idle' || state === 'stopped') { state = 'stopped'; return Promise.resolve(); }
+    if (state === 'starting') abortStart?.();
+    state = 'stopping'; generation += 1; const localServer = server; const localWss = wss;
+    stopPromise = new Promise((resolve) => {
+      if (heartbeat) { clock.clearInterval(heartbeat); heartbeat = null; }
+      for (const host of hosts.values()) { if (host.graceTimer) clock.clearTimeout(host.graceTimer); if (host.control) detachControl(host, host.control, { code: CLOSE.away, reason: 'server stopping', grace: false }); for (const entry of [...host.clients.values()]) removeClient(host, entry, CLOSE.away, 'server stopping', false); }
+      hosts.clear(); replay.clear(); admissions.clear(); clientIpCounts.clear(); counts.hosts = 0; counts.controls = 0; counts.clients = 0; counts.pairs = 0; counts.pending = 0; counts.queuedBytes = 0;
+      for (const socket of accepted) { if (socket._relayCloseDeadline) clock.clearTimeout(socket._relayCloseDeadline); socket.terminate(); } for (const socket of rawSockets) socket.destroy(); accepted.clear(); rawSockets.clear(); rawIpCounts.clear(); counts.sockets = 0; counts.rawSockets = 0;
+      if (!localServer) return resolve(); localWss?.close(); localServer.close(() => resolve()); clock.setTimeout(resolve, 100);
+    }).then(() => { if (server === localServer && wss === localWss) { server = null; wss = null; state = 'stopped'; } stopPromise = null; });
+    return stopPromise;
+  };
+  return { start, stop, address: () => server?.address(), get wsUrl() { const address = server?.address(); return address && typeof address === 'object' ? formatRelayWsUrl(options.host ?? '127.0.0.1', address.port, relayPath) : null; }, getSnapshot: snapshot };
+};
+
+export const startPrivateRelayServer = async (options) => { const relay = createPrivateRelayServer(options); await relay.start(); return relay; };