herdr-remote 0.2.33 → 0.2.35

package/node_modules/herdr-remote-relay/dist/server/client-channel.js

@@ -0,0 +1,396 @@
+// The browser side of the relay: a window's WebSocket, from its hello and
+// pairing to every message and keystroke it sends after.
+import { CAPABILITY, FRAME_TYPE_INPUT, PASTE_MAX_BYTES, PROTOCOL_VERSION, hasImageSignature, isPasteImageMime, packStreamFrame, packStreamFrameV2, } from '../protocol/index.js';
+import { requestFontChunk, requestFontSubset } from './font-proxy.js';
+import { allowClientHandshake, allowPairAttempt, clientAddress } from './requests.js';
+import { MIN_SESSION_COLS, MIN_SESSION_ROWS, beginHostReconnect, broadcastControlState, detachClient, startSession, } from './sessions.js';
+import { clampDimension, closeSocket, isOpen, jsonSend, parseJson, randomId, rejectHandshake, } from './sockets.js';
+import { enqueueDelayedSend, notifyHostClientCount } from './transport.js';
+/** A window asks to start its workstation's Herdr at most this often. */
+const HERDR_START_REPEAT_MS = 3_000;
+/** A window asks its workstation to re-read the terminal font at most this often. */
+const FONT_REFRESH_REPEAT_MS = 2_000;
+/** A window opens an administrator tab at most this often. */
+const ADMIN_TAB_REPEAT_MS = 1_000;
+function verifyImageMagicBytes(mime, dataBase64) {
+    if (typeof dataBase64 !== 'string' || dataBase64.length === 0)
+        return false;
+    let headerBuf;
+    try {
+        headerBuf = Buffer.from(dataBase64.slice(0, 32), 'base64');
+    }
+    catch {
+        return false;
+    }
+    if (headerBuf.length === 0)
+        return false;
+    return hasImageSignature(mime, headerBuf);
+}
+export function handleClientConnection(relay, ws, req) {
+    const pending = { ws, req, authenticated: false };
+    const deadline = setTimeout(() => {
+        if (!pending.authenticated)
+            closeSocket(ws, 1008, 'client hello timeout');
+    }, 10000);
+    ws.isAlive = true;
+    ws.on('pong', () => {
+        ws.isAlive = true;
+        if (pending.client) {
+            pending.client.lastSeenAt = Date.now();
+            pending.client.lastPingAt = new Date().toISOString();
+        }
+    });
+    ws.on('ping', () => {
+        ws.isAlive = true;
+        if (pending.client) {
+            pending.client.lastSeenAt = Date.now();
+            pending.client.lastPingAt = new Date().toISOString();
+        }
+    });
+    ws.on('message', (raw, isBinary) => {
+        if (!pending.authenticated) {
+            if (isBinary)
+                return rejectHandshake(ws, 'client hello must be JSON');
+            const message = parseJson(raw.toString());
+            if (message?.type !== 'hello' || message.protocol !== PROTOCOL_VERSION)
+                return rejectHandshake(ws, 'invalid client hello');
+            if (!allowClientHandshake(relay, req))
+                return rejectHandshake(ws, 'too many connection attempts', 'rate_limited');
+            let device = null;
+            let paired = null;
+            if (message.pairCode) {
+                if (!allowPairAttempt(relay, req))
+                    return rejectHandshake(ws, 'too many pairing attempts', 'rate_limited');
+                paired = relay.auth.completePairing(message.pairCode);
+            }
+            if (paired)
+                device = paired;
+            else if (message.token)
+                device = relay.auth.authenticateDevice(message.token);
+            if (!device)
+                return rejectHandshake(ws, 'valid device token or pairing code required', 'auth_required');
+            const host = relay.hosts.get(device.hostId);
+            if (!host || host.reconnecting || !isOpen(host.ws))
+                return rejectHandshake(ws, 'paired Herdr host is offline', host?.reconnecting ? 'host_reconnecting' : 'host_offline');
+            // Two tabs of one browser are separate windows with their own PTY sessions,
+            // not rivals. Nothing is retired here: each connection gets its own stream
+            // without evicting existing clients.
+            if (host.clients.size >= relay.config.relay.maxClientsPerHost)
+                return rejectHandshake(ws, 'host client limit reached', 'too_many_clients');
+            clearTimeout(deadline);
+            relay.finishHandshake(ws);
+            const clientId = randomId('client');
+            const client = {
+                id: clientId,
+                ws,
+                hostId: host.id,
+                deviceId: device.deviceId,
+                // Stable per browser profile; used to recognise a reconnect from the
+                // same browser rather than a genuinely separate viewer.
+                browserClientId: typeof message.clientId === 'string' ? message.clientId.slice(0, 128) : null,
+                handoffCapable: Array.isArray(message.capabilities) &&
+                    message.capabilities.includes(CAPABILITY.hostHandoff),
+                session: null,
+                // Every paired window gets its own interactive PTY session. Pairing
+                // is the permission boundary; once a device is through it, every
+                // window can type into its own terminal.
+                role: 'controller',
+                controllerId: null,
+                connectedAt: new Date().toISOString(),
+                connectedAtMs: Date.now(),
+                lastSeenAt: Date.now(),
+                lastPingAt: null,
+                bytesReceived: 0,
+                bytesSent: 0,
+                ip: clientAddress(relay, req),
+                userAgent: String(req.headers['user-agent'] || '').slice(0, 256),
+                cols: clampDimension(message.cols, 80),
+                rows: clampDimension(message.rows, 24),
+            };
+            client.controllerId = null;
+            // Persist how this device identifies itself so the operator dashboard
+            // can name it in the revoke list instead of showing a bare device id.
+            relay.auth.noteDeviceSeen(device.deviceId, { userAgent: client.userAgent, ip: client.ip });
+            pending.authenticated = true;
+            pending.client = client;
+            relay.clients.set(client.id, client);
+            host.clients.add(client.id);
+            notifyHostClientCount(host);
+            ws.isAlive = true;
+            if (paired)
+                jsonSend(ws, {
+                    type: 'paired',
+                    token: paired.token,
+                    deviceId: paired.deviceId,
+                    hostId: paired.hostId,
+                    expiresAt: paired.expiresAtIso,
+                });
+            // Expose the relay-assigned connection id so clients can distinguish
+            // their own controller lease from another device's lease. The browser
+            // supplied clientId identifies a device, not this live WebSocket.
+            jsonSend(ws, {
+                type: 'ready',
+                role: client.role,
+                // There is no controller to name: every window has full input. The
+                // field stays in the message for clients built against protocol 1,
+                // which read it to decide whether somebody else held the lease — and
+                // `null` is exactly the answer that means "nobody does".
+                controllerId: null,
+                hostId: host.id,
+                hostname: host.hostname,
+                platform: host.platform,
+                ...(host.shellProfile ? { shellProfile: host.shellProfile } : {}),
+                adminTerminalSupported: host.adminTabsAvailable,
+                clientId: client.id,
+                // Delivered with `ready`, before the first PTY byte, so the terminal
+                // is painted in the host's colors from its very first frame.
+                terminalPalette: host.terminalPalette || null,
+                terminalFont: host.terminalFont || null,
+                clientCount: host.clients.size,
+                hostVersion: host.version,
+                ...(host.herdrPrefixKeys ? { herdrPrefixKeys: host.herdrPrefixKeys } : {}),
+            });
+            if (host.agentStatus)
+                jsonSend(ws, host.agentStatus);
+            if (host.updateStatus)
+                jsonSend(ws, host.updateStatus);
+            startSession(relay, host, client);
+            broadcastControlState(relay, host);
+            return;
+        }
+        if (pending.client)
+            handleClientMessage(relay, pending.client, raw, isBinary);
+    });
+    ws.on('close', () => {
+        clearTimeout(deadline);
+        if (pending.client)
+            detachClient(relay, pending.client, { notify: true });
+    });
+    ws.on('error', () => { });
+}
+function handleClientMessage(relay, client, raw, isBinary) {
+    client.lastSeenAt = Date.now();
+    const host = relay.hosts.get(client.hostId);
+    if (!host) {
+        detachClient(relay, client, { notify: true, reason: 'host_offline' });
+        return;
+    }
+    if (isBinary) {
+        // The server keeps ws's default binaryType, so a binary frame is one Buffer.
+        const bytes = raw;
+        if (bytes.length > relay.config.relay.maxPayloadBytes)
+            return;
+        if (!client.session)
+            return;
+        // Each window owns its own PTY session, so input is stamped with the
+        // client's dedicated stream id or streamIndex.
+        const frame = host.binaryFrameV2 && typeof client.session.streamIndex === 'number'
+            ? packStreamFrameV2(FRAME_TYPE_INPUT, client.session.streamIndex, bytes)
+            : packStreamFrame('input', client.session.streamId, bytes);
+        if (isOpen(host.ws)) {
+            const doSend = () => {
+                if (!isOpen(host.ws))
+                    return;
+                try {
+                    host.ws.send(frame);
+                    client.bytesReceived += bytes.length;
+                    relay.metrics.recordIn(bytes.length, host.id);
+                }
+                catch {
+                    beginHostReconnect(relay, host, 'host_send_failed');
+                }
+            };
+            if (relay.devLatencyMs > 0)
+                enqueueDelayedSend(relay, host.ws, doSend);
+            else
+                doSend();
+        }
+        return;
+    }
+    // Untrusted: each branch reads only the fields its message type defines.
+    const message = parseJson(raw.toString());
+    if (!message) {
+        jsonSend(client.ws, { type: 'error', code: 'invalid_json', message: 'message must be JSON' });
+        return;
+    }
+    if (message.type === 'ping') {
+        client.lastPingAt = new Date().toISOString();
+        jsonSend(client.ws, { type: 'pong' });
+    }
+    else if (message.type === 'resize') {
+        // Each client owns its own PTY session, so resizing directly forwards
+        // the new geometry for this client's stream to the host.
+        client.cols = clampDimension(message.cols, client.cols);
+        client.rows = clampDimension(message.rows, client.rows);
+        if (client.session) {
+            client.session.cols = client.cols;
+            client.session.rows = client.rows;
+            if (isOpen(host.ws)) {
+                jsonSend(host.ws, {
+                    type: 'resize',
+                    clientId: client.session.streamId,
+                    streamId: client.session.streamId,
+                    cols: Math.max(MIN_SESSION_COLS, client.cols),
+                    rows: Math.max(MIN_SESSION_ROWS, client.rows),
+                });
+            }
+        }
+    }
+    else if (message.type === 'herdr_start') {
+        // The window's own workstation, and nobody else's: `host` was fixed by
+        // the device token at handshake, and nothing in this message can name
+        // another one. The host starts Herdr as its own user, at its own socket.
+        // Repeats are dropped — one click is enough, and the host shares a
+        // start between windows anyway.
+        if (!client.session) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'no_session',
+                message: 'terminal session is not ready',
+            });
+            return;
+        }
+        const now = Date.now();
+        if (client.herdrStartAt && now - client.herdrStartAt < HERDR_START_REPEAT_MS)
+            return;
+        client.herdrStartAt = now;
+        if (isOpen(host.ws)) {
+            jsonSend(host.ws, {
+                type: 'herdr_start',
+                clientId: client.session.streamId,
+                streamId: client.session.streamId,
+            });
+        }
+    }
+    else if (message.type === 'admin_tab_open') {
+        // Routed like herdr_start. The host runs the fixed elevated PowerShell of
+        // its own broker; nothing in this message chooses what starts.
+        if (!client.session || !isOpen(host.ws))
+            return;
+        if (!host.adminTabsAvailable) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'admin_terminal_unsupported',
+                message: 'Update the host connector to open administrator terminals.',
+            });
+            return;
+        }
+        // A double tap is one request; a second tab needs a second, later tap.
+        const now = Date.now();
+        if (client.adminTabAt && now - client.adminTabAt < ADMIN_TAB_REPEAT_MS)
+            return;
+        client.adminTabAt = now;
+        jsonSend(host.ws, {
+            type: 'admin_tab_open',
+            clientId: client.session.streamId,
+            streamId: client.session.streamId,
+        });
+    }
+    else if (message.type === 'host_font_chunk_request') {
+        requestFontChunk(host, client, message);
+    }
+    else if (message.type === 'host_font_subset_request') {
+        requestFontSubset(host, client, message);
+    }
+    else if (message.type === 'host_font_refresh') {
+        // Same routing as herdr_start: only the workstation this window is
+        // bound to, and only what it offered. Repeats inside the window are
+        // dropped; the answer is broadcast to every window anyway.
+        if (!client.session || !isOpen(host.ws))
+            return;
+        const now = Date.now();
+        if (client.fontRefreshAt && now - client.fontRefreshAt < FONT_REFRESH_REPEAT_MS)
+            return;
+        client.fontRefreshAt = now;
+        jsonSend(host.ws, {
+            type: 'host_font_refresh',
+            clientId: client.session.streamId,
+            streamId: client.session.streamId,
+        });
+    }
+    else if (message.type === 'claim_control') {
+        // Control is no longer a lease. Answering the old request keeps clients
+        // built against the previous protocol working.
+        client.role = 'controller';
+        jsonSend(client.ws, { type: 'control_granted' });
+    }
+    else if (message.type === 'release_control') {
+        // Nothing to release: the window keeps its input either way, and saying
+        // so beats a silence an older client would wait on.
+        jsonSend(client.ws, { type: 'control_state', role: 'controller', controllerId: null });
+    }
+    else if (message.type === 'paste_file') {
+        if (client.role === 'viewer') {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'viewer_mode',
+                message: 'Viewer mode cannot paste to terminal',
+            });
+            return;
+        }
+        if (!isPasteImageMime(message.mime)) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'paste_file_unsupported',
+                message: 'Unsupported paste image format',
+            });
+            return;
+        }
+        if (typeof message.dataBase64 !== 'string') {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'paste_file_unsupported',
+                message: 'Invalid paste image payload',
+            });
+            return;
+        }
+        const rawLength = Buffer.byteLength(message.dataBase64, 'base64');
+        if (rawLength === 0) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'paste_file_empty',
+                message: 'Pasted image payload is empty',
+            });
+            return;
+        }
+        if (rawLength > PASTE_MAX_BYTES) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'paste_file_too_large',
+                message: 'Pasted image exceeds 3 MB limit',
+            });
+            return;
+        }
+        if (!verifyImageMagicBytes(message.mime, message.dataBase64)) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'paste_file_unsupported',
+                message: 'Pasted image content does not match declared MIME type',
+            });
+            return;
+        }
+        if (!isOpen(host?.ws)) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'host_offline',
+                message: 'Host is offline or disconnected',
+            });
+            return;
+        }
+        if (!client.session) {
+            jsonSend(client.ws, {
+                type: 'error',
+                code: 'no_session',
+                message: 'Terminal session is not ready',
+            });
+            return;
+        }
+        jsonSend(host.ws, {
+            type: 'paste_file',
+            clientId: client.session.streamId,
+            streamId: client.session.streamId,
+            mime: message.mime,
+            dataBase64: message.dataBase64,
+        });
+    }
+}

