@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/hearth/{wake-proxy/proxy.js → control-plane/relay.js}

@@ -1,10 +1,42 @@
+// 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 { 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';
+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',
@@ -16,11 +48,8 @@ const hopByHopHeaders = new Set([
     '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]');
+    return redactSecrets(tenantSessionAuthRedactedMessage(message));
 }
 function redactDeep(value) {
     if (typeof value === 'string')
@@ -32,96 +61,17 @@ function redactDeep(value) {
     }
     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)) } };
-}
+/** 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 })}\n`);
+    process.stderr.write(`${JSON.stringify({ level: 'error', message, details: redactDeep(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];
@@ -129,40 +79,71 @@ function decodePathForValidation(raw) {
             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]' });
+                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('proxy rejected control or backslash characters in request target', { requestUrl: '[redacted]' });
+                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('proxy rejected control characters in request target', { requestUrl: '[redacted]' });
+            throw general('relay rejected control characters in request target', { requestUrl: '[redacted]' });
         }
     }
 }
-export function buildUpstreamHttpUrl(routeUrl, rawRequestUrl) {
-    const route = new URL(routeUrl);
+/** 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('proxy rejected request target that escapes the upstream origin', { requestUrl: raw.replace(/\?.*$/, '') });
+        throw general('relay 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;
 }
+/** 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.startsWith('proxy-') || lower.startsWith('sec-websocket-') || hopByHopHeaders.has(lower)) {
+        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);
@@ -171,14 +152,17 @@ function filteredRequestHeaders(req, 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) {
-    // Same-origin relative redirect (origin-form) is safe to forward verbatim.
-    if (location.startsWith('/') && !location.startsWith('//'))
+    if (location.startsWith('/') && !location.startsWith('//') && !location.includes('\\'))
         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}`;
     }
@@ -190,7 +174,7 @@ function sanitizeLocation(location, upstreamOrigin) {
 function applyResponseHeaders(res, headers, upstreamOrigin) {
     headers.forEach((value, key) => {
         const lower = key.toLowerCase();
-        if (lower === 'set-cookie' || hopByHopHeaders.has(lower) || lower.startsWith('proxy-'))
+        if (lower === 'set-cookie' || lower === 'authorization' || hopByHopHeaders.has(lower) || lower.startsWith('proxy-'))
             return;
         if (lower === 'location') {
             const sanitized = sanitizeLocation(value, upstreamOrigin);
@@ -265,7 +249,7 @@ async function streamResponseBody(body, res, signal) {
         reader.releaseLock();
     }
 }
-async function withWakeTimeout(work, timeoutMs, label) {
+async function withTimeout(work, timeoutMs, label) {
     if (timeoutMs <= 0)
         return work;
     let timer = null;
@@ -283,25 +267,30 @@ async function withWakeTimeout(work, timeoutMs, label) {
             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.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 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.
+ * 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.routeUrl, requestPath(req));
+    const upstreamUrl = buildUpstreamHttpUrl(awakened.preview_endpoint, requestPath(req));
     const method = req.method ?? 'GET';
     const canHaveBody = method !== 'GET' && method !== 'HEAD';
     const requestInit = {
@@ -316,12 +305,11 @@ async function forwardUpstream(req, res, awakened, controller) {
     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) {
+    if (isEventStream)
         responseHeaders.delete('content-length');
-    }
     res.statusCode = response.status;
     res.statusMessage = response.statusText;
-    applyResponseHeaders(res, responseHeaders, new URL(awakened.routeUrl).origin);
+    applyResponseHeaders(res, responseHeaders, new URL(awakened.preview_endpoint).origin);
     tuneStreamingHeaders(res, isEventStream);
     if (response.body === null || method === 'HEAD') {
         res.end();
@@ -332,113 +320,61 @@ async function forwardUpstream(req, res, awakened, controller) {
     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');
+/** 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 {
-        // 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);
+        const running = resolveRunningImpl(home.home_id);
         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', {
+                logError('hearth control plane relay running-route forward failed; escalating to deliberate wake', {
+                    home_id: home.home_id,
                     path: requestPath(req).replace(/\?.*$/, ''),
-                    ...serializeWakeProxyError(error),
+                    error: error instanceof Error ? error.message : String(error),
                 });
-                invalidateWarmVerdict(requestAuth.tenantId);
+                invalidate(home.home_id);
             }
         }
-        // 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');
+        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 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)) {
+        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('proxy ') ? 400 : 502, message.startsWith('proxy ') ? 'bad request' : 'bad gateway');
+            closeHttpWithError(res, message.startsWith('relay ') ? 400 : 502, message.startsWith('relay ') ? 'bad request' : 'bad gateway');
             return;
         }
         try {
@@ -450,20 +386,21 @@ export async function proxyHttpRequest(req, res, runtime) {
     }
     finally {
         cleanup();
-        releaseActivity(activity);
     }
 }
-function toWssUrl(routeUrl, nodeId) {
-    const url = new URL(routeUrl);
-    url.protocol = 'wss:';
-    url.pathname = `/node/${encodeURIComponent(nodeId)}`;
+// --- 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) {
-    // 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;
@@ -482,6 +419,8 @@ function sendSocketClose(socket, code, reason) {
     }
 }
 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;
@@ -513,7 +452,7 @@ function attachWsKeepalive(socket, context, options = {}) {
         if (stopped || socket.readyState !== WebSocket.OPEN)
             return;
         if (!alive) {
-            terminateStaleSocket('hearth wake proxy ws keepalive stale');
+            terminateStaleSocket('hearth control plane relay ws keepalive stale');
             return;
         }
         alive = false;
@@ -521,7 +460,7 @@ function attachWsKeepalive(socket, context, options = {}) {
             socket.ping();
         }
         catch {
-            terminateStaleSocket('hearth wake proxy ws keepalive ping failed');
+            terminateStaleSocket('hearth control plane relay ws keepalive ping failed');
         }
     };
     socket.on('pong', onPong);
@@ -532,25 +471,28 @@ function attachWsKeepalive(socket, context, options = {}) {
 function createUpgradeServer() {
     return new WebSocketServer({ noServer: true, maxPayload: BROKER_READ_CAPS.maxLineBytes });
 }
-async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps = {}) {
+/** 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 }));
-    const activity = acquireActivity(tenantId, 'ws');
+        ((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 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 = () => {
@@ -562,13 +504,11 @@ async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps
             return;
         teardownStarted = true;
         stopKeepalives();
-        release();
     };
-    stopBrowserKeepalive = attachWsKeepalive(browserWs, { nodeId, tenantId, leg: 'browser' }, { onStale: beginTeardown });
+    stopBrowserKeepalive = attachWsKeepalive(browserWs, { home_id: home.home_id, leg: 'browser' }, { onStale: beginTeardown });
     const logClose = (leg, code, reason) => {
-        logError('hearth wake proxy ws close', {
-            nodeId,
-            tenantId,
+        logError('hearth control plane relay ws close', {
+            home_id: home.home_id,
             leg,
             code,
             reason,
@@ -613,16 +553,19 @@ async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps
         }
     });
     browserWs.on('error', (error) => {
-        logError('hearth wake proxy browser websocket failed', { nodeId, error: redact(error instanceof Error ? error.message : String(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 withWakeTimeout(ensureAwakeImpl(tenantId), runtime.proxy.wakeTimeoutMs, 'wake proxy websocket');
+        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.routeUrl, nodeId), awakened.relayToken);
+        upstream = createUpstream(toWssUrl(awakened.preview_endpoint, target), awakened.relayToken);
         upstream.on('open', () => {
             if (teardownStarted || browserWs.readyState !== WebSocket.OPEN) {
                 beginTeardown();
@@ -632,14 +575,7 @@ async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps
                 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 });
+            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 });
@@ -665,52 +601,42 @@ async function proxyWebSocketBrowser(browserWs, nodeId, tenantId, runtime, deps
             }
         });
         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);
+            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 wake proxy websocket wake failed', { nodeId, ...serializeWakeProxyError(error) });
-        invalidateWarmVerdict(tenantId);
+        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');
     }
 }
-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;
-    }
+/** `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, nodeId, auth.tenantId, runtime);
+        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,
+};