@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/wake-proxy/proxy.js

@@ -0,0 +1,716 @@
+import { Readable } from 'node:stream';
+import { WebSocket, WebSocketServer } from 'ws';
+import { BROKER_READ_CAPS } from '../../core/runtime/broker-protocol.js';
+import { CrtrError, general } from '../../core/errors.js';
+import { loadProxyState, ensureProxyState } from './state.js';
+import { acquireActivity, ensureAwake, invalidateWarmVerdict, releaseActivity, resolveRunningHome } from './home.js';
+import { ownerAuthRedactedMessage, resolveOwnerAuth, setOwnerCookie } from './auth.js';
+const hopByHopHeaders = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+function currentState(runtime) {
+    return loadProxyState(runtime.proxy.statePath) ?? ensureProxyState(runtime.proxy);
+}
+function redact(message) {
+    return ownerAuthRedactedMessage(message).replace(/\bsha256:[0-9a-f]{64}\b/gi, 'sha256:[redacted]');
+}
+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;
+}
+export function serializeWakeProxyError(error) {
+    if (error instanceof CrtrError) {
+        return {
+            error: {
+                code: error.code,
+                message: redact(error.message),
+                exitCode: error.exitCode,
+                ...(error.details === undefined ? {} : { details: redactDeep(error.details) }),
+            },
+        };
+    }
+    if (error instanceof Error) {
+        return { error: { message: redact(error.message) } };
+    }
+    return { error: { message: redact(String(error)) } };
+}
+function logError(message, details = {}) {
+    process.stderr.write(`${JSON.stringify({ level: 'error', message, details })}\n`);
+}
+function requestPath(req) {
+    return req.url ?? '/';
+}
+function requestPathname(req) {
+    return new URL(requestPath(req), 'http://127.0.0.1').pathname;
+}
+const publicStaticAssetPaths = new Set([
+    '/favicon.ico',
+    '/favicon.svg',
+    '/favicon.png',
+    '/apple-touch-icon.png',
+    '/apple-touch-icon-precomposed.png',
+    '/manifest.webmanifest',
+    '/site.webmanifest',
+    '/robots.txt',
+    '/vite.svg',
+]);
+const publicStaticAssetExtensions = new Set([
+    '.css',
+    '.js',
+    '.mjs',
+    '.map',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.svg',
+    '.ico',
+    '.json',
+    '.txt',
+]);
+export function isPublicStaticAssetPath(pathname) {
+    if (pathname.startsWith('/assets/'))
+        return true;
+    if (publicStaticAssetPaths.has(pathname))
+        return true;
+    const match = /^\/[^/?#]+(\.[^/?#]+)$/.exec(pathname);
+    return match !== null && publicStaticAssetExtensions.has(match[1].toLowerCase());
+}
+function stripTokenFromTarget(rawUrl) {
+    const url = new URL(rawUrl, 'http://127.0.0.1');
+    url.searchParams.delete('token');
+    const query = url.searchParams.toString();
+    return `${url.pathname}${query === '' ? '' : `?${query}`}`;
+}
+function extractNodeId(pathname) {
+    const match = /^\/node\/([^/?#]+)\/?$/.exec(pathname);
+    if (match === null)
+        return null;
+    try {
+        const nodeId = decodeURIComponent(match[1]);
+        if (nodeId === '' || /[/\\]/.test(nodeId) || nodeId.includes('..'))
+            return null;
+        return nodeId;
+    }
+    catch {
+        return null;
+    }
+}
+function validateOriginFormRequestTarget(rawRequestUrl) {
+    const raw = rawRequestUrl === undefined || rawRequestUrl === '' ? '/' : rawRequestUrl;
+    if (!raw.startsWith('/')) {
+        throw general('proxy only accepts origin-form request targets', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    if (raw.startsWith('//')) {
+        throw general('proxy rejected scheme-relative request target', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    decodePathForValidation(raw);
+    return raw;
+}
+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('proxy 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('proxy rejected control or backslash characters in request target', { requestUrl: '[redacted]' });
+            }
+            i += 2;
+            continue;
+        }
+        if (ch === '\\' || ch === '\u0000' || ch < ' ' || ch === '\u007f') {
+            throw general('proxy rejected control characters in request target', { requestUrl: '[redacted]' });
+        }
+    }
+}
+export function buildUpstreamHttpUrl(routeUrl, rawRequestUrl) {
+    const route = new URL(routeUrl);
+    const raw = validateOriginFormRequestTarget(rawRequestUrl);
+    const upstream = new URL(raw, route);
+    if (upstream.origin !== route.origin) {
+        throw general('proxy rejected request target that escapes the upstream origin', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    upstream.searchParams.delete('token');
+    if (upstream.origin !== route.origin) {
+        throw general('proxy rejected upstream origin mismatch', { requestUrl: raw.replace(/\?.*$/, '') });
+    }
+    return upstream;
+}
+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.startsWith('proxy-') || lower.startsWith('sec-websocket-') || 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;
+}
+function sanitizeLocation(location, upstreamOrigin) {
+    // Same-origin relative redirect (origin-form) is safe to forward verbatim.
+    if (location.startsWith('/') && !location.startsWith('//'))
+        return location;
+    try {
+        const abs = new URL(location, upstreamOrigin);
+        // An absolute redirect back to the upstream route origin is rewritten to a Hearth-relative path so
+        // the browser stays behind the front door; any other absolute origin is dropped entirely.
+        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' || 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 withWakeTimeout(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);
+    }
+}
+export const proxyInternals = {
+    withWakeTimeout,
+    attachWsKeepalive,
+    proxyWebSocketBrowser,
+};
+function closeHttpWithError(res, statusCode, message) {
+    if (!res.headersSent) {
+        res.writeHead(statusCode, { 'content-type': 'text/plain; charset=utf-8' });
+    }
+    res.end(`${message}\n`);
+}
+/**
+ * Forward one HTTP request to an already-selected upstream route 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 — it never throws here, so it is never mistaken for a dead home.
+ */
+async function forwardUpstream(req, res, awakened, controller) {
+    const upstreamUrl = buildUpstreamHttpUrl(awakened.routeUrl, 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.routeUrl).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();
+}
+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);
+    };
+}
+export async function proxyHttpRequest(req, res, runtime) {
+    const pathname = requestPathname(req);
+    const isPublicStaticAsset = (req.method === 'GET' || req.method === 'HEAD') && isPublicStaticAssetPath(pathname);
+    const state = currentState(runtime);
+    let auth = null;
+    try {
+        auth = resolveOwnerAuth(req, runtime.proxy, state);
+    }
+    catch {
+        if (!isPublicStaticAsset) {
+            if (!res.headersSent)
+                closeHttpWithError(res, 403, 'forbidden');
+            return;
+        }
+    }
+    if (auth === null && !isPublicStaticAsset) {
+        if (!res.headersSent)
+            closeHttpWithError(res, 401, 'owner token required');
+        return;
+    }
+    const requestAuth = auth ?? {
+        ownerUserId: state.owner.ownerUserId,
+        tenantId: state.owner.defaultTenantId,
+        source: 'cookie',
+        token: '',
+    };
+    // An owner token in a ?token= query must never persist in the browser URL/history or be used to
+    // serve a proxied response. On a GET/HEAD deep link, convert it to the HttpOnly cookie and 303
+    // to the same tokenless path (mirroring GET /); reject it on any other method so the client
+    // retries via cookie/Bearer. The only legitimate token URL is the one immediately swapped here.
+    if (requestAuth.source === 'query') {
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            setOwnerCookie(res, requestAuth.token, runtime.proxy);
+            res.writeHead(303, {
+                location: stripTokenFromTarget(requestPath(req)),
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+            });
+            res.end();
+            return;
+        }
+        if (!res.headersSent)
+            closeHttpWithError(res, 401, 'owner token required');
+        return;
+    }
+    const activity = acquireActivity(requestAuth.tenantId, 'http');
+    const controller = new AbortController();
+    const cleanup = addRequestAbort(req, res, controller);
+    try {
+        // Fast path: a home crtr already records as `running` with a known route+token is forwarded
+        // directly — the forward itself is the liveness check. Normal GET/asset/SSE traffic must NOT
+        // enter the heavy ensureAwake/restore gate (probe + 150s serial guest execs) while the direct
+        // home route is serving 200 in ~0.1s. Only a missing/not-running home, or a CLEAR upstream
+        // failure against the trusted route, escalates to the deliberate wake path below.
+        const running = resolveRunningHome(requestAuth.tenantId);
+        if (running !== null) {
+            try {
+                await forwardUpstream(req, res, running, controller);
+                return;
+            }
+            catch (error) {
+                // Reaching here means a genuine upstream/network failure (app 4xx/5xx never throw). If
+                // nothing was sent, the client is still here, and the request is safe to replay (no body),
+                // the running verdict was stale — invalidate it and escalate to ONE deliberate wake.
+                // Anything else (mid-stream failure, aborted, or a body-bearing method we can't replay)
+                // rethrows to the handler's error path, which 502s and invalidates the warm verdict.
+                const method = req.method ?? 'GET';
+                const replayable = method === 'GET' || method === 'HEAD';
+                if (res.headersSent || controller.signal.aborted || !replayable)
+                    throw error;
+                logError('hearth wake proxy running-route forward failed; escalating to deliberate wake', {
+                    path: requestPath(req).replace(/\?.*$/, ''),
+                    ...serializeWakeProxyError(error),
+                });
+                invalidateWarmVerdict(requestAuth.tenantId);
+            }
+        }
+        // Deliberate wake path: missing/not-running home, or a stale running verdict that just failed.
+        // Bounded by wakeTimeoutMs; ensureAwake probes/restores under the per-tenant lock.
+        const awakened = await withWakeTimeout(ensureAwake(requestAuth.tenantId), runtime.proxy.wakeTimeoutMs, 'wake proxy request');
+        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 wake proxy HTTP request failed', { path: requestPath(req).replace(/\?.*$/, ''), ...serializeWakeProxyError(error) });
+        // An upstream forward failure (bad gateway / wake timeout) may mean the home died mid-TTL. Drop
+        // the cached warm verdict so the next request re-probes/restores instead of serving the stale
+        // "serving" answer for the rest of the window. Pure request-validation errors leave it intact.
+        if (!message.startsWith('proxy '))
+            invalidateWarmVerdict(requestAuth.tenantId);
+        if (controller.signal.aborted && /timed out/i.test(message)) {
+            closeHttpWithError(res, 504, 'wake timeout');
+            return;
+        }
+        if (!res.headersSent) {
+            closeHttpWithError(res, message.startsWith('proxy ') ? 400 : 502, message.startsWith('proxy ') ? 'bad request' : 'bad gateway');
+            return;
+        }
+        try {
+            res.destroy();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    finally {
+        cleanup();
+        releaseActivity(activity);
+    }
+}
+function toWssUrl(routeUrl, nodeId) {
+    const url = new URL(routeUrl);
+    url.protocol = 'wss:';
+    url.pathname = `/node/${encodeURIComponent(nodeId)}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+function sendableCloseCode(code) {
+    // 1005 (no status) and 1006 (abnormal) are reserved and must never be sent; clamp anything
+    // outside the sendable ranges back to 1000 so close() does not throw.
+    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;
+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 wake proxy ws keepalive stale');
+            return;
+        }
+        alive = false;
+        try {
+            socket.ping();
+        }
+        catch {
+            terminateStaleSocket('hearth wake proxy 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 });
+}
+async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps = {}) {
+    const ensureAwakeImpl = deps.ensureAwake ?? ensureAwake;
+    const createUpstream = deps.createUpstream ??
+        ((url, relayToken) => new WebSocket(url, { headers: { authorization: `Bearer ${relayToken}` }, perMessageDeflate: false }));
+    const activity = acquireActivity(tenantId, 'ws');
+    const handshakeAt = Date.now();
+    let upstream = null;
+    let settled = false;
+    let teardownStarted = false;
+    let upstreamOpenAt = null;
+    let browserClose = null;
+    let upstreamClose = null;
+    const queued = [];
+    const release = () => {
+        if (settled)
+            return;
+        settled = true;
+        releaseActivity(activity);
+    };
+    let stopBrowserKeepalive = () => { };
+    let stopUpstreamKeepalive = () => { };
+    const stopKeepalives = () => {
+        stopBrowserKeepalive();
+        stopUpstreamKeepalive();
+    };
+    const beginTeardown = () => {
+        if (teardownStarted)
+            return;
+        teardownStarted = true;
+        stopKeepalives();
+        release();
+    };
+    stopBrowserKeepalive = attachWsKeepalive(browserWs, { nodeId, tenantId, leg: 'browser' }, { onStale: beginTeardown });
+    const logClose = (leg, code, reason) => {
+        logError('hearth wake proxy ws close', {
+            nodeId,
+            tenantId,
+            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 wake proxy browser websocket failed', { nodeId, error: redact(error instanceof Error ? error.message : String(error)) });
+        closeBoth(1011, 'browser websocket error');
+    });
+    try {
+        const awakened = await withWakeTimeout(ensureAwakeImpl(tenantId), runtime.proxy.wakeTimeoutMs, 'wake proxy websocket');
+        if (browserWs.readyState !== WebSocket.OPEN) {
+            beginTeardown();
+            return;
+        }
+        upstream = createUpstream(toWssUrl(awakened.routeUrl, nodeId), 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();
+            logError('hearth wake proxy ws upstream open', {
+                nodeId,
+                tenantId,
+                handshakeToUpstreamOpenMs: upstreamOpenAt - handshakeAt,
+                browserReadyState: browserWs.readyState,
+                upstreamReadyState: upstream.readyState,
+            });
+            stopUpstreamKeepalive = attachWsKeepalive(upstream, { nodeId, tenantId, 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 wake proxy WS upstream failed', { nodeId, error: redact(error instanceof Error ? error.message : String(error)) });
+            // The upstream leg failed — the home may be down; re-probe on the next connect.
+            invalidateWarmVerdict(tenantId);
+            closeBoth(1011, 'upstream websocket error');
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError('hearth wake proxy websocket wake failed', { nodeId, ...serializeWakeProxyError(error) });
+        invalidateWarmVerdict(tenantId);
+        closeBoth(/timed out/i.test(message) ? 1013 : 1011, /timed out/i.test(message) ? 'wake timeout' : 'wake failed');
+    }
+}
+export function proxyUpgrade(req, socket, head, runtime) {
+    let nodeId = null;
+    try {
+        const rawTarget = validateOriginFormRequestTarget(req.url);
+        const pathname = new URL(rawTarget, 'http://127.0.0.1').pathname;
+        nodeId = extractNodeId(pathname);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        socket.write(`HTTP/1.1 ${message.startsWith('proxy ') ? '400 Bad Request' : '403 Forbidden'}\r\nConnection: close\r\n\r\n`);
+        socket.destroy();
+        return;
+    }
+    if (nodeId === null) {
+        socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    let auth;
+    try {
+        const state = currentState(runtime);
+        auth = resolveOwnerAuth(req, runtime.proxy, state);
+    }
+    catch {
+        auth = null;
+    }
+    if (auth === null) {
+        socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+        socket.destroy();
+        return;
+    }
+    const wss = createUpgradeServer();
+    wss.handleUpgrade(req, socket, head, (browserWs) => {
+        void proxyWebSocketBrowser(browserWs, nodeId, auth.tenantId, runtime);
+    });
+}