herdr-remote-relay 0.3.12 → 0.3.13

package/dist/server/requests.d.ts

@@ -0,0 +1,34 @@
+import type { IncomingMessage } from 'node:http';
+import type { RelayContext } from './types.js';
+/** Who an authenticated request speaks for. */
+export type RequestSubject = {
+    kind: 'host';
+    hostId: string;
+} | {
+    kind: 'device';
+    hostId: string;
+    deviceId: string;
+};
+export declare function isAllowedOrigin(relay: RelayContext, origin: string | undefined, req: IncomingMessage): boolean;
+export declare function requestOriginAllowed(relay: RelayContext, req: IncomingMessage): boolean;
+/**
+ * Identify the workstation making a request by its own host token.
+ * Ownership of a workstation is exactly what the host token proves, so a
+ * public relay serving many workstations stays safe: nobody can mint a pairing
+ * code for a host whose token they do not hold.
+ */
+export declare function authorizedHost(relay: RelayContext, req: IncomingMessage): string | null;
+/**
+ * Resolve the request to one tenant. Supplying both authentication schemes is
+ * allowed only when they identify the same host; otherwise a caller could
+ * accidentally combine credentials from two workstations and receive the
+ * result selected by whichever branch happened to run first.
+ */
+export declare function authorizedSubject(relay: RelayContext, req: IncomingMessage): RequestSubject | null;
+/** Authenticate the operator of this relay, not a workstation or device. */
+export declare function authorizedAdmin(relay: RelayContext, req: IncomingMessage): boolean;
+/** The address a window connected from, as the operator dashboard shows it. */
+export declare function clientAddress(relay: RelayContext, req: IncomingMessage): string | null;
+export declare function allowPairAttempt(relay: RelayContext, req: IncomingMessage): boolean;
+export declare function allowClientHandshake(relay: RelayContext, req: IncomingMessage): boolean;
+export declare function allowHostHandshake(relay: RelayContext, req: IncomingMessage): boolean;

package/dist/server/requests.js

