@rapidmx/meet-plugin 0.15.0 → 0.16.0

package/dist/apps/shared/push/GuestSignalingClient.js

@@ -1,312 +0,0 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-/**
- * A standalone `SignalingChannel` (`../webrtc/types.js`) over `@rapidrest/service-core`'s `/push` WebSocket -
- * built from scratch rather than reusing `@rapidmx/web-client`'s `PushClient`/`getPushClient()` (`lib/mail/pushClient.js`).
- *
- * ## Why not `PushClient`
- *
- * `PushClient` was investigated first, as this plugin's Phase 2 `.claude/NOTES.md` entry required. Its `connect()`
- * opens a bare `new WebSocket(url)` and relies entirely on the browser automatically attaching this deployment's
- * `jwt` `HttpOnly` cookie to the upgrade request - it never sends a token of its own (see its own doc comment:
- * "a script can't read that cookie, so there is no token to send"). That fits the webmail tab's own authenticated
- * session perfectly, but this plugin's anonymous guest has no such cookie at all - only the bearer `token`
- * `BaseVideoMeetingRoute.join()` minted, handed to this client explicitly. `PushClient`'s API has no parameter
- * anywhere to supply that token, and its shared-singleton design (`getPushClient()`, one client per tab) is itself
- * the wrong shape here too: a guest's signaling identity must never be confused with (or silently share a socket
- * with) whatever webmail session, if any, happens to already be open in the same browser. So this module
- * implements the same wire protocol independently instead - see `../../.claude/NOTES.md` and
- * `BasePushRoute`/`JWTStrategy` (`@rapidrest/service-core`) for the protocol this matches:
- *
- * - `wss://<origin>/push` - authenticated at the WebSocket upgrade. A real browser `WebSocket` cannot attach a
- * custom `Authorization` header to that upgrade request at all (a WHATWG API limitation, not something any
- * client-side code can work around) - `JWTStrategy.getAuthToken()`'s only other source is the same `jwt` cookie
- * `PushClient` already relies on. When `token` is supplied (the common anonymous/guest case -
- * `VideoMeetingJoinResult.authenticated` is `false`), this client sets that cookie itself, to `token`, immediately
- * before connecting (`applyAuthCookie()`). When `token` is omitted (the caller already authenticated as a real
- * RapidMX identity in `join()` - `authenticated: true` - see the FIXED LIMITATION below), this client writes no
- * cookie at all and simply lets the browser attach whatever real `jwt` session cookie already exists for this
- * origin, exactly as `PushClient` does for an ordinary webmail session.
- * - Right after connecting, the server sends `{ id: 0, type: "SUBSCRIBED", data: [...] }` (channels the socket
- * already holds - the caller's own uid channel, never this meeting's). `connect()` then explicitly `SUBSCRIBE`s to
- * the one meeting channel and waits for the matching `{ id, type: "SUBSCRIBED", data }` reply, resolving once
- * `channel` is actually in that reply's `data` (rejecting otherwise - an unauthorized/expired token, or the
- * meeting's ACL grant somehow missing).
- * - Publishing (`send()`) is **not** a WebSocket message at all - `BasePushRoute.send()` is `POST /push/:id`, a
- * perfectly ordinary authenticated HTTP endpoint. When `token` is supplied it's sent there as a normal
- * `Authorization: Bearer` header (no browser limitation applies to a plain `fetch()`); when it's omitted, the
- * request carries no `Authorization` header at all and instead relies on `fetch()`'s own default same-origin
- * credentials mode, which already attaches the browser's real `jwt` cookie to a same-origin request with zero
- * extra code - `JWTStrategy.getAuthToken()`'s cookie fallback authenticates it exactly as it would any other
- * same-origin authenticated call. Either way `send()` also attaches the CSRF double-submit header
- * (`withCsrfHeader()`) - required server-side only for the cookie case, but harmless to send for the bearer one
- * too - see `send()`'s own doc comment. Fire-and-forget either way, matching every other push publish in this
- * codebase - a failed send is logged, never thrown, since a caller (`MeshConnectionManager`) has no meaningful
- * per-message retry of its own.
- * - An incoming meeting message arrives wrapped `{ type: "MESSAGE", channel, data: <the posted body> }` - this
- * client unwraps it and delivers `data` (expected to be a `SignalMessage`) to `onMessage()` listeners.
- *
- * ## FIXED: the browser-session-collision limitation this module used to carry
- *
- * Phase 2 originally always wrote the guest `token` as the `jwt` cookie before connecting, unconditionally. If the
- * visiting browser already held a *real*, `HttpOnly` `jwt` session cookie for this exact origin (a logged-in
- * RapidMX user, e.g. with webmail open), that write was silently blocked by the browser's own "script cannot
- * override an `HttpOnly` cookie of the same name" protection - the WebSocket then authenticated as that real
- * session instead of the intended guest identity, and since the meeting's `AccessControlList` grant only named the
- * guest uid, the real session's `SUBSCRIBE` was simply refused. Net effect: a logged-in user could never actually
- * join a call at all (safe - never a cross-identity leak - but broken).
- *
- * The fix is in `BaseVideoMeetingRoute.join()` (backend): when the caller already presents a valid session for a
- * real RapidMX identity, it grants *that* identity's own uid on the meeting's channel directly and returns
- * `authenticated: true` with no guest `token` at all - see `VideoMeetingJoinResult`'s doc comment. This module's
- * own half of the fix is simply to stop writing a cookie (and stop sending a bearer header) whenever `token` is
- * absent, as described above - the browser's real cookie was always going to win that write anyway, so the
- * correct behavior is to not fight it and let it authenticate normally instead.
- */
-import { apiOrigin, withCsrfHeader } from "@rapidmx/web-client/lib/util/api.js";
-import { pushUrl } from "@rapidmx/web-client/lib/mail/pushClient.js";
-const SOCKET_OPEN = 1;
-function defaultSocketFactory() {
-    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url);
-}
-/** The cookie name `JWTStrategyOptions.cookieName` defaults to (and this deployment always uses - see
- * `BaseVideoMeetingRoute`'s guest JWT doc comment, signed with the same `auth` config every other token is). */
-const AUTH_COOKIE_NAME = "jwt";
-/** The first reconnect waits about this long, doubling on each further failure, matching `PushClient`'s own
- * constants (kept independent rather than imported, since this module deliberately doesn't depend on
- * `pushClient.ts` beyond its `pushUrl()` helper - see this module's doc comment on why it isn't `PushClient` itself). */
-export const SIGNALING_BACKOFF_BASE_MS = 1000;
-export const SIGNALING_BACKOFF_MAX_MS = 30000;
-export class GuestSignalingClient {
-    constructor(options) {
-        this.options = options;
-        this.closed = false;
-        this.nextRequestId = 1;
-        this.attempt = 0;
-        this.cookieApplied = false;
-        this.listeners = new Set();
-    }
-    /** Connects, authenticates (see this module's doc comment) and subscribes to the meeting's own channel.
-     * Resolves once genuinely ready to send/receive; rejects if the channel is refused (an invalid/expired token,
-     * or - now fixed rather than merely possible, see the FIXED LIMITATION section above - a stale grant) or there
-     * is nothing to connect with at all (no `WebSocket`, e.g. a non-HTTPS context in some browsers - the lobby's
-     * own device-support checks already cover the more common case of no `mediaDevices`, but this is an
-     * independent capability). Calling this a second time on an already-closed client rejects immediately. */
-    connect() {
-        if (this.closed) {
-            return Promise.reject(new Error("This signaling client has already been closed."));
-        }
-        return new Promise((resolve, reject) => {
-            this.pendingConnect = { resolve, reject };
-            this.openSocket();
-        });
-    }
-    /** Closes the socket, stops reconnecting and clears the guest auth cookie this client applied (see
-     * `applyAuthCookie()`) - idempotent. */
-    close() {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        clearTimeout(this.timer);
-        this.timer = undefined;
-        const socket = this.socket;
-        this.socket = undefined;
-        if (socket) {
-            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
-            try {
-                socket.close(1000, "closing");
-            }
-            catch {
-                // Already gone.
-            }
-        }
-        this.clearAuthCookie();
-        this.listeners.clear();
-        this.pendingConnect?.reject(new Error("Closed before the signaling channel connected."));
-        this.pendingConnect = undefined;
-    }
-    onMessage(handler) {
-        this.listeners.add(handler);
-        return () => this.listeners.delete(handler);
-    }
-    /** Publishes over `POST /push/:id`, with `token` as a bearer credential when present - see this module's doc
-     * comment on why this, unlike subscribing, needs no cookie workaround at all, and on the omitted-`token` case
-     * (an already-authenticated real caller), which relies on the browser's own real `jwt` cookie instead - and,
-     * because that's a *cookie*-authenticated request, also needs the matching CSRF header
-     * (`@rapidmx/web-client`'s `withCsrfHeader()`, the same double-submit echo `apiFetch()` applies to every other
-     * mutating call this server answers): without it, `RouteUtils.checkCsrf()` refuses the request with 403
-     * `"This request is missing a valid CSRF token."` before it ever reaches `BasePushRoute.send()`'s own ACL
-     * check - every `hello`/offer/answer/ICE candidate/`bye` a participant on that path sends 403s and is
-     * silently dropped (`send()` is fire-and-forget), which looks exactly like "stuck connecting, then no audio or
-     * video" from everyone else's side. `withCsrfHeader()` is harmless to also add on the bearer-token (guest)
-     * branch - the server only enforces the check for `req.auth.source === "cookie"` - so it's applied
-     * unconditionally here rather than only for the cookie case.
-     * Fire-and-forget: a failure is swallowed (there is nothing a signaling message's own sender can usefully do
-     * about a dropped publish beyond what the mesh's own `hello` re-announcement/renegotiation already tolerates -
-     * see `MeshConnectionManager`'s doc comment on fire-and-forget delivery). */
-    send(message) {
-        const fetchImpl = this.options.fetchImpl ?? (typeof fetch === "undefined" ? undefined : fetch);
-        if (!fetchImpl) {
-            return;
-        }
-        const origin = apiOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
-        const headers = { "Content-Type": "application/json" };
-        if (this.options.token) {
-            headers.Authorization = `Bearer ${this.options.token}`;
-        }
-        void fetchImpl(`${origin}/push/${encodeURIComponent(this.options.channel)}`, {
-            method: "POST",
-            headers: withCsrfHeader(headers, "POST"),
-            body: JSON.stringify(message),
-            // Only a `bye` needs to survive the page unloading - every other message is sent while the page (and
-            // the rest of this call's signaling) is very much alive. `keepalive` is a real-world liability to set
-            // unconditionally: some restrictive networks' inspecting proxies single out a `keepalive` fetch (it
-            // tells the browser the request may outlive the page - the same signal `navigator.sendBeacon()` and an
-            // `unload` handler's own fetch give off) for extra scrutiny or drop it outright, well short of Chrome's
-            // documented 64 KiB-per-request/several-MB-total keepalive quota. A participant behind such a network
-            // was seen stuck signaling forever - every `hello`/offer/answer/ICE candidate sent with `keepalive` and
-            // silently going nowhere (`send()` is fire-and-forget) - while an identical join from an unrestricted
-            // network connected normally.
-            keepalive: message.kind === "bye",
-        }).catch(() => {
-            // Best-effort - see this method's doc comment.
-        });
-    }
-    openSocket() {
-        const url = (this.options.url ?? pushUrl)();
-        const createSocket = this.options.createSocket ?? defaultSocketFactory();
-        if (!url || !createSocket) {
-            this.failConnect(new Error("This browser (or this page's connection) doesn't support the signaling channel."));
-            return;
-        }
-        this.applyAuthCookie();
-        let socket;
-        try {
-            socket = createSocket(url);
-        }
-        catch {
-            this.scheduleReconnect();
-            return;
-        }
-        this.socket = socket;
-        socket.onmessage = (event) => this.handleFrame(event.data);
-        socket.onclose = () => {
-            // Guards against a stale socket's belated close event: `close()` always sets `this.socket = undefined`
-            // synchronously (before this handler could possibly be detached asynchronously), so once this client
-            // is closed, `this.socket` can never equal `socket` again and this always returns here first.
-            if (this.socket !== socket) {
-                return;
-            }
-            this.socket = undefined;
-            this.scheduleReconnect();
-        };
-        socket.onerror = () => undefined;
-    }
-    scheduleReconnect() {
-        const ceiling = Math.min(SIGNALING_BACKOFF_MAX_MS, SIGNALING_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 10));
-        const delay = ceiling / 2 + ((this.options.random ?? Math.random)() * ceiling) / 2;
-        this.attempt += 1;
-        this.timer = setTimeout(() => {
-            this.timer = undefined;
-            this.openSocket();
-        }, delay);
-    }
-    handleFrame(raw) {
-        if (typeof raw !== "string") {
-            return;
-        }
-        let frame;
-        try {
-            const parsed = JSON.parse(raw);
-            if (!parsed || typeof parsed !== "object") {
-                return;
-            }
-            frame = parsed;
-        }
-        catch {
-            return;
-        }
-        if (frame.type === "SUBSCRIBED") {
-            this.handleSubscribed(frame);
-            return;
-        }
-        if (frame.type === "MESSAGE" && frame.channel === this.options.channel) {
-            const data = frame.data;
-            if (data && typeof data === "object" && data.type === "video-meeting-signal") {
-                this.emit(data);
-            }
-        }
-    }
-    handleSubscribed(frame) {
-        const channels = Array.isArray(frame.data) ? frame.data.filter((c) => typeof c === "string") : [];
-        if (frame.id === 0) {
-            // The connect-time greeting: now actually subscribe to the one channel this client cares about.
-            const id = this.nextRequestId++;
-            this.send0({ id, type: "SUBSCRIBE", data: [this.options.channel] });
-            return;
-        }
-        if (channels.includes(this.options.channel)) {
-            this.attempt = 0;
-            this.pendingConnect?.resolve();
-            this.pendingConnect = undefined;
-        }
-        else if (this.pendingConnect) {
-            this.failConnect(new Error("This meeting's signaling channel refused the subscription."));
-        }
-    }
-    send0(message) {
-        const socket = this.socket;
-        if (!socket || socket.readyState !== SOCKET_OPEN) {
-            return;
-        }
-        try {
-            socket.send(JSON.stringify(message));
-        }
-        catch {
-            // The close that follows a dead socket reconnects and re-subscribes.
-        }
-    }
-    failConnect(err) {
-        this.pendingConnect?.reject(err);
-        this.pendingConnect = undefined;
-    }
-    emit(message) {
-        for (const listener of [...this.listeners]) {
-            listener(message);
-        }
-    }
-    /** Sets the `jwt` cookie to `token` for this origin, so the browser attaches it (as `PushClient`'s own doc
-     * comment describes for a real session) to the WebSocket upgrade this client is about to open - see this
-     * module's doc comment for the full reasoning. A no-op when `token` is omitted (the caller already
-     * authenticated as a real RapidMX identity - see the FIXED LIMITATION section above): there is then no guest
-     * token to apply, and writing nothing leaves the browser's own real `jwt` session cookie, whatever it is,
-     * untouched and free to authenticate the connection normally. */
-    applyAuthCookie() {
-        if (!this.options.token) {
-            return;
-        }
-        const doc = this.options.documentRef ?? (typeof document === "undefined" ? undefined : document);
-        if (!doc) {
-            return;
-        }
-        this.cookieApplied = true;
-        const secure = (doc.location ?? (typeof location === "undefined" ? undefined : location))?.protocol === "https:" ? "; Secure" : "";
-        doc.cookie = `${AUTH_COOKIE_NAME}=${encodeURIComponent(this.options.token)}; path=/; SameSite=Lax${secure}`;
-    }
-    /** Expires the cookie `applyAuthCookie()` set - a no-op if that write was itself silently blocked, or never
-     * attempted at all because `token` was omitted (see `applyAuthCookie()`'s own doc comment), either way leaving
-     * whatever real session cookie was already there untouched. `cookieApplied` is only ever set once
-     * `applyAuthCookie()` has already confirmed both a `token` to write and a `doc` to write it to, and neither
-     * `this.options.token`, `this.options.documentRef` nor the real global `document` can change mid-call, so
-     * resolving it here is guaranteed to succeed too - no second `!doc` guard needed. */
-    clearAuthCookie() {
-        if (!this.cookieApplied) {
-            return;
-        }
-        const doc = this.options.documentRef ?? (typeof document === "undefined" ? undefined : document);
-        doc.cookie = `${AUTH_COOKIE_NAME}=; path=/; Max-Age=0`;
-    }
-}