@crouton-kit/crouter 0.3.33 → 0.3.34

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

@@ -0,0 +1,346 @@
+// control-plane/server.ts — the CP front door. Generalizes the wake-proxy's
+// server.ts (route dispatch) and proxy.ts's gate ordering into the CP shape:
+// session-then-registry resolution before anything ever reaches a home, and
+// a swappable relay dispatch boundary for the dynamic lanes the actual
+// HTTP+WS relay engine (P4.3) will fill in.
+//
+// Route tree (master plan P4.1 / part-plan T2.2). Every dynamic lane is an
+// exact method+path entry in `DYNAMIC_ROUTES` below; anything else on a
+// known dynamic-lane path is a 405, and anything unrecognized is a 404 —
+// neither ever reaches the relay:
+//   GET  /__hearth/healthz                       -> liveness, no auth
+//   GET/HEAD /                                    -> resolveTenantSession ->
+//                                                     resolveHome -> 302 to
+//                                                     the existing in-guest
+//                                                     client path carrying
+//                                                     ONLY the
+//                                                     server-derived
+//                                                     `home_agent_target`;
+//                                                     absent/invalid session
+//                                                     or unresolved home
+//                                                     never reaches a home
+//                                                     (no relay/wake call)
+//   WS   /node/<id>                               -> dynamic lane, upgrade
+//                                                     only (never a normal
+//                                                     HTTP dispatcher entry),
+//                                                     gated by the same
+//                                                     write-capable auth as
+//                                                     write lanes (trusted-
+//                                                     Origin cookie OR
+//                                                     no-Origin Bearer) and
+//                                                     an exact single-segment
+//                                                     `<id>` matcher
+//   POST /__crtr/source                           -> dynamic lane, write-auth
+//   GET  /__crtr/events                           -> dynamic lane, read-auth
+//   GET  /__hearth/model-auth/anthropic/status     -> dynamic lane, read-auth
+//   POST /__hearth/model-auth/anthropic/start      -> dynamic lane, write-auth
+//   POST /__hearth/model-auth/anthropic/finish     -> dynamic lane, write-auth
+//   GET/HEAD /views/<view>                        -> dynamic lane, read-auth
+//                                                     (the SPA shell `GET /`
+//                                                     redirects to)
+//   GET/HEAD <static asset path>                  -> dynamic lane, read-auth
+//                                                     (the JS/CSS/image
+//                                                     assets the view shell
+//                                                     loads) — still gated by
+//                                                     session+registry, NOT a
+//                                                     public/unauthenticated
+//                                                     allowlist
+//
+// The relay engine itself (ensureAwake + HTTP/WS forwarding to
+// preview_endpoint) is P4.2/P4.3 scope, not this file's. The `RelayDispatcher`
+// seam below is the stub boundary: every dynamic-lane request is gated by
+// session(+write-origin where required)+registry resolution here, then
+// handed to the dispatcher, which today simply reports "not implemented yet"
+// without contacting any home.
+import { createServer } from 'node:http';
+import { getControlPlaneDb } from './db.js';
+import { resolveHome } from './registry.js';
+import { resolveTenantSession, resolveTenantWriteAuth, swapQueryTokenForCookie, tenantSessionAuthRedactedMessage } from './session.js';
+import { redactSecrets } from './secrets.js';
+import { handleWebhookRequest, isWebhookPath, isWebhookRequest } from './register.js';
+const notImplementedRelay = {
+    proxyHttp(_req, res) {
+        sendText(res, 501, 'hearth control-plane relay is not implemented yet (lands in P4.3)\n');
+    },
+    proxyUpgrade(_req, socket) {
+        socket.destroy();
+    },
+};
+function requestUrl(req) {
+    return new URL(req.url ?? '/', 'http://127.0.0.1');
+}
+function sendText(res, statusCode, body) {
+    res.writeHead(statusCode, {
+        'content-type': 'text/plain; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+        'referrer-policy': 'no-referrer',
+    });
+    res.end(body);
+}
+function redirectChat(res, target) {
+    res.writeHead(302, {
+        location: `/views/chat?target=${encodeURIComponent(target)}`,
+        'cache-control': 'no-store',
+        'referrer-policy': 'no-referrer',
+    });
+    res.end();
+}
+function respondHealthz(res) {
+    sendText(res, 200, 'ok\n');
+}
+/** `?token=` is intentionally not accepted as durable auth (`session.ts`); the
+ *  one allowed query-token use is the single-use M0 handoff swap-to-cookie,
+ *  attempted here only when no durable cookie/bearer session is already
+ *  present, and only ever turned into a session via that one origin-checked
+ *  swap function — never read/trusted directly by this route. */
+function resolveRootSession(req, res, config, store) {
+    const direct = resolveTenantSession(req, { store });
+    if (direct !== null)
+        return direct;
+    try {
+        return swapQueryTokenForCookie(req, res, { publicOrigin: config.publicOrigin, store, cookie: { secure: config.cookieSecure } });
+    }
+    catch {
+        return null;
+    }
+}
+/** `GET /` entry resolution. Resolves fresh on every load (R-VIEW-1): no
+ *  session -> no registry/home read at all; session resolves to no home, or a
+ *  home with no `home_agent_target` yet -> still no relay/wake/provider call.
+ *  The redirect target is always the value this process just read from the
+ *  registry — never a client-supplied `?target=`. */
+function respondRoot(req, res, db, config, store) {
+    const session = resolveRootSession(req, res, config, store);
+    if (session === null) {
+        sendText(res, 401, 'hearth session required\n');
+        return;
+    }
+    const home = resolveHome(session.tenant_id, session.user_id, db);
+    if (home === null) {
+        sendText(res, 404, 'home not found\n');
+        return;
+    }
+    const target = home.home_agent_target?.trim() ?? '';
+    if (target === '') {
+        sendText(res, 503, 'home not yet provisioned\n');
+        return;
+    }
+    redirectChat(res, target);
+}
+const DYNAMIC_ROUTES = [
+    { method: 'POST', path: '/__crtr/source', auth: 'write' },
+    { method: 'GET', path: '/__crtr/events', auth: 'read' },
+    { method: 'GET', path: '/__hearth/model-auth/anthropic/status', auth: 'read' },
+    { method: 'POST', path: '/__hearth/model-auth/anthropic/start', auth: 'write' },
+    { method: 'POST', path: '/__hearth/model-auth/anthropic/finish', auth: 'write' },
+];
+const DYNAMIC_ROUTE_PATHS = new Set(DYNAMIC_ROUTES.map((route) => route.path));
+function findDynamicRoute(method, pathname) {
+    return DYNAMIC_ROUTES.find((route) => route.path === pathname && route.method === method);
+}
+/** `GET /` redirects to `/views/<view>?target=...` (review finding #1) but
+ *  that path never reached the relay — it 404'd even for a valid session.
+ *  These two matchers extend the dynamic-lane gate (session+registry, same as
+ *  every other lane above) to the SPA view shell and the static assets it
+ *  loads, so the redirect target is actually servable. This is deliberately
+ *  NOT a public/unauthenticated allowlist (the part-plan does not call for
+ *  one) — every match below still goes through `respondDynamicLane`'s
+ *  session+registry gate before `relay.proxyHttp` is ever invoked. */
+function isViewShellPath(pathname) {
+    return /^\/views\/[^/?#]+$/.test(pathname);
+}
+const STATIC_ASSET_ROOT_PATHS = 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 STATIC_ASSET_EXTENSIONS = new Set(['.css', '.js', '.mjs', '.map', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.json', '.txt']);
+function isStaticAssetPath(pathname) {
+    if (pathname.startsWith('/assets/'))
+        return true;
+    if (STATIC_ASSET_ROOT_PATHS.has(pathname))
+        return true;
+    const match = /^\/[^/?#]+(\.[^/?#]+)$/.exec(pathname);
+    return match !== null && STATIC_ASSET_EXTENSIONS.has(match[1].toLowerCase());
+}
+function isRelayableViewOrAssetPath(pathname) {
+    return isViewShellPath(pathname) || isStaticAssetPath(pathname);
+}
+/** Session+registry gate shared by every dynamic lane. Absent/invalid session
+ *  (or, for `auth: 'write'`, an untrusted Origin) or an unresolved home
+ *  rejects before the relay dispatcher (and therefore before any
+ *  wake/provider/home contact) is ever invoked. */
+async function respondDynamicLane(req, res, db, config, store, relay, auth) {
+    const session = auth === 'write'
+        ? resolveTenantWriteAuth(req, { store, publicOrigin: config.publicOrigin })
+        : resolveTenantSession(req, { store });
+    if (session === null) {
+        sendText(res, 401, 'hearth session required\n');
+        return;
+    }
+    const home = resolveHome(session.tenant_id, session.user_id, db);
+    if (home === null) {
+        sendText(res, 404, 'home not found\n');
+        return;
+    }
+    await relay.proxyHttp(req, res, home);
+}
+async function routeControlPlaneRequest(req, res, db, config, store, relay) {
+    const url = requestUrl(req);
+    if (req.method === 'GET' && url.pathname === '/__hearth/healthz') {
+        respondHealthz(res);
+        return;
+    }
+    if ((req.method === 'GET' || req.method === 'HEAD') && url.pathname === '/') {
+        respondRoot(req, res, db, config, store);
+        return;
+    }
+    // Public webhook ingress lane (`POST /webhook/:routing_key`). Authenticated
+    // ONLY by the per-route HMAC signature verified inside the handler, so it
+    // sits BEFORE — and deliberately outside — the session/registry gate every
+    // dynamic lane below goes through. A wrong method on the webhook path is a
+    // 405, never a fall-through to the relay.
+    if (isWebhookPath(url.pathname)) {
+        if (!isWebhookRequest(req.method, url.pathname)) {
+            sendText(res, 405, 'method not allowed\n');
+            return;
+        }
+        await handleWebhookRequest(req, res);
+        return;
+    }
+    if (DYNAMIC_ROUTE_PATHS.has(url.pathname)) {
+        const route = findDynamicRoute(req.method, url.pathname);
+        if (route === undefined) {
+            sendText(res, 405, 'method not allowed\n');
+            return;
+        }
+        await respondDynamicLane(req, res, db, config, store, relay, route.auth);
+        return;
+    }
+    if ((req.method === 'GET' || req.method === 'HEAD') && isRelayableViewOrAssetPath(url.pathname)) {
+        await respondDynamicLane(req, res, db, config, store, relay, 'read');
+        return;
+    }
+    sendText(res, 404, 'not found\n');
+}
+/** Exact single-segment `/node/<id>` matcher (review finding #3). Rejects an
+ *  empty id, additional path segments/trailing slash, an embedded `/` or `\`
+ *  (pre- or post-decode), `..` traversal, and malformed percent-encoding —
+ *  only a single clean path segment reaches `relay.proxyUpgrade`. Mirrors the
+ *  M0 `extractNodeId` shape (`wake-proxy/proxy.ts`) without the loose
+ *  `startsWith('/node/')` prefix match it replaces. */
+function extractNodeId(pathname) {
+    const match = /^\/node\/([^/]+)$/.exec(pathname);
+    if (match === null)
+        return null;
+    const raw = match[1];
+    if (raw.includes('\\'))
+        return null;
+    let nodeId;
+    try {
+        nodeId = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    if (nodeId === '' || /[/\\]/.test(nodeId) || nodeId.includes('..'))
+        return null;
+    return nodeId;
+}
+/** WS upgrade gate for `/node/<id>`. Uses the same write-capable browser auth
+ *  as write HTTP lanes (`resolveTenantWriteAuth`: trusted-Origin cookie OR
+ *  no-Origin/non-browser Bearer — review finding #3) rather than plain
+ *  `resolveTenantSession`, so a cross-site page cannot ride a victim's cookie
+ *  into the bidirectional `/node/<id>` lane the way a same-site/no-Origin
+ *  WS handshake can. Then mirrors `respondDynamicLane`'s registry gate before
+ *  handing the socket to the relay dispatcher. */
+async function handleUpgrade(req, socket, head, db, config, store, relay) {
+    const url = requestUrl(req);
+    const nodeId = extractNodeId(url.pathname);
+    if (nodeId === null) {
+        socket.destroy();
+        return;
+    }
+    const session = resolveTenantWriteAuth(req, { store, publicOrigin: config.publicOrigin });
+    if (session === null) {
+        socket.destroy();
+        return;
+    }
+    const home = resolveHome(session.tenant_id, session.user_id, db);
+    if (home === null) {
+        socket.destroy();
+        return;
+    }
+    relay.proxyUpgrade(req, socket, head, home);
+}
+function stripReferrerHeaders(req) {
+    delete req.headers.referer;
+    delete req.headers.referrer;
+}
+/** Redact secrets/session material out of a server-side error log line. The
+ *  client never sees this text (see the 500 handler below) — it exists only
+ *  so stderr never carries a raw bearer/cookie/relay-token value. */
+function redactServerErrorMessage(message) {
+    return redactSecrets(tenantSessionAuthRedactedMessage(message));
+}
+/** Log a route/relay failure server-side only. The browser always gets the
+ *  generic 500 body written by the caller — raw exception text (which can
+ *  carry upstream URLs, headers, bearer/session strings, or DB paths once
+ *  P4.3 plugs in the real relay) never reaches the client. */
+function logRequestError(error, req) {
+    const raw = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    const details = {
+        level: 'error',
+        message: 'hearth control plane request failed',
+        method: req.method,
+        path: requestUrl(req).pathname,
+        error: redactServerErrorMessage(raw),
+    };
+    process.stderr.write(`${JSON.stringify(details)}\n`);
+}
+/** Build the CP HTTP+WS server. No registry seeding and no idle timers are
+ *  started here or anywhere reachable from this constructor (master plan
+ *  P4.1 / S3 — the provider owns idle->suspend, not the CP). `deps` lets
+ *  callers inject the db handle, a session store, and a relay dispatcher —
+ *  `main.ts` uses the real env-resolved defaults; tests/smoke checks inject
+ *  fakes for all three without touching global env state. */
+export function createControlPlaneServer(config, deps = {}) {
+    const db = deps.db ?? getControlPlaneDb();
+    const store = deps.sessionStore;
+    const relay = deps.relay ?? notImplementedRelay;
+    const server = createServer((req, res) => {
+        void routeControlPlaneRequest(req, res, db, config, store, relay).catch((error) => {
+            logRequestError(error, req);
+            if (!res.headersSent) {
+                sendText(res, 500, 'internal server error\n');
+            }
+            else {
+                res.destroy();
+            }
+        });
+    });
+    server.prependListener('request', (req, res) => {
+        stripReferrerHeaders(req);
+        if (requestUrl(req).pathname === '/')
+            res.setHeader('Referrer-Policy', 'no-referrer');
+    });
+    server.prependListener('upgrade', (req) => {
+        stripReferrerHeaders(req);
+    });
+    server.on('connect', (_req, socket) => {
+        socket.end('HTTP/1.1 405 Method Not Allowed\r\nConnection: close\r\n\r\n');
+    });
+    server.on('upgrade', (req, socket, head) => {
+        void handleUpgrade(req, socket, head, db, config, store, relay).catch(() => {
+            socket.destroy();
+        });
+    });
+    return server;
+}

package/dist/hearth/control-plane/session.d.ts

@@ -0,0 +1,68 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { TenantSession } from './types.js';
+export declare const HEARTH_SESSION_COOKIE = "hearth_session";
+type AuthSource = 'cookie' | 'bearer' | 'query-swap';
+export interface TenantSessionAuth extends TenantSession {
+    source: AuthSource;
+}
+export interface TenantSessionTokenSeed extends TenantSession {
+    /** Raw cookie/bearer session token. Preferred for dogfood env seeding when
+     *  query-token handoff must set a cookie. If omitted, `token_hash` can still
+     *  validate existing cookies/bearer clients but cannot be emitted into a new
+     *  Set-Cookie header. */
+    token?: string;
+    token_hash?: string;
+    /** Optional one-time M0 handoff token. It is not accepted by
+     *  `resolveTenantSession`; it can only be consumed by
+     *  `swapQueryTokenForCookie`, which requires a trusted Origin and marks the
+     *  query hash spent in this CP process. */
+    query_token?: string;
+    query_token_hash?: string;
+}
+export interface TenantSessionStore {
+    records: readonly NormalizedTenantSessionToken[];
+    consumed_query_token_hashes: Set<string>;
+}
+interface NormalizedTenantSessionToken extends TenantSession {
+    token_hash: string;
+    token: string | null;
+    query_token_hash: string | null;
+}
+export interface SessionCookieOptions {
+    secure?: boolean;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    maxAgeSeconds?: number;
+    path?: string;
+}
+export interface ResolveTenantSessionOptions {
+    store?: TenantSessionStore;
+}
+export interface ResolveTenantWriteAuthOptions extends ResolveTenantSessionOptions {
+    publicOrigin: string;
+}
+export interface QueryTokenSwapOptions extends ResolveTenantWriteAuthOptions {
+    cookie?: SessionCookieOptions;
+}
+export declare function createTenantSessionStore(seeds: readonly TenantSessionTokenSeed[]): TenantSessionStore;
+export declare function loadTenantSessionStore(env?: NodeJS.ProcessEnv): TenantSessionStore;
+export declare function setSessionCookie(res: ServerResponse, token: string, options?: SessionCookieOptions): void;
+export declare function clearSessionCookie(res: ServerResponse, options?: SessionCookieOptions): void;
+/** Validate durable session credentials only: HttpOnly cookie for browsers or
+ *  Bearer for non-browser clients. Query tokens are intentionally ignored here
+ *  so a copied `?token=` URL is never durable authorization. */
+export declare function resolveTenantSession(req: IncomingMessage, options?: ResolveTenantSessionOptions): TenantSessionAuth | null;
+/** State-changing browser lanes require a valid session AND a trusted Origin;
+ *  query tokens are not accepted here. Bearer remains available only to
+ *  non-browser clients (no Origin header). */
+export declare function resolveTenantWriteAuth(req: IncomingMessage, options: ResolveTenantWriteAuthOptions): TenantSessionAuth | null;
+/** Consume an optional M0 handoff `?token=` exactly once and swap it to the
+ *  HttpOnly/Secure/SameSite Hearth session cookie. This is the only query-token
+ *  path. Safe top-level navigations (`GET`/`HEAD`) are permitted without a
+ *  matching `Origin` header (see `originAcceptableForQueryTokenSwap`); any
+ *  other method still requires a trusted Origin, matching the write-lane
+ *  policy. Returns null on replay, invalid token, missing token, or a
+ *  rejected Origin. */
+export declare function swapQueryTokenForCookie(req: IncomingMessage, res: ServerResponse, options: QueryTokenSwapOptions): TenantSessionAuth | null;
+export declare function tenantSessionAuthRedactedMessage(message: string): string;
+export declare function resetTenantSessionStoreCacheForTests(): void;
+export {};