package/node_modules/herdr-remote-relay/dist/server/font-proxy.d.ts

@@ -0,0 +1,19 @@
+import { type ClientHostFontChunkRequestMessage, type ClientHostFontSubsetRequestMessage, type HostFontChunkMessage, type HostFontSubsetMessage } from '../protocol/index.js';
+import type { RelayClient, RelayHost } from './types.js';
+/** One outstanding font chunk request of this window was answered. */
+export declare function settleFontChunk(client: RelayClient): void;
+/** One outstanding font subset request of this window was answered. */
+export declare function settleFontSubset(client: RelayClient): void;
+/**
+ * Pass a browser's request for one slice of a font file to its workstation.
+ * Only a file the workstation announced can be asked for, by its hash, and
+ * only a few slices at a time.
+ */
+export declare function requestFontChunk(host: RelayHost, client: RelayClient, message: ClientHostFontChunkRequestMessage): void;
+/**
+ * Ask the workstation to cut characters out of a large font it announced.
+ * The text is only characters to look up; a few requests at a time.
+ */
+export declare function requestFontSubset(host: RelayHost, client: RelayClient, message: ClientHostFontSubsetRequestMessage): void;
+export declare function forwardFontSubset(client: RelayClient, message: HostFontSubsetMessage): void;
+export declare function forwardFontChunk(client: RelayClient, message: HostFontChunkMessage): void;

