@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/relay.js

@@ -0,0 +1,642 @@
+// control-plane/relay.ts — the CP→home HTTP+WS relay engine (P4.3 / part-plan
+// T3.2). Implements the `RelayDispatcher` seam `server.ts` defines: every
+// call here already passed `respondDynamicLane`'s/`handleUpgrade`'s
+// session+registry gate (P4.1) — `home` is the registry row resolved FRESH
+// from the caller's own session this request, never from anything client-
+// supplied (R-CP-2). This module's only job is wake (P4.2's `ensureAwake`)
+// plus the actual byte/frame relay to `home.preview_endpoint`, generalizing
+// M0 `wake-proxy/proxy.ts` from a single-tenant/single-home proxy onto the
+// CP's per-request resolved `Home` row.
+//
+// Re-binding (R-CP-6 / criterion 5): the upstream origin is always
+// `home.preview_endpoint` (resolved by `ensureAwake`, never the request URL)
+// and the WS node target is always `home.home_agent_target` — both read off
+// the `home` row this function was called with. A client cannot widen or
+// redirect the route by supplying `?target=` or a different `/node/<id>`
+// path segment: this design's home model is a single resident root per home
+// (design.md F1 — `home_agent_target` is the only legitimate relay target),
+// and home selection itself is entirely session-derived upstream of this
+// module (server.ts resolves `home` from the session on every call, never
+// from the client). Re-deriving the target from the client path here would
+// only reintroduce the cross-home surface this design avoids; a session for
+// home A can therefore never reach home B's broker through this relay no
+// matter what `?target=`/path id it sends — home B's `preview_endpoint` is
+// never even looked up for that session.
+//
+// Two credentials, two legs (S4): the relay token is resolved by
+// `ensureAwake` (via `secrets.ts`, from `relay_auth_ref`) and injected as the
+// CP→home `Authorization: Bearer` header; the browser/worker leg's own
+// Authorization/Cookie/Proxy-* headers are stripped before the request ever
+// reaches the upstream fetch/WS call (R-CP-3). The browser/worker leg never
+// sees or reflects the relay token.
+import { Readable } from 'node:stream';
+import { WebSocket, WebSocketServer } from 'ws';
+import { BROKER_READ_CAPS } from '../../core/runtime/broker-protocol.js';
+import { general } from '../../core/errors.js';
+import { loadControlPlaneConfig } from './config.js';
+import { ensureAwake, invalidateWarmVerdict, resolveRunning } from './wake.js';
+import { redactSecrets } from './secrets.js';
+import { tenantSessionAuthRedactedMessage } from './session.js';
+const hopByHopHeaders = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+function redact(message) {
+    return redactSecrets(tenantSessionAuthRedactedMessage(message));
+}
+function redactDeep(value) {
+    if (typeof value === 'string')
+        return redact(value);
+    if (Array.isArray(value))
+        return value.map((entry) => redactDeep(entry));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactDeep(entry)]));
+    }
+    return value;
+}
+/** Log a relay-side failure server-side only — never sent to the browser
+ *  (callers always respond with a generic status + short body). Every field
+ *  is redacted so a resolved relay token, a session cookie/bearer value, or
+ *  an `Authorization:`/`?token=` fragment captured in an upstream error
+ *  message can never reach stderr unredacted (criterion 7). */
+function logError(message, details = {}) {
+    process.stderr.write(`${JSON.stringify({ level: 'error', message, details: redactDeep(details) })}\n`);
+}
+function requestPath(req) {
+    return req.url ?? '/';
+}
+function decodePathForValidation(raw) {
+    for (let i = 0; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (ch === '%') {
+            const a = raw[i + 1];
+            const b = raw[i + 2];
+            if (a === undefined || b === undefined || !/[0-9A-Fa-f]/.test(a) || !/[0-9A-Fa-f]/.test(b)) {
+                throw general('relay rejected malformed percent-encoding in request target', { requestUrl: '[redacted]' });
+            }
+            const decoded = Number.parseInt(`${a}${b}`, 16);
+            if (decoded <= 0x1f || decoded === 0x7f || decoded === 0x5c) {
+                throw general('relay rejected control or backslash characters in request target', { requestUrl: '[redacted]' });
+            }
+            i += 2;
+            continue;
+        }
+        if (ch === '\\' || ch === '\u0000' || ch < ' ' || ch === '\u007f') {
+            throw general('relay rejected control characters in request target', { requestUrl: '[redacted]' });
+        }
+    }
+}
+/** Origin-form-only request target validation (criterion 4): rejects
+ *  scheme-relative (`//evil`) and any target that doesn't start with `/`,
+ *  and rejects control/backslash characters (raw or percent-encoded) before
+ *  the target is ever joined onto the upstream origin. */
+function validateOriginFormRequestTarget(rawRequestUrl) {
+    const raw = rawRequestUrl === undefined || rawRequestUrl === '' ? '/' : rawRequestUrl;
+    if (!raw.startsWith('/')) {
+        throw general('relay only accepts origin-form request targets', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    if (raw.startsWith('//')) {
+        throw general('relay rejected scheme-relative request target', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    decodePathForValidation(raw);
+    return raw;
+}
+/** Join the validated origin-form request target onto `previewEndpoint` and
+ *  reject anything that would escape that origin (criterion 4: "reject
+ *  scheme-relative/absolute external escapes"). */
+export function buildUpstreamHttpUrl(previewEndpoint, rawRequestUrl) {
+    const route = new URL(previewEndpoint);
+    const raw = validateOriginFormRequestTarget(rawRequestUrl);
+    const upstream = new URL(raw, route);
+    if (upstream.origin !== route.origin) {
+        throw general('relay rejected request target that escapes the upstream origin', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    upstream.searchParams.delete('token');
+    return upstream;
+}
+/** Strip every browser-leg auth header (Authorization/Cookie/Proxy-*) and
+ *  every client-supplied forwarding/host-metadata header (Forwarded,
+ *  X-Forwarded-*, X-Real-IP) before forwarding upstream — the relay is a
+ *  single hop behind the CP, so the home should see no forwarding metadata
+ *  at all rather than an attacker-controlled one — then inject the CP→home
+ *  relay token as the sole Authorization header (criterion 2). */
+function filteredRequestHeaders(req, relayToken) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        const lower = name.toLowerCase();
+        if (lower === 'host' ||
+            lower === 'authorization' ||
+            lower === 'cookie' ||
+            lower === 'referer' ||
+            lower === 'referrer' ||
+            lower === 'forwarded' ||
+            lower === 'x-real-ip' ||
+            lower.startsWith('proxy-') ||
+            lower.startsWith('sec-websocket-') ||
+            lower.startsWith('x-forwarded-') ||
+            hopByHopHeaders.has(lower)) {
+            continue;
+        }
+        headers.set(lower, Array.isArray(value) ? value.join(',') : value);
+    }
+    headers.set('authorization', `Bearer ${relayToken}`);
+    headers.set('accept-encoding', 'identity');
+    return headers;
+}
+/** Rewrite an upstream redirect to stay same-origin on the CP (criterion 3).
+ *  A relative Location is forwarded verbatim (already same-origin to
+ *  whatever origin the browser/worker considers itself on). An absolute
+ *  Location back to the upstream route origin is rewritten to a CP-relative
+ *  path so the browser never learns/visits the upstream origin directly; any
+ *  other absolute origin is dropped. */
+function sanitizeLocation(location, upstreamOrigin) {
+    if (location.startsWith('/') && !location.startsWith('//') && !location.includes('\\'))
+        return location;
+    try {
+        const abs = new URL(location, upstreamOrigin);
+        if (abs.origin === upstreamOrigin)
+            return `${abs.pathname}${abs.search}${abs.hash}`;
+    }
+    catch {
+        /* malformed Location — drop it */
+    }
+    return null;
+}
+function applyResponseHeaders(res, headers, upstreamOrigin) {
+    headers.forEach((value, key) => {
+        const lower = key.toLowerCase();
+        if (lower === 'set-cookie' || lower === 'authorization' || hopByHopHeaders.has(lower) || lower.startsWith('proxy-'))
+            return;
+        if (lower === 'location') {
+            const sanitized = sanitizeLocation(value, upstreamOrigin);
+            if (sanitized !== null)
+                res.setHeader('location', sanitized);
+            return;
+        }
+        res.setHeader(lower, value);
+    });
+    const contentType = headers.get('content-type');
+    if (contentType !== null && !res.hasHeader('content-type'))
+        res.setHeader('content-type', contentType);
+}
+function tuneStreamingHeaders(res, isEventStream) {
+    if (!isEventStream)
+        return;
+    const cacheControl = res.getHeader('cache-control');
+    if (typeof cacheControl === 'string') {
+        if (!/no-transform/i.test(cacheControl))
+            res.setHeader('cache-control', `${cacheControl}, no-transform`);
+    }
+    else if (cacheControl === undefined) {
+        res.setHeader('cache-control', 'no-cache, no-transform');
+    }
+    res.setHeader('connection', 'keep-alive');
+    res.setHeader('x-accel-buffering', 'no');
+    res.socket?.setNoDelay(true);
+}
+async function waitForDrain(res, signal) {
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            res.off('drain', onDrain);
+            res.off('close', onClose);
+            res.off('error', onError);
+            signal.removeEventListener('abort', onAbort);
+        };
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error('response closed while streaming'));
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new Error('response aborted while streaming'));
+        };
+        res.once('drain', onDrain);
+        res.once('close', onClose);
+        res.once('error', onError);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+async function streamResponseBody(body, res, signal) {
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            if (!res.write(Buffer.from(value))) {
+                await waitForDrain(res, signal);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function withTimeout(work, timeoutMs, label) {
+    if (timeoutMs <= 0)
+        return work;
+    let timer = null;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(general(`${label} timed out`, { timeoutMs })), timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== null)
+            clearTimeout(timer);
+    }
+}
+function closeHttpWithError(res, statusCode, message) {
+    if (!res.headersSent) {
+        res.writeHead(statusCode, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+    }
+    res.end(`${message}\n`);
+}
+function addRequestAbort(req, res, controller) {
+    const abort = () => controller.abort();
+    req.once('aborted', abort);
+    res.once('close', abort);
+    return () => {
+        req.off('aborted', abort);
+        res.off('close', abort);
+    };
+}
+/**
+ * Forward one HTTP request to the already-awakened home and stream the
+ * response back. Returns normally once the response is fully relayed;
+ * throws on a genuine upstream/network failure (connect refused/reset, DNS,
+ * body-stream error) — an app-level 4xx/5xx is a RESOLVED fetch and is
+ * relayed verbatim, never thrown here.
+ */
+async function forwardUpstream(req, res, awakened, controller) {
+    const upstreamUrl = buildUpstreamHttpUrl(awakened.preview_endpoint, requestPath(req));
+    const method = req.method ?? 'GET';
+    const canHaveBody = method !== 'GET' && method !== 'HEAD';
+    const requestInit = {
+        method,
+        headers: filteredRequestHeaders(req, awakened.relayToken),
+        body: canHaveBody ? Readable.toWeb(req) : undefined,
+        signal: controller.signal,
+        redirect: 'manual',
+    };
+    if (canHaveBody)
+        requestInit.duplex = 'half';
+    const response = await fetch(upstreamUrl, requestInit);
+    const responseHeaders = new Headers(response.headers);
+    const isEventStream = /text\/event-stream/i.test(responseHeaders.get('content-type') ?? '');
+    if (isEventStream)
+        responseHeaders.delete('content-length');
+    res.statusCode = response.status;
+    res.statusMessage = response.statusText;
+    applyResponseHeaders(res, responseHeaders, new URL(awakened.preview_endpoint).origin);
+    tuneStreamingHeaders(res, isEventStream);
+    if (response.body === null || method === 'HEAD') {
+        res.end();
+        return;
+    }
+    res.flushHeaders?.();
+    await streamResponseBody(response.body, res, controller.signal);
+    if (!res.writableEnded)
+        res.end();
+}
+/** Forward one HTTP request to `home` (criterion 1: only after the caller's
+ *  session/registry gate already resolved `home`, and only after
+ *  `ensureAwake(home.home_id)` succeeds). Mirrors M0 `proxy.ts`'s
+ *  fast-path-then-escalate shape: a fresh warm-verdict cache hit
+ *  (`resolveRunning`, P4.2) is forwarded directly without re-entering the
+ *  wake pipeline; only a missing/stale verdict, or a running route that just
+ *  failed on a safely-replayable method, escalates to a bounded
+ *  `ensureAwake`. */
+export async function proxyHttp(req, res, home, deps = {}) {
+    const ensureAwakeImpl = deps.ensureAwake ?? ensureAwake;
+    const resolveRunningImpl = deps.resolveRunning ?? resolveRunning;
+    const invalidate = deps.invalidateWarmVerdict ?? invalidateWarmVerdict;
+    const config = (deps.loadConfig ?? loadControlPlaneConfig)();
+    const controller = new AbortController();
+    const cleanup = addRequestAbort(req, res, controller);
+    try {
+        const running = resolveRunningImpl(home.home_id);
+        if (running !== null) {
+            try {
+                await forwardUpstream(req, res, running, controller);
+                return;
+            }
+            catch (error) {
+                const method = req.method ?? 'GET';
+                const replayable = method === 'GET' || method === 'HEAD';
+                if (res.headersSent || controller.signal.aborted || !replayable)
+                    throw error;
+                logError('hearth control plane relay running-route forward failed; escalating to deliberate wake', {
+                    home_id: home.home_id,
+                    path: requestPath(req).replace(/\?.*$/, ''),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                invalidate(home.home_id);
+            }
+        }
+        const awakened = await withTimeout(ensureAwakeImpl(home.home_id), config.wakeTimeoutMs, 'control plane relay wake');
+        if (controller.signal.aborted)
+            throw general('request closed while waking');
+        await forwardUpstream(req, res, awakened, controller);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError('hearth control plane relay HTTP request failed', {
+            home_id: home.home_id,
+            path: requestPath(req).replace(/\?.*$/, ''),
+            error: message,
+        });
+        if (!message.startsWith('relay '))
+            invalidate(home.home_id);
+        if (/timed out/i.test(message)) {
+            closeHttpWithError(res, 504, 'wake timeout');
+            return;
+        }
+        if (!res.headersSent) {
+            closeHttpWithError(res, message.startsWith('relay ') ? 400 : 502, message.startsWith('relay ') ? 'bad request' : 'bad gateway');
+            return;
+        }
+        try {
+            res.destroy();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    finally {
+        cleanup();
+    }
+}
+// --- WebSocket relay --------------------------------------------------
+/** Build the upstream `wss://`/`ws://` URL for the home's single resident-
+ *  root target. `target` is always `home.home_agent_target` (server-derived,
+ *  never the client's request path — see module header). */
+function toWssUrl(previewEndpoint, target) {
+    const url = new URL(previewEndpoint);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.pathname = `/node/${encodeURIComponent(target)}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+function sendableCloseCode(code) {
+    if (!Number.isInteger(code) || code === 1005 || code === 1006 || code < 1000 || code > 4999)
+        return 1000;
+    return code;
+}
+function sendSocketClose(socket, code, reason) {
+    try {
+        socket.close(sendableCloseCode(code), reason.slice(0, 123));
+    }
+    catch {
+        try {
+            socket.terminate();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+const wsKeepaliveIntervalMs = 25_000;
+/** 25s ping/pong keepalive (M0 shape, kept verbatim — criterion 4). A socket
+ *  that never pongs back is terminated rather than left to leak. */
+function attachWsKeepalive(socket, context, options = {}) {
+    const intervalMs = options.intervalMs ?? wsKeepaliveIntervalMs;
+    let alive = true;
+    let stopped = false;
+    let timer = null;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (timer !== null)
+            clearInterval(timer);
+        socket.off('pong', onPong);
+    };
+    const onPong = () => {
+        alive = true;
+    };
+    const terminateStaleSocket = (message) => {
+        logError(message, { ...context, readyState: socket.readyState });
+        options.onStale?.();
+        try {
+            socket.terminate();
+        }
+        catch {
+            /* ignore */
+        }
+        stop();
+    };
+    const pingOrTerminate = () => {
+        if (stopped || socket.readyState !== WebSocket.OPEN)
+            return;
+        if (!alive) {
+            terminateStaleSocket('hearth control plane relay ws keepalive stale');
+            return;
+        }
+        alive = false;
+        try {
+            socket.ping();
+        }
+        catch {
+            terminateStaleSocket('hearth control plane relay ws keepalive ping failed');
+        }
+    };
+    socket.on('pong', onPong);
+    timer = setInterval(pingOrTerminate, intervalMs);
+    timer.unref?.();
+    return stop;
+}
+function createUpgradeServer() {
+    return new WebSocketServer({ noServer: true, maxPayload: BROKER_READ_CAPS.maxLineBytes });
+}
+/** Bridge one already-upgraded browser WebSocket to the home's resident-root
+ *  broker over `wss://<preview_endpoint>/node/<home_agent_target>`, carrying
+ *  the relay token as the upstream Authorization header (never reflected
+ *  back to the browser leg). Keepalive/teardown/close-code handling mirrors
+ *  M0 `proxy.ts`'s `proxyWebSocketBrowser` (criterion 4). */
+async function proxyWebSocketBrowser(browserWs, home, deps = {}) {
+    const ensureAwakeImpl = deps.ensureAwake ?? ensureAwake;
+    const config = (deps.loadConfig ?? loadControlPlaneConfig)();
+    const createUpstream = deps.createUpstream ??
+        ((url, relayToken) => new WebSocket(url, {
+            headers: { authorization: `Bearer ${relayToken}` },
+            perMessageDeflate: false,
+            handshakeTimeout: config.readyTimeoutMs,
+            maxPayload: BROKER_READ_CAPS.maxLineBytes,
+        }));
+    const handshakeAt = Date.now();
+    let upstream = null;
+    let teardownStarted = false;
+    let upstreamOpenAt = null;
+    let browserClose = null;
+    let upstreamClose = null;
+    const queued = [];
+    let stopBrowserKeepalive = () => { };
+    let stopUpstreamKeepalive = () => { };
+    const stopKeepalives = () => {
+        stopBrowserKeepalive();
+        stopUpstreamKeepalive();
+    };
+    const beginTeardown = () => {
+        if (teardownStarted)
+            return;
+        teardownStarted = true;
+        stopKeepalives();
+    };
+    stopBrowserKeepalive = attachWsKeepalive(browserWs, { home_id: home.home_id, leg: 'browser' }, { onStale: beginTeardown });
+    const logClose = (leg, code, reason) => {
+        logError('hearth control plane relay ws close', {
+            home_id: home.home_id,
+            leg,
+            code,
+            reason,
+            handshakeToUpstreamOpenMs: upstreamOpenAt === null ? null : upstreamOpenAt - handshakeAt,
+            browserCloseCode: browserClose?.code ?? null,
+            browserCloseReason: browserClose?.reason ?? null,
+            upstreamCloseCode: upstreamClose?.code ?? null,
+            upstreamCloseReason: upstreamClose?.reason ?? null,
+            browserReadyState: browserWs.readyState,
+            upstreamReadyState: upstream?.readyState ?? 'none',
+            teardownStarted,
+        });
+    };
+    const closeBoth = (code, reason) => {
+        beginTeardown();
+        if (browserWs.readyState === WebSocket.OPEN || browserWs.readyState === WebSocket.CONNECTING) {
+            sendSocketClose(browserWs, code, reason);
+        }
+        if (upstream !== null && (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING)) {
+            sendSocketClose(upstream, code, reason);
+        }
+    };
+    browserWs.on('message', (data, isBinary) => {
+        if (upstream === null || upstream.readyState !== WebSocket.OPEN) {
+            queued.push({ data, isBinary });
+            return;
+        }
+        try {
+            upstream.send(data, { binary: isBinary });
+        }
+        catch {
+            closeBoth(1011, 'failed to relay browser frame');
+        }
+    });
+    browserWs.on('close', (code, reason) => {
+        const closeReason = reason.toString('utf8').slice(0, 123);
+        browserClose = { code, reason: closeReason };
+        logClose('browser', code, closeReason);
+        beginTeardown();
+        if (upstream !== null && (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING)) {
+            sendSocketClose(upstream, code, closeReason);
+        }
+    });
+    browserWs.on('error', (error) => {
+        logError('hearth control plane relay browser websocket failed', { home_id: home.home_id, error: error instanceof Error ? error.message : String(error) });
+        closeBoth(1011, 'browser websocket error');
+    });
+    try {
+        const awakened = await withTimeout(ensureAwakeImpl(home.home_id), config.wakeTimeoutMs, 'control plane relay websocket wake');
+        const target = home.home_agent_target?.trim() ?? '';
+        if (target === '')
+            throw general(`home ${home.home_id} is missing home_agent_target — cannot relay`, { home_id: home.home_id });
+        if (browserWs.readyState !== WebSocket.OPEN) {
+            beginTeardown();
+            return;
+        }
+        upstream = createUpstream(toWssUrl(awakened.preview_endpoint, target), awakened.relayToken);
+        upstream.on('open', () => {
+            if (teardownStarted || browserWs.readyState !== WebSocket.OPEN) {
+                beginTeardown();
+                if (upstream !== null && (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING)) {
+                    sendSocketClose(upstream, 1000, 'browser websocket closed before upstream open');
+                }
+                return;
+            }
+            upstreamOpenAt = Date.now();
+            stopUpstreamKeepalive = attachWsKeepalive(upstream, { home_id: home.home_id, leg: 'upstream' }, { onStale: beginTeardown });
+            for (const frame of queued.splice(0, queued.length)) {
+                try {
+                    upstream.send(frame.data, { binary: frame.isBinary });
+                }
+                catch {
+                    closeBoth(1011, 'failed to flush buffered browser frame');
+                    return;
+                }
+            }
+        });
+        upstream.on('message', (data, isBinary) => {
+            if (browserWs.readyState !== WebSocket.OPEN)
+                return;
+            browserWs.send(data, { binary: isBinary });
+        });
+        upstream.on('close', (code, reason) => {
+            const closeReason = reason.toString('utf8').slice(0, 123);
+            upstreamClose = { code, reason: closeReason };
+            logClose('upstream', code, closeReason);
+            beginTeardown();
+            if (browserWs.readyState === WebSocket.OPEN || browserWs.readyState === WebSocket.CONNECTING) {
+                sendSocketClose(browserWs, code, closeReason);
+            }
+        });
+        upstream.on('error', (error) => {
+            logError('hearth control plane relay ws upstream failed', { home_id: home.home_id, error: error instanceof Error ? error.message : String(error) });
+            (deps.invalidateWarmVerdict ?? invalidateWarmVerdict)(home.home_id);
+            closeBoth(1011, 'upstream websocket error');
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError('hearth control plane relay websocket wake failed', { home_id: home.home_id, error: message });
+        (deps.invalidateWarmVerdict ?? invalidateWarmVerdict)(home.home_id);
+        closeBoth(/timed out/i.test(message) ? 1013 : 1011, /timed out/i.test(message) ? 'wake timeout' : 'wake failed');
+    }
+}
+/** `RelayDispatcher.proxyUpgrade`: complete the WS handshake on the already
+ *  session+registry-gated socket (`server.ts`'s `handleUpgrade`), then bridge
+ *  it to the home. Errors after this point close the browser socket in-band
+ *  with a WS close code (1011/1013) rather than a raw TCP reset, so the
+ *  client sees a clean failure (criterion 4: "keep ... close behavior from
+ *  M0 where applicable"). */
+export function proxyUpgrade(req, socket, head, home, deps = {}) {
+    const wss = createUpgradeServer();
+    wss.handleUpgrade(req, socket, head, (browserWs) => {
+        void proxyWebSocketBrowser(browserWs, home, deps).catch((error) => {
+            logError('hearth control plane relay websocket bridge failed', { home_id: home.home_id, error: error instanceof Error ? error.message : String(error) });
+            try {
+                browserWs.terminate();
+            }
+            catch {
+                /* ignore */
+            }
+        });
+    });
+}
+/** The real `RelayDispatcher` `main.ts` wires in once the CP server is built
+ *  — `server.ts`'s default (`notImplementedRelay`) is only ever used when a
+ *  caller (test/smoke) doesn't inject one. */
+export const controlPlaneRelay = {
+    proxyHttp,
+    proxyUpgrade,
+};

package/dist/hearth/control-plane/scheduler/fire-store.d.ts

@@ -0,0 +1,36 @@
+export type ScheduleFireState = 'pending' | 'waking' | 'delivered' | 'failed';
+export interface ScheduleFireRow {
+    fire_id: string;
+    schedule_id: string;
+    home_id: string;
+    tenant_id: string;
+    user_id: string;
+    scheduled_for: string;
+    state: ScheduleFireState;
+    attempts: number;
+    last_error: string | null;
+    delivered_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ClaimFireInput {
+    fire_id?: string;
+    schedule_id: string;
+    scheduled_for: string;
+    now?: string;
+}
+export interface ClaimFireResult {
+    fire: ScheduleFireRow;
+    claimed: boolean;
+}
+export interface SetFireStateOptions {
+    last_error?: string | null;
+    delivered_at?: string | null;
+    increment_attempts?: boolean;
+    now?: string;
+}
+export declare function claimFire(input: ClaimFireInput): ClaimFireResult;
+export declare function getFireById(fireId: string): ScheduleFireRow | null;
+export declare function getFireByScheduleSlot(scheduleId: string, scheduledFor: string): ScheduleFireRow | null;
+export declare function setFireState(fireId: string, state: ScheduleFireState, options?: SetFireStateOptions): void;
+export declare function selectResumableFires(limit?: number): ScheduleFireRow[];