herdr-remote-relay 0.3.11 → 0.3.13

package/dist/server/host-broadcasts.d.ts

@@ -0,0 +1,25 @@
+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;
+};
+/**
+ * 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 two 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/dist/server/host-broadcasts.js

@@ -0,0 +1,79 @@
+// 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})?$/;
+/** 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 two 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 version = (value) => typeof value === 'string' && RELEASE_VERSION.test(value) ? value : null;
+    const current = version(message.current);
+    const latest = version(message.latest);
+    if (!current || !latest)
+        return;
+    const payload = {
+        type: 'update_status',
+        current,
+        installed: version(message.installed) || current,
+        latest,
+        updateAvailable: message.updateAvailable === true,
+        restartPending: message.restartPending === 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);
+}

package/dist/server/host-channel.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from 'node:http';
+import type { RelayContext, RelaySocket } from './types.js';
+export declare function handleHostConnection(relay: RelayContext, ws: RelaySocket, req: IncomingMessage): void;

package/dist/server/host-channel.js

@@ -0,0 +1,266 @@
+// The host side of the relay: a workstation's WebSocket, from its hello and
+// the hand-off from an older connection to every message it sends after.
+import os from 'node:os';
+import { CAPABILITY, PROTOCOL_VERSION, sanitizeTerminalFont, sanitizeTerminalPalette, unpackStreamFrame, } from '../protocol/index.js';
+import { forwardFontChunk, forwardFontSubset, settleFontChunk, settleFontSubset, } from './font-proxy.js';
+import { broadcastAgentStatus, broadcastTerminalFont, broadcastUpdateStatus, } from './host-broadcasts.js';
+import { allowHostHandshake } from './requests.js';
+import { beginHostReconnect, canHandoffHost, detachClient, detachHost, releaseSession, startSession, } from './sessions.js';
+import { closeSocket, isOpen, jsonSend, parseJson, randomId, rejectHandshake } from './sockets.js';
+import { broadcastToClients, notifyHostClientCount, sendClientBinary } from './transport.js';
+function createHostRecord(message, ws, pending, clients = new Set()) {
+    const capabilities = Array.isArray(message.capabilities) ? message.capabilities : [];
+    return {
+        id: message.hostId,
+        ws,
+        hostname: typeof message.hostname === 'string' ? message.hostname.slice(0, 128) : os.hostname(),
+        platform: typeof message.platform === 'string' ? message.platform.slice(0, 32) : process.platform,
+        arch: typeof message.arch === 'string' ? message.arch.slice(0, 32) : process.arch,
+        connectedAt: new Date(pending.connectedAt).toISOString(),
+        connectedAtMs: pending.connectedAt,
+        terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
+        /** Family, size and fetchable files of the workstation's terminal font. */
+        terminalFont: sanitizeTerminalFont(message.terminalFont),
+        /** The latest workstation snapshot is replayed when a browser joins late. */
+        agentStatus: null,
+        /** Whether the workstation's herdr-remote is behind; replayed the same way. */
+        updateStatus: null,
+        lastSeenAt: Date.now(),
+        clients,
+        controllerId: null,
+        load: {},
+        ptys: [],
+        reconnecting: false,
+        reconnectTimer: null,
+        connectionGeneration: randomId('host-connection'),
+        handoffCapable: capabilities.includes(CAPABILITY.hostHandoff),
+        binaryFrameV2: capabilities.includes(CAPABILITY.binaryFrameV2),
+        streamIndices: new Map(),
+        nextStreamIndex: 0,
+        shutdownRequested: false,
+    };
+}
+export function handleHostConnection(relay, ws, req) {
+    const pending = {
+        ws,
+        remoteAddress: req.socket.remoteAddress,
+        connectedAt: Date.now(),
+        authenticated: false,
+    };
+    const deadline = setTimeout(() => {
+        if (!pending.authenticated)
+            closeSocket(ws, 1008, 'host hello timeout');
+    }, 10000);
+    ws.isAlive = true;
+    ws.on('pong', () => {
+        ws.isAlive = true;
+        if (pending.host)
+            pending.host.lastSeenAt = Date.now();
+    });
+    ws.on('ping', () => {
+        ws.isAlive = true;
+        if (pending.host)
+            pending.host.lastSeenAt = Date.now();
+    });
+    ws.on('message', (raw, isBinary) => {
+        if (!pending.authenticated) {
+            if (isBinary)
+                return rejectHandshake(ws, 'host hello must be JSON');
+            const message = parseJson(raw.toString());
+            if (message?.type !== 'host_hello' || message.protocol !== PROTOCOL_VERSION)
+                return rejectHandshake(ws, 'invalid host hello');
+            if (!allowHostHandshake(relay, req))
+                return rejectHandshake(ws, 'too many connection attempts', 'rate_limited');
+            const oldHost = relay.hosts.get(message.hostId);
+            if (!oldHost && relay.hosts.size >= relay.config.relay.maxHosts) {
+                return rejectHandshake(ws, 'relay host limit reached', 'too_many_hosts');
+            }
+            const registration = relay.auth.registerHost(message.hostId, message.token, message.password ?? null);
+            if (!registration.ok)
+                return rejectHandshake(ws, registration.message, registration.code);
+            clearTimeout(deadline);
+            pending.authenticated = true;
+            relay.finishHandshake(ws);
+            const handoff = canHandoffHost(relay, oldHost);
+            const retainedClients = handoff && oldHost ? oldHost.clients : new Set();
+            if (oldHost) {
+                if (oldHost.reconnectTimer)
+                    clearTimeout(oldHost.reconnectTimer);
+                oldHost.reconnectTimer = null;
+                if (handoff) {
+                    for (const clientId of oldHost.clients) {
+                        const client = relay.clients.get(clientId);
+                        if (client?.session) {
+                            if (isOpen(oldHost.ws)) {
+                                jsonSend(oldHost.ws, {
+                                    type: 'session_stop',
+                                    clientId: client.session.streamId,
+                                    streamId: client.session.streamId,
+                                });
+                            }
+                            releaseSession(relay, oldHost, client);
+                        }
+                    }
+                    oldHost.load = {};
+                    oldHost.ptys = [];
+                    broadcastToClients(relay, oldHost, () => ({
+                        type: 'host_reconnecting',
+                        code: 'host_replaced',
+                    }));
+                }
+                else {
+                    detachHost(relay, oldHost, { notify: true, reason: 'host_replaced' });
+                }
+            }
+            const host = createHostRecord(message, ws, pending, retainedClients);
+            pending.host = host;
+            // Install the new record before closing the old socket. Its delayed
+            // close handler then fails the identity check instead of detaching the
+            // freshly authenticated host.
+            relay.hosts.set(host.id, host);
+            if (oldHost && handoff)
+                closeSocket(oldHost.ws, 1000, 'host_replaced');
+            jsonSend(ws, {
+                type: 'host_ready',
+                protocol: PROTOCOL_VERSION,
+                hostId: host.id,
+                clientCount: host.clients.size,
+            });
+            notifyHostClientCount(host);
+            if (handoff) {
+                for (const clientId of host.clients) {
+                    const client = relay.clients.get(clientId);
+                    if (client)
+                        startSession(relay, host, client, { restarted: true });
+                }
+            }
+            return;
+        }
+        if (pending.host)
+            handleHostMessage(relay, pending.host, raw, isBinary);
+    });
+    ws.on('close', (_code, rawReason) => {
+        clearTimeout(deadline);
+        const host = pending.host;
+        if (!host || relay.hosts.get(host.id) !== host || host.ws !== ws)
+            return;
+        const reason = rawReason ? rawReason.toString() : '';
+        if (reason === 'host_shutdown')
+            host.shutdownRequested = true;
+        if (host.shutdownRequested || !canHandoffHost(relay, host)) {
+            detachHost(relay, host, {
+                notify: true,
+                reason: host.shutdownRequested ? 'host_shutdown' : 'host_disconnected',
+            });
+            return;
+        }
+        beginHostReconnect(relay, host, 'host_disconnected');
+    });
+    ws.on('error', () => { });
+}
+function handleHostMessage(relay, host, raw, isBinary) {
+    host.lastSeenAt = Date.now();
+    if (isBinary) {
+        let frame;
+        try {
+            frame = unpackStreamFrame(raw);
+        }
+        catch (error) {
+            relay.metrics.recordCleanup('deadConnectionsClosed');
+            closeSocket(host.ws, 1003, error.message);
+            return;
+        }
+        // Postel's law: be conservative in what you send, liberal in what you accept.
+        // We strictly send v2 only to hosts that negotiated binary_frame_v2, but we accept
+        // both v1 and v2 on receipt: a v2-capable host falls back to v1 if stream indices
+        // were exhausted for a session, and an unnegotiated host sending v2 simply finds
+        // no routed client instead of having its entire connection severed.
+        // Output is routed to the single client owning the stream rather than broadcast.
+        if (frame.type !== 'output')
+            return;
+        const clientId = frame.version === 2
+            ? host.streamIndices.get(frame.streamIndex)
+            : relay.streams.get(frame.streamId);
+        if (!clientId)
+            return;
+        const client = relay.clients.get(clientId);
+        if (!client || !isOpen(client.ws))
+            return;
+        sendClientBinary(relay, host, client, frame.payload);
+        return;
+    }
+    // Untrusted: each branch reads only the fields its message type defines.
+    const message = parseJson(raw.toString());
+    if (!message)
+        return;
+    if (message.type === 'heartbeat') {
+        host.load = message.load && typeof message.load === 'object' ? message.load : {};
+        host.ptys = Array.isArray(message.ptys) ? message.ptys.slice(0, 256) : [];
+        return;
+    }
+    if (message.type === 'host_shutdown') {
+        host.shutdownRequested = true;
+        if (relay.hosts.get(host.id) === host)
+            detachHost(relay, host, { notify: true, reason: 'host_shutdown' });
+        return;
+    }
+    // What the workstation's agents are doing belongs to the workstation, not
+    // to one stream: every window watching it gets the same answer.
+    if (message.type === 'agent_status') {
+        broadcastAgentStatus(relay, host, message);
+        return;
+    }
+    if (message.type === 'update_status') {
+        broadcastUpdateStatus(relay, host, message);
+        return;
+    }
+    if (message.type === 'terminal_font') {
+        broadcastTerminalFont(relay, host, message);
+        return;
+    }
+    // Session events target the single client that owns this stream.
+    const addressed = message;
+    const streamId = typeof addressed.clientId === 'string'
+        ? addressed.clientId
+        : addressed.streamId;
+    const clientId = streamId ? relay.streams.get(streamId) : null;
+    const client = clientId ? relay.clients.get(clientId) : null;
+    if (!client)
+        return;
+    if (message.type === 'session_ready') {
+        if (client.session)
+            client.session.ready = true;
+        jsonSend(client.ws, { type: 'session_ready', clientId: client.id });
+    }
+    else if (message.type === 'session_exit') {
+        const code = Number.isInteger(message.code) ? message.code : null;
+        jsonSend(client.ws, { type: 'exit', code });
+        releaseSession(relay, host, client);
+        detachClient(relay, client, { notify: false });
+    }
+    else if (message.type === 'host_font_chunk') {
+        forwardFontChunk(client, message);
+    }
+    else if (message.type === 'host_font_subset_ready') {
+        forwardFontSubset(client, message);
+    }
+    else if (message.type === 'paste_file_ready') {
+        jsonSend(client.ws, {
+            type: 'paste_file_ready',
+            path: message.path,
+        });
+    }
+    else if (message.type === 'error') {
+        if (message.code === 'host_font_unavailable') {
+            settleFontChunk(client);
+            settleFontSubset(client);
+        }
+        if (message.code === 'host_font_subset_failed')
+            settleFontSubset(client);
+        jsonSend(client.ws, {
+            type: 'error',
+            code: message.code || 'host_error',
+            message: String(message.message || 'Host connector error'),
+        });
+    }
+}