package/node_modules/herdr-remote-relay/dist/server/font-proxy.js

@@ -0,0 +1,155 @@
+// Terminal font files and cuts, passed between a window and its workstation a
+// slice at a time, and only for what the workstation announced.
+import { TERMINAL_FONT_CHUNK_BYTES, } from '../protocol/index.js';
+import { isOpen, jsonSend } from './sockets.js';
+/**
+ * Font chunks a window may have outstanding. Fonts are pulled a slice at a
+ * time so megabytes of font never queue ahead of terminal output; an answer
+ * that never comes stops counting after the timeout.
+ */
+const MAX_FONT_CHUNKS_IN_FLIGHT = 4;
+const FONT_CHUNK_TIMEOUT_MS = 30_000;
+/** Base64 of one full chunk, the most a `host_font_chunk` may carry. */
+const MAX_FONT_CHUNK_BASE64 = Math.ceil(TERMINAL_FONT_CHUNK_BYTES / 3) * 4;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/** Characters one subset request may ask for (UTF-16 units of `text`). */
+const MAX_FONT_SUBSET_TEXT = 32 * 1024;
+/** Cut fonts a window may pull by hash; older ones stop being fetchable. */
+const MAX_FONT_SUBSETS_PER_CLIENT = 64;
+const MAX_FONT_SUBSET_BYTES = 16 * 1024 * 1024;
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,32}$/;
+/** One outstanding font chunk request of this window was answered. */
+export function settleFontChunk(client) {
+    if (Array.isArray(client.fontChunkRequests) && client.fontChunkRequests.length)
+        client.fontChunkRequests.shift();
+}
+/** One outstanding font subset request of this window was answered. */
+export function settleFontSubset(client) {
+    if (Array.isArray(client.fontSubsetRequests) && client.fontSubsetRequests.length)
+        client.fontSubsetRequests.shift();
+}
+/**
+ * Pass a browser's request for one slice of a font file to its workstation.
+ * Only a file the workstation announced can be asked for, by its hash, and
+ * only a few slices at a time.
+ */
+export function requestFontChunk(host, client, message) {
+    if (!client.session || !isOpen(host.ws))
+        return;
+    const face = host.terminalFont?.faces?.find((candidate) => candidate.sha256 === message.sha256);
+    // A whole font file the workstation announced, or a cut it made for this window.
+    const bytes = face ? face.bytes : client.fontSubsets?.get(message.sha256) || 0;
+    const total = Math.ceil(bytes / TERMINAL_FONT_CHUNK_BYTES);
+    if (!bytes || !Number.isInteger(message.index) || message.index < 0 || message.index >= total) {
+        jsonSend(client.ws, {
+            type: 'error',
+            code: 'host_font_unavailable',
+            message: 'The workstation did not offer this font file',
+        });
+        return;
+    }
+    const now = Date.now();
+    client.fontChunkRequests = (client.fontChunkRequests || []).filter((at) => now - at < FONT_CHUNK_TIMEOUT_MS);
+    if (client.fontChunkRequests.length >= MAX_FONT_CHUNKS_IN_FLIGHT)
+        return;
+    client.fontChunkRequests.push(now);
+    jsonSend(host.ws, {
+        type: 'host_font_chunk_request',
+        clientId: client.session.streamId,
+        streamId: client.session.streamId,
+        sha256: message.sha256,
+        index: message.index,
+    });
+}
+/**
+ * Ask the workstation to cut characters out of a large font it announced.
+ * The text is only characters to look up; a few requests at a time.
+ */
+export function requestFontSubset(host, client, message) {
+    if (!client.session || !isOpen(host.ws))
+        return;
+    const known = host.terminalFont?.subsets?.some((source) => source.sha256 === message.sha256);
+    const valid = known &&
+        typeof message.text === 'string' &&
+        message.text.length > 0 &&
+        message.text.length <= MAX_FONT_SUBSET_TEXT &&
+        typeof message.requestId === 'string' &&
+        REQUEST_ID.test(message.requestId);
+    if (!valid) {
+        jsonSend(client.ws, {
+            type: 'error',
+            code: 'host_font_unavailable',
+            message: 'The workstation did not offer this font',
+        });
+        return;
+    }
+    const now = Date.now();
+    client.fontSubsetRequests = (client.fontSubsetRequests || []).filter((at) => now - at < FONT_CHUNK_TIMEOUT_MS);
+    if (client.fontSubsetRequests.length >= MAX_FONT_CHUNKS_IN_FLIGHT)
+        return;
+    client.fontSubsetRequests.push(now);
+    jsonSend(host.ws, {
+        type: 'host_font_subset_request',
+        clientId: client.session.streamId,
+        streamId: client.session.streamId,
+        requestId: message.requestId,
+        sha256: message.sha256,
+        text: message.text,
+    });
+}
+export function forwardFontSubset(client, message) {
+    settleFontSubset(client);
+    const valid = typeof message.sha256 === 'string' &&
+        SHA256_HEX.test(message.sha256) &&
+        typeof message.subsetSha === 'string' &&
+        SHA256_HEX.test(message.subsetSha) &&
+        typeof message.requestId === 'string' &&
+        REQUEST_ID.test(message.requestId) &&
+        Number.isInteger(message.bytes) &&
+        message.bytes > 0 &&
+        message.bytes <= MAX_FONT_SUBSET_BYTES &&
+        (message.dataBase64 === undefined ||
+            (typeof message.dataBase64 === 'string' &&
+                message.dataBase64.length <= MAX_FONT_CHUNK_BASE64));
+    if (!valid)
+        return;
+    if (message.dataBase64 === undefined) {
+        // Pulled in slices next: make this hash fetchable for this window only.
+        client.fontSubsets ||= new Map();
+        client.fontSubsets.delete(message.subsetSha);
+        client.fontSubsets.set(message.subsetSha, message.bytes);
+        while (client.fontSubsets.size > MAX_FONT_SUBSETS_PER_CLIENT) {
+            const oldest = client.fontSubsets.keys().next().value;
+            if (oldest !== undefined)
+                client.fontSubsets.delete(oldest);
+        }
+    }
+    jsonSend(client.ws, {
+        type: 'host_font_subset_ready',
+        requestId: message.requestId,
+        sha256: message.sha256,
+        subsetSha: message.subsetSha,
+        bytes: message.bytes,
+        ...(message.dataBase64 !== undefined ? { dataBase64: message.dataBase64 } : {}),
+    });
+}
+export function forwardFontChunk(client, message) {
+    settleFontChunk(client);
+    const valid = typeof message.sha256 === 'string' &&
+        SHA256_HEX.test(message.sha256) &&
+        Number.isInteger(message.index) &&
+        message.index >= 0 &&
+        Number.isInteger(message.total) &&
+        message.total > message.index &&
+        typeof message.dataBase64 === 'string' &&
+        message.dataBase64.length <= MAX_FONT_CHUNK_BASE64;
+    if (!valid)
+        return;
+    jsonSend(client.ws, {
+        type: 'host_font_chunk',
+        sha256: message.sha256,
+        index: message.index,
+        total: message.total,
+        dataBase64: message.dataBase64,
+    });
+}

