@crouton-kit/crouter 0.3.39 → 0.3.41

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

@@ -1,711 +0,0 @@
-// 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 { beginHttp, beginWs, endHttp, endWs } from './serving.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`);
-}
-/** Serialize a non-`Error` rejection for a log line without collapsing it to `"[object Object]"`
- *  (`String(error)` on a plain object) — recreate-race-fix.md §3.6. Falls back to `String` only
- *  if the value itself isn't JSON-serializable (a circular structure, a BigInt, etc). */
-export function serializeRelayError(error) {
-    try {
-        // `JSON.stringify` returns `undefined` (does not throw) for `undefined`, a function, or a
-        // symbol. Falling through to that here would hand the `message.startsWith('relay ')`/
-        // `/timed out/i` control-flow checks right after this an `undefined` string and THROW
-        // inside the catch block — exactly the control-flow change this rider promised not to make.
-        const json = JSON.stringify(error);
-        return json === undefined ? String(error) : json;
-    }
-    catch {
-        return String(error);
-    }
-}
-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 {
-                // Mark this home as actively serving ONLY around the actual data
-                // transfer, never around the wake DECISION above it. Bumping the
-                // counter any earlier (e.g. unconditionally on function
-                // entry, before `ensureAwake` runs below) would make a home's very
-                // FIRST request after being suspended see ITS OWN just-begun counter
-                // and read as "serving" — `isHomeStale && !homeIsServing` would then
-                // never be true for any home, ever, silently disabling every roll
-                // (verified live: `beginHttp` then `isHomeServing` in the same tick
-                // returns true with zero other activity). Scoping begin/end tightly
-                // around each `forwardUpstream` call still protects the real target
-                // (a genuinely separate, already-open session on this home) because
-                // that session's OWN counter is independent and already non-zero.
-                beginHttp(home.home_id);
-                try {
-                    await forwardUpstream(req, res, running, controller);
-                }
-                finally {
-                    endHttp(home.home_id);
-                }
-                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');
-        beginHttp(home.home_id);
-        try {
-            await forwardUpstream(req, res, awakened, controller);
-        }
-        finally {
-            endHttp(home.home_id);
-        }
-    }
-    catch (error) {
-        // A non-`Error` rejection (e.g. a raw object thrown from outside the SDK's recognized error
-        // shapes) must not serialize to "[object Object]" here — that loss of the real error is what
-        // cost the recreate-race incident its diagnosis (recreate-race-fix.md §3.6). `message` below
-        // still drives the control-flow checks that follow (relay-prefixed/timeout messages), which
-        // only ever come from `Error` instances (`general()`), so this branch change cannot affect them.
-        const message = error instanceof Error ? error.message : serializeRelayError(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;
-    // Whether THIS bridge has actually incremented `wsOpen` (set true only
-    // once the upstream leg is being established — see below —
-    // and guards the `close`-handler `endWs` call so a bridge whose own
-    // `ensureAwake` failed before ever counting itself can't decrement a
-    // DIFFERENT, still-live session's counter for the same home).
-    let wsCounted = 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);
-        }
-        if (wsCounted) {
-            wsCounted = false;
-            endWs(home.home_id);
-        }
-    });
-    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;
-        }
-        // Mark this home as actively serving ONLY once the wake DECISION above
-        // has already resolved — not on function entry.
-        // `ensureAwake` (inside the wait above) makes the roll-vs-normal-wake
-        // call by consulting this very tracker; counting a bridge as "open"
-        // before that decision runs would make a home's very first WS reconnect
-        // after being suspended see ITS OWN not-yet-real session and read as
-        // "serving," permanently blocking the roll this connection was itself
-        // supposed to trigger (mirrors the identical HTTP hazard in `proxyHttp`
-        // above — verified live for the HTTP case; same mechanism applies here).
-        // A genuinely separate, already-open bridge for this home is unaffected:
-        // its own counter is already live and independent of this one.
-        beginWs(home.home_id);
-        wsCounted = true;
-        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,
-};