package/dist/server/http-api.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RelayContext } from './types.js';
+export declare function handleHttp(relay: RelayContext, req: IncomingMessage, res: ServerResponse): void;

package/dist/server/http-api.js

@@ -0,0 +1,214 @@
+// The relay's HTTP side: the JSON API under /api, /healthz, and the built web
+// app for everything else.
+import fs from 'node:fs';
+import path from 'node:path';
+import { URL } from 'node:url';
+import { PROTOCOL_VERSION } from '../protocol/index.js';
+import { PACKAGE_ROOT } from '../relay-config.js';
+import { allowPairAttempt, authorizedAdmin, authorizedHost, authorizedSubject, requestOriginAllowed, } from './requests.js';
+import { detachDeviceSessions } from './sessions.js';
+import { isOpen } from './sockets.js';
+import { statusSnapshot } from './status.js';
+import { VERSION } from './version.js';
+const PUBLIC_DIR = path.join(PACKAGE_ROOT, 'web', 'dist');
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+};
+function setResponseHeaders(res, contentType = 'application/json') {
+    res.setHeader('Content-Type', contentType);
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('Content-Security-Policy', "default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; connect-src 'self' ws: wss:; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'");
+}
+function sendJsonResponse(res, status, payload) {
+    setResponseHeaders(res);
+    res.writeHead(status);
+    res.end(JSON.stringify(payload));
+}
+function sendError(res, status, code, message) {
+    sendJsonResponse(res, status, { ok: false, code, message });
+}
+/** Whether the caller is the relay operator; answers the request when not. */
+function adminAllowed(relay, req, res) {
+    if (!relay.adminToken) {
+        sendError(res, 503, 'admin_not_configured', 'configure RELAY_ADMIN_TOKEN to access the relay dashboard');
+        return false;
+    }
+    if (!authorizedAdmin(relay, req)) {
+        sendError(res, 401, 'admin_auth_required', 'a valid relay admin token is required');
+        return false;
+    }
+    return true;
+}
+const healthz = (relay, _req, res) => {
+    // Liveness is intentionally tenant-blind. Host/client counts let an
+    // unauthenticated caller learn whether other workstations are present.
+    sendJsonResponse(res, 200, {
+        ok: true,
+        version: VERSION,
+        protocol: PROTOCOL_VERSION,
+        uptimeSeconds: Math.floor((Date.now() - relay.startedAt) / 1000),
+    });
+};
+const info = (relay, _req, res) => {
+    const publicUrl = String(relay.config.relay.publicUrl || '').replace(/\/+$/, '');
+    sendJsonResponse(res, 200, {
+        ok: true,
+        version: VERSION,
+        protocol: PROTOCOL_VERSION,
+        relayMode: relay.relayMode,
+        isRemoteRelay: relay.relayMode === 'remote',
+        adminConfigured: Boolean(relay.adminToken),
+        adminPath: '/admin',
+        adminStatusPath: '/api/admin/status',
+        publicUrl,
+        remoteAdminUrl: relay.relayMode === 'remote' ? `${publicUrl}/admin` : null,
+    });
+};
+const status = (relay, req, res) => {
+    const subject = authorizedSubject(relay, req);
+    if (!subject) {
+        sendError(res, 401, 'auth_required', 'an authorized device or host token is required');
+        return;
+    }
+    sendJsonResponse(res, 200, statusSnapshot(relay, { scopeHostId: subject.hostId }));
+};
+const adminStatus = (relay, req, res) => {
+    if (!adminAllowed(relay, req, res))
+        return;
+    sendJsonResponse(res, 200, statusSnapshot(relay, { includeDevices: true }));
+};
+const revokeDevice = (relay, req, res, url) => {
+    if (!adminAllowed(relay, req, res))
+        return;
+    const deviceId = decodeURIComponent(url.pathname.slice('/api/admin/devices/'.length));
+    const revoked = relay.auth.revokeDevice(deviceId);
+    if (!revoked) {
+        sendError(res, 404, 'device_not_found', 'no such paired device');
+        return;
+    }
+    // Revocation has to take effect now, not at the next reconnect: drop any
+    // socket the device still holds so the terminal closes immediately.
+    const disconnected = detachDeviceSessions(relay, deviceId);
+    sendJsonResponse(res, 200, { ok: true, deviceId: revoked.deviceId, disconnected });
+};
+const startPairing = (relay, req, res) => {
+    if (!allowPairAttempt(relay, req)) {
+        sendError(res, 429, 'rate_limited', 'too many pairing attempts');
+        return;
+    }
+    const hostId = authorizedHost(relay, req);
+    if (!hostId) {
+        sendError(res, 401, 'host_auth_required', 'a valid host id and token are required');
+        return;
+    }
+    const host = relay.hosts.get(hostId);
+    if (!host || host.reconnecting || !isOpen(host.ws)) {
+        sendError(res, 409, 'host_offline', 'no Herdr host is connected');
+        return;
+    }
+    try {
+        const pairing = relay.auth.startPairing(hostId, String(relay.config.relay.publicUrl).replace(/\/$/, ''));
+        const answer = {
+            ok: true,
+            ...pairing,
+            pairUrl: `${pairing.publicUrl}/?pairCode=${encodeURIComponent(pairing.code)}`,
+        };
+        sendJsonResponse(res, 200, answer);
+    }
+    catch (error) {
+        const { code, message } = error;
+        sendError(res, 409, code || 'pairing_failed', message);
+    }
+};
+const ROUTES = [
+    { method: 'GET', path: '/healthz', handle: healthz },
+    { method: 'GET', path: '/api/info', handle: info },
+    { method: 'GET', path: '/api/status', handle: status },
+    { method: 'GET', path: '/api/admin/status', handle: adminStatus },
+    { method: 'DELETE', path: '/api/admin/devices/', prefix: true, handle: revokeDevice },
+    { method: 'POST', path: '/api/pair/start', handle: startPairing },
+];
+export function handleHttp(relay, req, res) {
+    let requestUrl;
+    try {
+        requestUrl = new URL(req.url || '', `http://${req.headers.host || 'localhost'}`);
+    }
+    catch {
+        sendError(res, 400, 'bad_request', 'invalid URL');
+        return;
+    }
+    if (!requestOriginAllowed(relay, req)) {
+        sendError(res, 403, 'origin_denied', 'origin is not allowed');
+        return;
+    }
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, {
+            'Access-Control-Allow-Origin': req.headers.origin || '*',
+            'Access-Control-Allow-Headers': 'Authorization, Content-Type, X-Herdr-Host-Id, X-Herdr-Host-Token, X-Relay-Admin-Token',
+            'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+            Vary: 'Origin',
+        });
+        res.end();
+        return;
+    }
+    // Only echo an origin after the exact allowlist/same-host check above. This
+    // makes explicitly configured cross-origin WebUI profiles usable without
+    // reflecting an attacker-controlled Origin header.
+    if (req.headers.origin) {
+        res.setHeader('Access-Control-Allow-Origin', req.headers.origin);
+        res.setHeader('Vary', 'Origin');
+    }
+    const { pathname } = requestUrl;
+    const route = ROUTES.find((candidate) => candidate.method === req.method &&
+        (candidate.prefix ? pathname.startsWith(candidate.path) : pathname === candidate.path));
+    if (route) {
+        route.handle(relay, req, res, requestUrl);
+        return;
+    }
+    if (pathname.startsWith('/api/')) {
+        sendError(res, 404, 'not_found', 'API route not found');
+        return;
+    }
+    serveStatic(pathname, res);
+}
+function serveStatic(requestPath, res) {
+    const relative = requestPath === '/' || requestPath === '/admin'
+        ? 'index.html'
+        : requestPath.replace(/^\/+/, '');
+    const candidate = path.resolve(PUBLIC_DIR, relative);
+    if (!candidate.startsWith(`${PUBLIC_DIR}${path.sep}`) &&
+        candidate !== path.join(PUBLIC_DIR, 'index.html')) {
+        sendError(res, 403, 'forbidden', 'path is not allowed');
+        return;
+    }
+    fs.readFile(candidate, (error, data) => {
+        if (error && !path.extname(relative)) {
+            fs.readFile(path.join(PUBLIC_DIR, 'index.html'), (fallbackError, fallbackData) => {
+                if (fallbackError) {
+                    sendError(res, 503, 'web_not_built', 'frontend has not been built');
+                    return;
+                }
+                setResponseHeaders(res, 'text/html; charset=utf-8');
+                res.end(fallbackData);
+            });
+            return;
+        }
+        if (error) {
+            sendError(res, 404, 'not_found', 'file not found');
+            return;
+        }
+        const extension = path.extname(candidate).toLowerCase();
+        setResponseHeaders(res, MIME_TYPES[extension] || 'application/octet-stream');
+        res.end(data);
+    });
+}