package/node_modules/herdr-remote-relay/dist/server/host-broadcasts.d.ts

@@ -0,0 +1,27 @@
+import type { HostAgentStatusMessage, HostTerminalFontMessage, HostUpdateStatusMessage } from '../protocol/messages.js';
+import type { RelayContext, RelayHost } from './types.js';
+/** A message as the host sent it: the right keys, but values not yet checked. */
+type Unchecked<T> = {
+    [K in keyof T]?: unknown;
+};
+/** `value` if it is a release version, else null: it ends up as text in browsers. */
+export declare function releaseVersion(value: unknown): string | null;
+/**
+ * Pass on what the workstation's agents are doing.
+ *
+ * Sanitised rather than forwarded: the host is trusted, but this is the one
+ * message whose contents come from terminal titles, and it lands in a status
+ * bar on every attached window. The counts are numbers and the list is
+ * bounded, so a workstation cannot grow a browser's memory by naming things
+ * carefully.
+ */
+export declare function broadcastAgentStatus(relay: RelayContext, host: RelayHost, message: Unchecked<HostAgentStatusMessage>): void;
+/**
+ * Whether the workstation runs the newest herdr-remote, for every window on
+ * it. Only version strings and three flags pass: this ends up as text in the
+ * browser, and the host is not the relay's to trust.
+ */
+export declare function broadcastUpdateStatus(relay: RelayContext, host: RelayHost, message: Unchecked<HostUpdateStatusMessage>): void;
+/** The workstation re-read its terminal font; every window draws with it. */
+export declare function broadcastTerminalFont(relay: RelayContext, host: RelayHost, message: Unchecked<HostTerminalFontMessage>): void;
+export {};

