@openchambery/relay-server 1.19.17 → 1.19.19-beta.1

package/DOCUMENTATION.md

@@ -8,7 +8,7 @@ The Relay server brokers Layer 1 routing: Host control connections, client route
 
 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.
+Relay v1 admission accepts anonymous Client route requests. Per-IP, global, pending-connection, raw-socket, frame, and queue limits bound that public entry point. Host-control upgrades are separately bounded per IP and per `serverId` so a Host reconnect loop cannot monopolize the listener; a limited Host-control upgrade is `4029` and does not replace a live control socket. Relay does not inspect Host or Client application versions — mixed app versions are a Host/Client concern, and unsupported Layer 1 fields are ignored rather than version-gated. 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.
 
@@ -259,9 +259,11 @@ For an IPv6 literal in a public URL, enclose the host in brackets: `wss://[2001:
 | `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_ADMISSION_WINDOW_MS` | `60000` | ms admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSIONS_PER_IP` | `120` | Client, Host-data, and malformed upgrades per role/IP per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOST_CONTROL_ADMISSIONS_PER_IP` | `30` | Host-control upgrades per IP per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOST_CONTROL_ADMISSIONS_PER_SERVER` | `12` | Host-control upgrades per `serverId` per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSION_ENTRIES` | `10000` | tracked admission records |
 | `OPENCHAMBER_RELAY_SERVER_ID_ATTEMPTS` | `4` | random connection-ID attempts |
 
 Host Push URL (OpenChamber Host, not the Push process):

package/README.md

@@ -284,9 +284,11 @@ Trusted-proxy mode accepts exactly one valid IP address in `X-Forwarded-For`. Cl
 | `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_ADMISSION_WINDOW_MS` | `60000` | ms admission window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSIONS_PER_IP` | `120` | Client, Host-data, and malformed upgrades per role/IP per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOST_CONTROL_ADMISSIONS_PER_IP` | `30` | Host-control upgrades per IP per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_HOST_CONTROL_ADMISSIONS_PER_SERVER` | `12` | Host-control upgrades per `serverId` per window |
+| `OPENCHAMBER_RELAY_SERVER_MAX_ADMISSION_ENTRIES` | `10000` | tracked admission records |
 | `OPENCHAMBER_RELAY_SERVER_ID_ATTEMPTS` | `4` | random connection-ID attempts |
 
 ### Host Push URL override
@@ -436,6 +438,7 @@ These assets define an optional follow-on deployment path. Validate the image, p
 | 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. |
+| One Host reconnects host-control thousands of times per hour | Relay does not version-gate Hosts. A live control is kept when a later host-control admission is limited (`4029`). Review `MAX_HOST_CONTROL_ADMISSIONS_PER_SERVER` / `_PER_IP` and the Host's control backoff. |
 | 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`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/relay-server",
-  "version": "1.19.17",
+  "version": "1.19.19-beta.1",
   "description": "Self-hosted private relay server for OpenChamber",
   "private": false,
   "type": "module",

package/src/cli.js

@@ -1,7 +1,7 @@
 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 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', 'maxHostControlAdmissionsPerIp', 'maxHostControlAdmissionsPerServer', '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}`); };

package/src/index.d.ts

@@ -31,6 +31,8 @@ export interface Limits {
   closeDeadlineMs: number;
   admissionWindowMs: number;
   maxAdmissionsPerIp: number;
+  maxHostControlAdmissionsPerIp: number;
+  maxHostControlAdmissionsPerServer: number;
   maxAdmissionEntries: number;
   idAttempts: number;
 }

package/src/index.js

@@ -15,7 +15,8 @@ const DEFAULT_LIMITS = {
   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,
+  admissionWindowMs: 60_000, maxAdmissionsPerIp: 120,
+  maxHostControlAdmissionsPerIp: 30, maxHostControlAdmissionsPerServer: 12, maxAdmissionEntries: 10_000,
   idAttempts: 4,
 };
 const fields = {
@@ -87,16 +88,23 @@ export const createPrivateRelayServer = (options = {}) => {
     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);
+  const admit = (key, cap) => {
+    purge(); 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; }
+    if (record.count > cap) { addReason('limited'); return false; }
     return true;
   };
+  const admitUpgrade = (ip, parsed) => {
+    if (parsed.role === 'host-control') {
+      return admit(`host-control:${ip}`, limits.maxHostControlAdmissionsPerIp)
+        && admit(`host-control-server:${parsed.serverId}`, limits.maxHostControlAdmissionsPerServer);
+    }
+    return admit(`${parsed.role}:${ip}`, limits.maxAdmissionsPerIp);
+  };
   const removeSocket = (socket) => {
     if (!accepted.delete(socket)) return;
     counts.sockets -= 1;
@@ -330,8 +338,11 @@ export const createPrivateRelayServer = (options = {}) => {
     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 (!parsed) {
+        if (!admit(`malformed:${ip}`, limits.maxAdmissionsPerIp)) return reject(request, socket, head, CLOSE.limit);
+        addReason('policyRejected'); return reject(request, socket, head, CLOSE.malformed);
+      }
+      if (!admitUpgrade(ip, parsed)) 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; } });