@@ -0,0 +1,142 @@
+// Who is asking, and whether to let them: origins, credentials and rate limits
+// for HTTP requests and WebSocket handshakes.
+import crypto from 'node:crypto';
+function bearerToken(req) {
+    const value = req.headers.authorization;
+    if (typeof value !== 'string')
+        return null;
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return match ? match[1] : null;
+}
+function tokenMatches(candidate, expected) {
+    if (typeof candidate !== 'string' ||
+        candidate.length === 0 ||
+        typeof expected !== 'string' ||
+        expected.length === 0)
+        return false;
+    // Hashing first gives timingSafeEqual fixed-size buffers, without leaking a
+    // length mismatch through the comparison itself.
+    const candidateHash = crypto.createHash('sha256').update(candidate, 'utf8').digest();
+    const expectedHash = crypto.createHash('sha256').update(expected, 'utf8').digest();
+    return crypto.timingSafeEqual(candidateHash, expectedHash);
+}
+export function isAllowedOrigin(relay, origin, req) {
+    if (!origin)
+        return true;
+    const allowed = relay.config.relay.allowedOrigins || [];
+    if (allowed.includes(origin))
+        return true;
+    try {
+        return new URL(origin).host === req.headers.host;
+    }
+    catch {
+        return false;
+    }
+}
+export function requestOriginAllowed(relay, req) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    return isAllowedOrigin(relay, origin, req);
+}
+/**
+ * Identify the workstation making a request by its own host token.
+ * Ownership of a workstation is exactly what the host token proves, so a
+ * public relay serving many workstations stays safe: nobody can mint a pairing
+ * code for a host whose token they do not hold.
+ */
+export function authorizedHost(relay, req) {
+    const hostId = req.headers['x-herdr-host-id'];
+    const token = req.headers['x-herdr-host-token'];
+    if (typeof hostId !== 'string' || typeof token !== 'string')
+        return null;
+    return relay.auth.authenticateHost(hostId, token) ? hostId : null;
+}
+function authorizedDevice(relay, req) {
+    const token = bearerToken(req);
+    return token ? relay.auth.authenticateDevice(token) : null;
+}
+/**
+ * Resolve the request to one tenant. Supplying both authentication schemes is
+ * allowed only when they identify the same host; otherwise a caller could
+ * accidentally combine credentials from two workstations and receive the
+ * result selected by whichever branch happened to run first.
+ */
+export function authorizedSubject(relay, req) {
+    const hostIdHeader = req.headers['x-herdr-host-id'];
+    const hostTokenHeader = req.headers['x-herdr-host-token'];
+    const hasHostCredentials = hostIdHeader !== undefined || hostTokenHeader !== undefined;
+    const hasBearer = req.headers.authorization !== undefined;
+    const hostId = authorizedHost(relay, req);
+    const device = authorizedDevice(relay, req);
+    if (hasHostCredentials && !hostId)
+        return null;
+    if (hasBearer && !device)
+        return null;
+    if (hostId && device && hostId !== device.hostId)
+        return null;
+    if (hostId)
+        return { kind: 'host', hostId };
+    if (device)
+        return { kind: 'device', hostId: device.hostId, deviceId: device.deviceId };
+    return null;
+}
+/** Authenticate the operator of this relay, not a workstation or device. */
+export function authorizedAdmin(relay, req) {
+    return tokenMatches(req.headers['x-relay-admin-token'], relay.adminToken);
+}
+/**
+ * The left-most X-Forwarded-For entry, but only when `trustProxy` says a proxy
+ * sits in front of the relay: otherwise any caller could write the header.
+ */
+function forwardedFor(relay, req) {
+    if (!relay.trustProxy)
+        return null;
+    const forwarded = req.headers['x-forwarded-for'];
+    if (typeof forwarded !== 'string' || forwarded.length === 0)
+        return null;
+    return forwarded.split(',')[0].trim() || null;
+}
+/**
+ * Rate-limit key for a request. Behind a TLS reverse proxy every connection
+ * arrives from the proxy itself, so keying on the socket address would put
+ * every device in the world into one bucket and let a single attacker lock
+ * everyone out.
+ */
+function rateLimitKey(relay, req) {
+    return forwardedFor(relay, req) || req.socket.remoteAddress || 'unknown';
+}
+/** The address a window connected from, as the operator dashboard shows it. */
+export function clientAddress(relay, req) {
+    return forwardedFor(relay, req) || req.socket.remoteAddress || null;
+}
+function allowAttempt(relay, store, req, limit = 20) {
+    const key = rateLimitKey(relay, req);
+    const now = Date.now();
+    const current = store.get(key);
+    if (!current || now - current.startedAt >= 60_000) {
+        // Bound the map even when an attacker rotates source addresses. Expired
+        // entries are removed by sweep; the oldest live entry is the least
+        // useful one to retain when the cap is reached.
+        if (store.size >= 4096) {
+            const oldest = store.keys().next().value;
+            if (oldest !== undefined)
+                store.delete(oldest);
+        }
+        store.set(key, { startedAt: now, count: 1 });
+        return true;
+    }
+    if (current.count >= limit)
+        return false;
+    current.count += 1;
+    return true;
+}
+export function allowPairAttempt(relay, req) {
+    return allowAttempt(relay, relay.pairAttempts, req, 20);
+}
+export function allowClientHandshake(relay, req) {
+    return allowAttempt(relay, relay.clientHandshakeAttempts, req, 60);
+}
+export function allowHostHandshake(relay, req) {
+    return allowAttempt(relay, relay.hostHandshakeAttempts, req, 60);
+}

package/dist/server/sessions.d.ts

