@camstack/server 1.1.60 → 1.1.62

package/dist/api/trpc/trpc.router.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichInputWithUserAgent = enrichInputWithUserAgent;
+exports.enrichInputWithRelayClass = enrichInputWithRelayClass;
 exports.wrapWebrtcSessionProviderWithRelay = wrapWebrtcSessionProviderWithRelay;
 exports.buildAppRouter = buildAppRouter;
 const addon_settings_router_js_1 = require("../core/addon-settings.router.js");
@@ -39,30 +40,93 @@ function enrichInputWithUserAgent(input, userAgent) {
     };
 }
 /**
- * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
+ * Operator gate for FORCING TURN-relay-only ICE on genuinely-remote viewers.
+ * DEFAULT OFF.
  *
- * It was meant to give CGNAT/4G viewers a clean relay↔relay path, but werift's
- * TURN media-forward is unreliable between two real TURN servers (relay↔relay
- * connects yet media never arrives → connected-but-black), and forcing relay
- * ALSO kills the direct LAN/Tailscale host pair — which carries full native
- * quality with no relay. We now offer ALL candidates (host incl. the hub's
- * advertised Tailscale address, srflx, relay) and let ICE nominate the best
- * reachable pair: direct when possible, relay only as a fallback. The
- * `relayOnly` cap field + broker support remain for when relay media-forward
- * is fixed.
+ * The forced relay↔relay path is disabled by default because it was NEVER
+ * validated to deliver media. It was originally disabled on 2026-05-26 after a
+ * connected relay session produced a black picture — ICE/DTLS completed but no
+ * decodable media was forwarded over the relay (a MEDIA-FORWARD reliability
+ * bug, not a signalling one). The later werift+0.22.9 patch
+ * (`patches/werift+0.22.9.patch`) fixed a DIFFERENT bug — a host/srflx
+ * candidate LEAK in the forced-relay SDP — and does nothing for relay
+ * media-forward, so the connected-but-black regression remains unproven-fixed.
  *
- * The wrapper additionally enriches the `createSession` / `handleOffer`
- * subscriber attribution with the originating client's User-Agent, read
- * from the tRPC request context (browser sessions). All OTHER methods
- * delegate straight through — auth, the remote-proxy factory and every
- * signaling behaviour are untouched.
+ * Until an operator confirms that ONE real remote relay session (4G /
+ * Cloudflare-tunnel) actually delivers media, remote viewers stay on the same
+ * `relayOnly:false` path as everyone else. Set `CAMSTACK_FORCE_RELAY_REMOTE=1`
+ * (or `true`) to re-enable remote→relay once validated; the broker's pairClass
+ * logging is the instrument for that validation.
+ */
+const FORCE_RELAY_REMOTE = process.env.CAMSTACK_FORCE_RELAY_REMOTE === '1' ||
+    process.env.CAMSTACK_FORCE_RELAY_REMOTE === 'true';
+/**
+ * Inject the SERVER-computed `relayOnly` ICE override.
+ *
+ * The client's three-way classification (`lan | vpn | remote`, see
+ * `client-ip.ts`) is ALWAYS computed by the caller and passed here so the
+ * broker's pairClass logging can observe the viewer class for every session.
+ * Whether that class actually forces a relay is gated by
+ * `FORCE_RELAY_REMOTE` (default OFF — see above):
+ *   - gate OFF → `relayOnly: false` for ALL classes (today's effective,
+ *     validated behaviour: nobody is forced onto the unproven relay path).
+ *   - gate ON  → `deriveRelayOnly(clientClass)` — only genuinely-remote
+ *     viewers (public / CGNAT-4G / Cloudflare-tunnel) get `relayOnly: true`;
+ *     `lan` and `vpn` (Tailscale) keep the low-latency direct host/srflx path.
+ *
+ * When the class is `null` (mesh-originated call — no request context) the
+ * input passes through UNCHANGED so a trusted addon-set `relayOnly` (e.g.
+ * Alexa) is never clobbered. Any client-supplied `relayOnly` on a
+ * request-bound call IS overwritten — the hub trusts only the request context.
+ *
+ * Immutable — builds a NEW input object, never mutates the caller's.
+ */
+function enrichInputWithRelayClass(input, clientClass) {
+    if (clientClass === null)
+        return input;
+    const relayOnly = FORCE_RELAY_REMOTE ? (0, client_ip_js_1.deriveRelayOnly)(clientClass) : false;
+    return { ...input, relayOnly };
+}
+/**
+ * Per-request wrapper around the resolved `webrtc-session` broker singleton.
+ *
+ * Two SERVER-side enrichments, both read from the tRPC request context (the
+ * broker is a forked addon that cannot see the HTTP request):
+ *  1. `relayOnly` — the ICE policy. The client is classified three ways
+ *     (`lan | vpn | remote`, 2026-07-15): Tailscale (`vpn`) is distinguished
+ *     from genuine internet (`remote`) and Cloudflare Tunnel's
+ *     `CF-Connecting-IP` on the loopback connector path is honoured, closing
+ *     the two blind spots the boolean classifier had (a tailnet client on the
+ *     hub's own 100.64/10 address is `vpn`; a Cloudflare-tunneled viewer with
+ *     a loopback socket peer is `remote`, not misread as LAN). The class is
+ *     ALWAYS computed and threaded so the broker's pairClass logging can
+ *     observe it — but FORCING remote viewers onto a relay↔relay path is
+ *     GATED OFF by default (`CAMSTACK_FORCE_RELAY_REMOTE`, see
+ *     `enrichInputWithRelayClass`).
+ *
+ *     Why gated: the forced-relay MEDIA-FORWARD path was disabled on
+ *     2026-05-26 because a connected relay session delivered NO decodable
+ *     media (ICE/DTLS up, picture black). The werift+0.22.9 patch
+ *     (`patches/werift+0.22.9.patch`) fixed a DIFFERENT bug — the forced-relay
+ *     SDP host/srflx candidate LEAK — and does NOT address relay
+ *     media-forward, so the connected-but-black regression is still unproven-
+ *     fixed. The flag lets the operator re-enable remote→relay only after
+ *     validating that ONE real 4G / Cloudflare-tunnel relay session actually
+ *     delivers media (the broker pairClass logging is the instrument). Until
+ *     then every class gets `relayOnly:false`.
+ *  2. `consumerAttribution.userAgent` — the browser UA for the broker's
+ *     client list.
+ *
+ * All OTHER methods delegate straight through — auth, the remote-proxy
+ * factory and every signaling behaviour are untouched.
  */
 function wrapWebrtcSessionProviderWithRelay(provider, ctx) {
     const userAgent = (0, client_ip_js_1.extractUserAgent)(ctx.req);
+    const clientClass = (0, client_ip_js_1.classifyClientRequest)(ctx.req);
     return {
         ...provider,
-        createSession: (input) => provider.createSession(enrichInputWithUserAgent(input, userAgent)),
-        handleOffer: (input) => provider.handleOffer(enrichInputWithUserAgent(input, userAgent)),
+        createSession: (input) => provider.createSession(enrichInputWithRelayClass(enrichInputWithUserAgent(input, userAgent), clientClass)),
+        handleOffer: (input) => provider.handleOffer(enrichInputWithRelayClass(enrichInputWithUserAgent(input, userAgent), clientClass)),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.1.60",
+  "version": "1.1.62",
   "private": false,
   "files": [
     "dist",
@@ -23,19 +23,19 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.1.49",
-    "@camstack/addon-advanced-notifier": "1.1.22",
-    "@camstack/addon-auth": "1.1.7",
-    "@camstack/addon-decoder-nodeav": "1.1.10",
-    "@camstack/addon-notifiers": "1.1.22",
-    "@camstack/addon-pipeline": "1.1.54",
-    "@camstack/addon-pipeline-orchestrator": "1.1.44",
-    "@camstack/addon-post-analysis": "1.1.26",
-    "@camstack/sdk": "1.1.23",
-    "@camstack/shm-ring": "1.0.22",
-    "@camstack/system": "1.1.47",
-    "@camstack/types": "1.1.42",
-    "@camstack/ui-library": "1.1.34",
+    "@camstack/addon-admin-ui": "1.1.51",
+    "@camstack/addon-advanced-notifier": "1.1.24",
+    "@camstack/addon-auth": "1.1.9",
+    "@camstack/addon-decoder-nodeav": "1.1.11",
+    "@camstack/addon-notifiers": "1.1.23",
+    "@camstack/addon-pipeline": "1.1.56",
+    "@camstack/addon-pipeline-orchestrator": "1.1.46",
+    "@camstack/addon-post-analysis": "1.1.28",
+    "@camstack/sdk": "1.1.24",
+    "@camstack/shm-ring": "1.0.23",
+    "@camstack/system": "1.1.49",
+    "@camstack/types": "1.1.44",
+    "@camstack/ui-library": "1.1.36",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",