package/node_modules/herdr-remote-relay/dist/server/host-broadcasts.js

@@ -0,0 +1,83 @@
+// Facts about a workstation that every window on it shows: its agents, its
+// update status and its terminal font. Each is checked on the way through and
+// kept on the host record, so a window that joins later gets the latest one.
+import { sanitizeTerminalFont } from '../protocol/terminal.js';
+import { text } from './sockets.js';
+import { broadcastToClients } from './transport.js';
+/** A release version as npm writes it; anything else is not forwarded. */
+const RELEASE_VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,32})?$/;
+/** `value` if it is a release version, else null: it ends up as text in browsers. */
+export function releaseVersion(value) {
+    return typeof value === 'string' && RELEASE_VERSION.test(value) ? value : null;
+}
+/** Matches the host's own cap; the relay re-applies it rather than trusting it. */
+const MAX_AGENT_STATUS_ENTRIES = 16;
+/**
+ * Pass on what the workstation's agents are doing.
+ *
+ * Sanitised rather than forwarded: the host is trusted, but this is the one
+ * message whose contents come from terminal titles, and it lands in a status
+ * bar on every attached window. The counts are numbers and the list is
+ * bounded, so a workstation cannot grow a browser's memory by naming things
+ * carefully.
+ */
+export function broadcastAgentStatus(relay, host, message) {
+    const counts = {};
+    if (message.counts && typeof message.counts === 'object') {
+        for (const [status, value] of Object.entries(message.counts)) {
+            if (typeof value === 'number' && Number.isFinite(value)) {
+                counts[status.slice(0, 32)] = Math.max(0, Math.min(9999, Math.trunc(value)));
+            }
+        }
+    }
+    const agents = (Array.isArray(message.agents) ? message.agents : [])
+        .slice(0, MAX_AGENT_STATUS_ENTRIES)
+        .map((agent) => ({
+        paneId: text(agent?.paneId, 64),
+        workspaceId: text(agent?.workspaceId, 64),
+        agent: text(agent?.agent, 32),
+        title: text(agent?.title, 64),
+        status: text(agent?.status, 16),
+        focused: agent?.focused === true,
+    }));
+    const payload = {
+        type: 'agent_status',
+        focusedPaneId: text(message.focusedPaneId, 64),
+        focusedAgent: text(message.focusedAgent, 32),
+        counts,
+        total: typeof message.total === 'number' && Number.isFinite(message.total)
+            ? Math.max(0, Math.trunc(message.total))
+            : agents.length,
+        agents,
+    };
+    host.agentStatus = payload;
+    broadcastToClients(relay, host, () => payload);
+}
+/**
+ * Whether the workstation runs the newest herdr-remote, for every window on
+ * it. Only version strings and three flags pass: this ends up as text in the
+ * browser, and the host is not the relay's to trust.
+ */
+export function broadcastUpdateStatus(relay, host, message) {
+    const current = releaseVersion(message.current);
+    const latest = releaseVersion(message.latest);
+    if (!current || !latest)
+        return;
+    const payload = {
+        type: 'update_status',
+        current,
+        installed: releaseVersion(message.installed) || current,
+        latest,
+        updateAvailable: message.updateAvailable === true,
+        restartPending: message.restartPending === true,
+        updateCommand: message.updateCommand === true,
+    };
+    host.updateStatus = payload;
+    broadcastToClients(relay, host, () => payload);
+}
+/** The workstation re-read its terminal font; every window draws with it. */
+export function broadcastTerminalFont(relay, host, message) {
+    host.terminalFont = sanitizeTerminalFont(message.terminalFont);
+    const payload = { type: 'terminal_font', terminalFont: host.terminalFont || null };
+    broadcastToClients(relay, host, () => payload);
+}