@@ -0,0 +1,36 @@
+import type { RelayClient, RelayContext, RelayHost } from './types.js';
+/** Never shrink an individual session grid below something a program can still draw in. */
+export declare const MIN_SESSION_COLS = 20;
+export declare const MIN_SESSION_ROWS = 6;
+export interface DetachOptions {
+    /** Tell the window why, before closing it. */
+    notify?: boolean;
+    reason?: string;
+    closeCode?: number;
+    /** Drop the socket at once instead of closing it politely. */
+    terminate?: boolean;
+}
+export declare function allocateStreamIndex(host: RelayHost | null | undefined): number | null;
+/** Forget `client`'s stream: its id, its v2 index on `host`, and the session itself. */
+export declare function releaseSession(relay: RelayContext, host: RelayHost | null | undefined, client: RelayClient): void;
+/** Start a dedicated PTY session for one attached client. */
+export declare function startSession(relay: RelayContext, host: RelayHost, client: RelayClient | null | undefined, { restarted }?: {
+    restarted?: boolean | undefined;
+}): void;
+/**
+ * Tell every window who is attached.
+ *
+ * There is no controller to announce any more, so this carries the one fact
+ * that changed: how many windows now share this terminal.
+ */
+export declare function broadcastControlState(relay: RelayContext, host: RelayHost): void;
+/**
+ * Close every window a revoked device still holds, on any host, so revoking
+ * takes effect now rather than at its next reconnect. Returns how many.
+ */
+export declare function detachDeviceSessions(relay: RelayContext, deviceId: string): number;
+export declare function detachClient(relay: RelayContext, client: RelayClient | null | undefined, { notify, reason, closeCode, terminate, }?: DetachOptions): void;
+export declare function detachHost(relay: RelayContext, host: RelayHost | null | undefined, { notify, reason, terminate }?: DetachOptions): void;
+/** Whether `host`'s windows can keep their sessions across a host reconnect. */
+export declare function canHandoffHost(relay: RelayContext, host: RelayHost | null | undefined): boolean;
+export declare function beginHostReconnect(relay: RelayContext, host: RelayHost | null | undefined, reason?: string): void;

package/dist/server/sessions.js