package/dist/server/maintenance.d.ts

@@ -0,0 +1,5 @@
+import type { RelayContext } from './types.js';
+/** Close sockets that missed the last ping, and ping the rest. */
+export declare function heartbeat(relay: RelayContext): void;
+/** Drop rate-limit windows, windows and hosts that have gone stale, and expired pairings. */
+export declare function sweep(relay: RelayContext): void;

package/dist/server/maintenance.js

@@ -0,0 +1,64 @@
+// Timed housekeeping: ping every socket, and drop what went quiet.
+import { WebSocket } from 'ws';
+import { detachClient, detachHost } from './sessions.js';
+import { terminateSocket } from './sockets.js';
+/** Close sockets that missed the last ping, and ping the rest. */
+export function heartbeat(relay) {
+    const sockets = [
+        ...[...relay.hosts.values()].map((host) => host.ws),
+        ...[...relay.clients.values()].map((client) => client.ws),
+    ].filter((socket) => Boolean(socket && socket.readyState !== WebSocket.CLOSED));
+    for (const socket of sockets) {
+        if (socket.readyState === WebSocket.CLOSING) {
+            relay.metrics.recordCleanup('deadConnectionsClosed');
+            terminateSocket(socket);
+            continue;
+        }
+        if (socket.readyState !== WebSocket.OPEN)
+            continue;
+        if (!socket.isAlive) {
+            relay.metrics.recordCleanup('deadConnectionsClosed');
+            terminateSocket(socket);
+            continue;
+        }
+        socket.isAlive = false;
+        try {
+            socket.ping();
+        }
+        catch {
+            // A socket failing mid-ping is terminated by the next sweep.
+        }
+    }
+}
+function forgetExpiredAttempts(store, now) {
+    for (const [key, attempt] of store.entries()) {
+        if (now - attempt.startedAt >= 60_000)
+            store.delete(key);
+    }
+}
+/** Drop rate-limit windows, windows and hosts that have gone stale, and expired pairings. */
+export function sweep(relay) {
+    const now = Date.now();
+    const staleAfter = relay.config.cleanup.staleAfterMs;
+    forgetExpiredAttempts(relay.pairAttempts, now);
+    forgetExpiredAttempts(relay.clientHandshakeAttempts, now);
+    forgetExpiredAttempts(relay.hostHandshakeAttempts, now);
+    for (const client of [...relay.clients.values()]) {
+        if (now - client.lastSeenAt > staleAfter) {
+            relay.metrics.recordCleanup('staleClientsPurged');
+            detachClient(relay, client, { notify: false, reason: 'stale_client', terminate: true });
+        }
+    }
+    for (const host of [...relay.hosts.values()]) {
+        if (host.reconnecting)
+            continue;
+        if (now - host.lastSeenAt > staleAfter) {
+            relay.metrics.recordCleanup('deadConnectionsClosed');
+            detachHost(relay, host, { notify: true, reason: 'stale_host', terminate: true });
+        }
+    }
+    const authCleanup = relay.auth.cleanup(now);
+    if (authCleanup.removedDevices || authCleanup.removedPairings)
+        relay.metrics.recordCleanup('staleClientsPurged', authCleanup.removedDevices);
+    relay.metrics.cleanup.lastCleanupAt = new Date(now).toISOString();
+}