@@ -0,0 +1,225 @@
+// A window's PTY session on its host, and taking windows and hosts off the
+// relay: detaching, host hand-off and the reconnect grace period.
+import { WebSocket } from 'ws';
+import { closeSocket, isOpen, jsonSend, randomId, terminateSocket } from './sockets.js';
+import { broadcastToClients, notifyHostClientCount } from './transport.js';
+/** Never shrink an individual session grid below something a program can still draw in. */
+export const MIN_SESSION_COLS = 20;
+export const MIN_SESSION_ROWS = 6;
+export function allocateStreamIndex(host) {
+    if (!host)
+        return null;
+    const totalPossible = 65536;
+    for (let i = 0; i < totalPossible; i++) {
+        const candidate = host.nextStreamIndex;
+        host.nextStreamIndex = (host.nextStreamIndex + 1) & 0xffff;
+        if (!host.streamIndices.has(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** Forget `client`'s stream: its id, its v2 index on `host`, and the session itself. */
+export function releaseSession(relay, host, client) {
+    const session = client.session;
+    if (!session)
+        return;
+    if (session.streamIndex !== null && session.streamIndex !== undefined && host) {
+        host.streamIndices.delete(session.streamIndex);
+    }
+    relay.streams.delete(session.streamId);
+    client.session = null;
+}
+/** Start a dedicated PTY session for one attached client. */
+export function startSession(relay, host, client, { restarted = false } = {}) {
+    if (!client || !isOpen(host.ws))
+        return;
+    const streamId = randomId('session');
+    let streamIndex = null;
+    if (host.binaryFrameV2) {
+        streamIndex = allocateStreamIndex(host);
+        if (streamIndex !== null) {
+            host.streamIndices.set(streamIndex, client.id);
+        }
+    }
+    client.session = {
+        streamId,
+        streamIndex,
+        cols: client.cols,
+        rows: client.rows,
+        ready: false,
+    };
+    relay.streams.set(streamId, client.id);
+    jsonSend(host.ws, {
+        type: 'session_start',
+        clientId: streamId,
+        streamId,
+        cols: Math.max(MIN_SESSION_COLS, client.cols),
+        rows: Math.max(MIN_SESSION_ROWS, client.rows),
+        role: 'controller',
+        ...(streamIndex !== null ? { streamIndex } : {}),
+    });
+    if (restarted) {
+        jsonSend(client.ws, {
+            type: 'session_restarted',
+            streamId,
+            cols: client.cols,
+            rows: client.rows,
+            hostname: host.hostname,
+            terminalPalette: host.terminalPalette || null,
+            terminalFont: host.terminalFont || null,
+        });
+    }
+}
+/**
+ * Tell every window who is attached.
+ *
+ * There is no controller to announce any more, so this carries the one fact
+ * that changed: how many windows now share this terminal.
+ */
+export function broadcastControlState(relay, host) {
+    for (const clientId of host.clients) {
+        const client = relay.clients.get(clientId);
+        if (!client)
+            continue;
+        client.role = 'controller';
+        client.controllerId = null;
+        jsonSend(client.ws, {
+            type: 'control_state',
+            role: 'controller',
+            controllerId: null,
+            clientCount: host.clients.size,
+        });
+    }
+}
+/**
+ * Close every window a revoked device still holds, on any host, so revoking
+ * takes effect now rather than at its next reconnect. Returns how many.
+ */
+export function detachDeviceSessions(relay, deviceId) {
+    if (!deviceId)
+        return 0;
+    let closed = 0;
+    for (const existing of [...relay.clients.values()]) {
+        if (!existing || existing.deviceId !== deviceId)
+            continue;
+        detachClient(relay, existing, { notify: false, reason: 'device_revoked' });
+        closeSocket(existing.ws, 1000, 'this device has been revoked by the relay operator');
+        closed += 1;
+    }
+    return closed;
+}
+export function detachClient(relay, client, { notify = true, reason = 'client_disconnected', closeCode = 1000, terminate = false, } = {}) {
+    if (!client || !relay.clients.has(client.id))
+        return;
+    relay.clients.delete(client.id);
+    const host = relay.hosts.get(client.hostId);
+    // Each window has its own PTY session. Tearing down the client immediately
+    // stops its backing session on the host and cleans up its stream mapping.
+    if (client.session) {
+        const streamId = client.session.streamId;
+        releaseSession(relay, host, client);
+        if (host && isOpen(host.ws)) {
+            jsonSend(host.ws, { type: 'session_stop', clientId: streamId, streamId });
+        }
+    }
+    if (host) {
+        host.clients.delete(client.id);
+        notifyHostClientCount(host);
+        broadcastControlState(relay, host);
+        if (host.clients.size === 0) {
+            host.controllerId = null;
+            if (host.reconnecting)
+                detachHost(relay, host, { notify: false, reason: 'no_clients' });
+        }
+    }
+    const clientSocket = client.ws;
+    client.ws = null;
+    if (notify)
+        jsonSend(clientSocket, {
+            type: 'error',
+            code: reason,
+            message: reason === 'host_offline' ? 'Herdr host is offline' : 'connection closed',
+        });
+    if (terminate || clientSocket?.readyState === WebSocket.CLOSING) {
+        terminateSocket(clientSocket);
+    }
+    else {
+        closeSocket(clientSocket, closeCode, reason);
+    }
+    relay.metrics.recordCleanup('closedPtysCleaned');
+}
+export function detachHost(relay, host, { notify = true, reason = 'host_disconnected', terminate = false } = {}) {
+    if (!host || relay.hosts.get(host.id) !== host)
+        return;
+    if (host.reconnectTimer)
+        clearTimeout(host.reconnectTimer);
+    host.reconnectTimer = null;
+    relay.hosts.delete(host.id);
+    for (const clientId of [...host.clients]) {
+        const client = relay.clients.get(clientId);
+        if (!client)
+            continue;
+        relay.clients.delete(client.id);
+        releaseSession(relay, host, client);
+        const clientSocket = client.ws;
+        client.ws = null;
+        if (notify)
+            jsonSend(clientSocket, { type: 'error', code: reason, message: 'Herdr host disconnected' });
+        if (terminate || clientSocket?.readyState === WebSocket.CLOSING) {
+            terminateSocket(clientSocket);
+        }
+        else {
+            closeSocket(clientSocket, 1012, reason);
+        }
+    }
+    host.clients.clear();
+    relay.metrics.forgetHost(host.id);
+    const hostSocket = host.ws;
+    host.ws = null;
+    if (terminate || hostSocket?.readyState === WebSocket.CLOSING) {
+        terminateSocket(hostSocket);
+    }
+    else {
+        closeSocket(hostSocket, 1000, reason);
+    }
+}
+/** Whether `host`'s windows can keep their sessions across a host reconnect. */
+export function canHandoffHost(relay, host) {
+    if (!host?.handoffCapable || host.clients.size === 0)
+        return false;
+    for (const clientId of host.clients) {
+        const client = relay.clients.get(clientId);
+        if (!client?.handoffCapable)
+            return false;
+    }
+    return true;
+}
+export function beginHostReconnect(relay, host, reason = 'host_disconnected') {
+    if (!host || relay.hosts.get(host.id) !== host || host.reconnecting)
+        return;
+    if (!canHandoffHost(relay, host)) {
+        detachHost(relay, host, { notify: true, reason });
+        return;
+    }
+    host.ws = null;
+    host.reconnecting = true;
+    host.reconnectStartedAt = Date.now();
+    host.lastSeenAt = Date.now();
+    host.load = {};
+    host.ptys = [];
+    for (const clientId of host.clients) {
+        const client = relay.clients.get(clientId);
+        if (client)
+            releaseSession(relay, host, client);
+    }
+    broadcastToClients(relay, host, () => ({ type: 'host_reconnecting', code: reason }));
+    const timer = setTimeout(() => {
+        host.reconnectTimer = null;
+        if (relay.hosts.get(host.id) === host && host.reconnecting) {
+            detachHost(relay, host, { notify: true, reason: 'host_reconnect_timeout' });
+        }
+    }, relay.config.relay.hostReconnectGraceMs);
+    host.reconnectTimer = timer;
+    timer.unref?.();
+}

package/dist/server/sockets.d.ts

@@ -0,0 +1,12 @@
+import type { RelaySocket } from './types.js';
+export declare function randomId(prefix: string): string;
+/** A bounded string, or null. For fields whose contents a pane decided. */
+export declare function text(value: unknown, limit: number): string | null;
+export declare function clampDimension(value: unknown, fallback: number): number;
+export declare function isOpen(socket: RelaySocket | null | undefined): socket is RelaySocket;
+export declare function jsonSend(socket: RelaySocket | null | undefined, payload: unknown): void;
+export declare function closeSocket(socket: RelaySocket | null | undefined, code?: number, reason?: string): void;
+export declare function terminateSocket(socket: RelaySocket | null | undefined): void;
+/** Parsed JSON, or null for anything that is not a string of valid JSON. */
+export declare function parseJson<T = Record<string, unknown>>(data: unknown): T | null;
+export declare function rejectHandshake(ws: RelaySocket, message: string, code?: string): void;

package/dist/server/sockets.js

@@ -0,0 +1,64 @@
+// Small helpers for the relay's WebSockets and the untrusted data read from them.
+import crypto from 'node:crypto';
+import { WebSocket } from 'ws';
+const MAX_DIMENSION = 500;
+export function randomId(prefix) {
+    return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
+}
+/** A bounded string, or null. For fields whose contents a pane decided. */
+export function text(value, limit) {
+    return typeof value === 'string' && value.length > 0 ? value.slice(0, limit) : null;
+}
+export function clampDimension(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric))
+        return fallback;
+    return Math.min(MAX_DIMENSION, Math.max(2, numeric));
+}
+export function isOpen(socket) {
+    return Boolean(socket) && socket?.readyState === WebSocket.OPEN;
+}
+export function jsonSend(socket, payload) {
+    if (isOpen(socket))
+        socket.send(JSON.stringify(payload));
+}
+export function closeSocket(socket, code = 1000, reason = '') {
+    if (!socket || socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING)
+        return;
+    try {
+        socket.close(code, reason.slice(0, 120));
+    }
+    catch {
+        // Closing a socket that is already failing needs no further handling.
+    }
+}
+export function terminateSocket(socket) {
+    if (!socket || socket.readyState === WebSocket.CLOSED)
+        return;
+    try {
+        if (typeof socket.terminate === 'function') {
+            socket.terminate();
+        }
+        else if (typeof socket.destroy === 'function') {
+            socket.destroy();
+        }
+    }
+    catch {
+        // Tearing down a dead socket; there is nothing left to recover.
+    }
+}
+/** Parsed JSON, or null for anything that is not a string of valid JSON. */
+export function parseJson(data) {
+    if (typeof data !== 'string')
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export function rejectHandshake(ws, message, code = 'invalid_handshake') {
+    jsonSend(ws, { type: 'error', code, message });
+    closeSocket(ws, 1008, message);
+}

package/dist/server/status.d.ts

@@ -0,0 +1,11 @@
+import type { AdminStatusResponse } from '../protocol/http.js';
+import type { RelayContext } from './types.js';
+export interface StatusOptions {
+    /** Advance the throughput sample; off for reads that must not skew the rates. */
+    sample?: boolean;
+    /** Include the paired-device roster, which only the relay operator may see. */
+    includeDevices?: boolean;
+    /** Report only this workstation and its windows. */
+    scopeHostId?: string | null;
+}
+export declare function statusSnapshot(relay: RelayContext, { sample, includeDevices, scopeHostId }?: StatusOptions): AdminStatusResponse;

package/dist/server/status.js

@@ -0,0 +1,95 @@
+// What `/api/status` and `/api/admin/status` report: the relay's metrics plus
+// the hosts, windows and PTYs it can see, scoped to one tenant when asked.
+import { countActiveUsers } from '../metrics.js';
+export function statusSnapshot(relay, { sample = true, includeDevices = false, scopeHostId = null } = {}) {
+    const scopedClients = scopeHostId
+        ? [...relay.clients.values()].filter((client) => client.hostId === scopeHostId)
+        : [...relay.clients.values()];
+    const scopedHosts = scopeHostId
+        ? [...relay.hosts.values()].filter((host) => host.id === scopeHostId)
+        : [...relay.hosts.values()];
+    const clients = scopedClients.map((client) => ({
+        id: client.id,
+        role: client.role,
+        ...(scopeHostId ? {} : { hostId: client.hostId }),
+        ...(includeDevices ? { deviceId: client.deviceId } : {}),
+        userAgent: client.userAgent,
+        connectedAt: client.connectedAt,
+        lastPingAt: client.lastPingAt,
+        bytesReceived: client.bytesReceived,
+        bytesSent: client.bytesSent,
+        ip: client.ip,
+    }));
+    // The roster is read once and used twice: the operator response carries it
+    // whole, and every response carries the per-host tally derived from it. A
+    // public caller learns how many devices a workstation has paired, never
+    // which ones.
+    const pairedDevices = relay.auth.listDevices();
+    const pairedPerHost = new Map();
+    for (const device of pairedDevices) {
+        pairedPerHost.set(device.hostId, (pairedPerHost.get(device.hostId) || 0) + 1);
+    }
+    const hosts = scopedHosts.map((host) => ({
+        id: host.id,
+        hostname: host.hostname,
+        platform: host.platform,
+        arch: host.arch,
+        status: host.reconnecting ? 'reconnecting' : host.clients.size ? 'busy' : 'online',
+        connectedAt: host.connectedAt,
+        activePtyCount: host.ptys.length,
+        // Distinct devices attached to this workstation, not open sockets: a
+        // phone with two tabs open is one device on the operator's board.
+        connectedDeviceCount: countActiveUsers([...host.clients]
+            .map((id) => relay.clients.get(id))
+            .filter((client) => Boolean(client))),
+        pairedDeviceCount: pairedPerHost.get(host.id) || 0,
+        load: host.load,
+    }));
+    // The workstation counts one PTY per stream and cannot know how many
+    // windows are watching it; the relay does, and that is the number an
+    // operator needs when the session is shared. Scoped callers only receive
+    // the PTYs belonging to their authenticated host.
+    const ptys = scopedHosts.flatMap((host) => host.ptys.map((pty) => ({
+        ...pty,
+        ...(scopeHostId ? {} : { hostId: host.id }),
+        activeClients: host.clients.size,
+    })));
+    // The paired-device roster identifies people's hardware, so it is served to
+    // the relay operator only — never on /api/status, which any paired device
+    // may read.
+    const devices = includeDevices ? pairedDevices : undefined;
+    const address = relay.address();
+    return {
+        ...relay.metrics.snapshot({
+            clients,
+            hosts,
+            ptys,
+            sample,
+            scopeHostId,
+            // Counted from the unredacted records: the mapped rows above only carry
+            // `deviceId` for the operator, and a public caller must still see the
+            // same number of users the operator does.
+            activeUserCount: countActiveUsers(scopedClients),
+        }),
+        ...(devices ? { devices } : {}),
+        relayMode: relay.relayMode,
+        isRemoteRelay: relay.relayMode === 'remote',
+        remoteAdminUrl: relay.relayMode === 'remote'
+            ? `${String(relay.config.relay.publicUrl || '').replace(/\/+$/, '')}/admin`
+            : undefined,
+        relay: {
+            mode: relay.relayMode,
+            publicUrl: relay.config.relay.publicUrl,
+            bind: relay.config.relay.host,
+            port: (address && 'port' in address ? address.port : undefined) || relay.config.relay.port,
+            maxClientsPerHost: relay.config.relay.maxClientsPerHost,
+            maxHosts: relay.config.relay.maxHosts,
+            maxPendingHandshakes: relay.config.relay.maxPendingHandshakes,
+            maxBufferedBytesPerClient: relay.config.relay.maxBufferedBytesPerClient,
+            hostReconnectGraceMs: relay.config.relay.hostReconnectGraceMs,
+            adminConfigured: Boolean(relay.adminToken),
+            adminStatusPath: '/api/admin/status',
+            dashboardPath: '/admin',
+        },
+    };
+}

package/dist/server/transport.d.ts

@@ -0,0 +1,16 @@
+import type { RelayClient, RelayContext, RelayHost, RelaySocket } from './types.js';
+/** Notify the host whether any browser currently needs business telemetry. */
+export declare function notifyHostClientCount(host: RelayHost | null | undefined): void;
+/**
+ * Forward output without allowing one slow browser to grow an unbounded ws
+ * queue. Closing only that browser preserves low latency for the other views.
+ */
+export declare function sendClientBinary(relay: RelayContext, host: RelayHost, client: RelayClient | null | undefined, payload: Buffer): boolean;
+/**
+ * Queue artificial delay per-socket rather than using naked setTimeout calls.
+ * Concurrent timers experience event loop jitter that can deliver frames out of order;
+ * a single FIFO queue per socket guarantees strict in-order delivery of terminal frames.
+ */
+export declare function enqueueDelayedSend(relay: RelayContext, socket: RelaySocket, task: () => void): void;
+/** Send one JSON message to every browser attached to `host`. */
+export declare function broadcastToClients(relay: RelayContext, host: RelayHost, build: (client: RelayClient) => unknown): void;