@crouton-kit/crouter 0.3.39 → 0.3.41

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

@@ -1,482 +0,0 @@
-// 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 { createHash, timingSafeEqual } from 'node:crypto';
-import { hearthHomeImageRefForVersion } from '../../core/hearth/config.js';
-import { getControlPlaneDb } from './db.js';
-import { resolveHome } from './registry.js';
-import { setHearthTarget } from './hearth-target.js';
-import { resolveTenantSession, resolveTenantWriteAuth, swapQueryTokenForCookie, tenantSessionAuthRedactedMessage } from './session.js';
-import { redactSecrets, resolveCpAdminToken } from './secrets.js';
-import { beginOAuth, endOAuth } from './serving.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');
-}
-const ADMIN_HEARTH_IMAGE_PATH = '/__admin/hearth-image';
-// The auto-upgrade notify body is tiny ({template_version, image_ref}); cap
-// hard so a malformed/oversized POST can't buffer unbounded.
-const ADMIN_BODY_MAX_BYTES = 4 * 1024;
-const STRICT_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
-/** Fixed-length digest of a UTF-8 string — always 32 bytes (sha256), so
- *  comparing two digests never branches on the ORIGINAL strings' lengths. */
-function sha256(value) {
-    return createHash('sha256').update(value, 'utf8').digest();
-}
-/** Constant-time bearer check against the configured CP admin token. Fails
- *  CLOSED: no `Authorization: Bearer` header, or no token configured on the
- *  CP, or a mismatch — all return false without leaking which. Compares
- *  sha256 digests (always 32 bytes each) rather than the raw token buffers,
- *  so there is no length-inequality short-circuit that would leak the
- *  configured token's length before `timingSafeEqual` runs — equal plaintext
- *  still implies equal digest, and every digest is the same size regardless
- *  of what was presented. */
-function isAdminAuthorized(req) {
-    const configured = resolveCpAdminToken();
-    if (configured === null || configured === '')
-        return false;
-    const header = req.headers.authorization;
-    if (typeof header !== 'string')
-        return false;
-    const match = /^Bearer[ ]+(.+)$/.exec(header.trim());
-    if (match === null)
-        return false;
-    return timingSafeEqual(sha256(match[1]), sha256(configured));
-}
-function readRequestBody(req, maxBytes) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let total = 0;
-        let tooLarge = false;
-        req.on('data', (chunk) => {
-            total += chunk.length;
-            if (total > maxBytes) {
-                tooLarge = true;
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => resolve({ body: Buffer.concat(chunks), tooLarge }));
-        req.on('error', (error) => {
-            if (tooLarge) {
-                resolve({ body: Buffer.alloc(0), tooLarge: true });
-                return;
-            }
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
-}
-/** `POST /__admin/hearth-image` — the image-build workflow's push-notify
- *  (design §2-C). Bearer-authed against the CP admin token (constant-time),
- *  BEFORE and outside the session/registry gate (it is a machine ingress, not
- *  a browser lane). Validates the body is strict semver + `image_ref ===
- *  hearthHomeImageRefForVersion(template_version)` (the notify cannot register
- *  an image name that doesn't match its version), then idempotently upserts
- *  the single global target row — a re-post of the same version is a no-op. It
- *  never contacts a home; the actual roll happens lazily on each home's next
- *  wake (wake.ts). */
-async function respondAdminHearthImage(req, res, db) {
-    if (!isAdminAuthorized(req)) {
-        sendText(res, 401, 'admin authorization required\n');
-        return;
-    }
-    const { body, tooLarge } = await readRequestBody(req, ADMIN_BODY_MAX_BYTES);
-    if (tooLarge) {
-        sendText(res, 413, 'request body too large\n');
-        return;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(body.toString('utf8'));
-    }
-    catch {
-        sendText(res, 400, 'body must be valid JSON\n');
-        return;
-    }
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        sendText(res, 400, 'body must be a JSON object with template_version and image_ref\n');
-        return;
-    }
-    const record = parsed;
-    const templateVersion = typeof record.template_version === 'string' ? record.template_version.trim() : '';
-    const imageRef = typeof record.image_ref === 'string' ? record.image_ref.trim() : '';
-    if (!STRICT_SEMVER_RE.test(templateVersion)) {
-        sendText(res, 400, 'template_version must be strict semver (X.Y.Z)\n');
-        return;
-    }
-    const expectedImageRef = hearthHomeImageRefForVersion(templateVersion);
-    if (imageRef !== expectedImageRef) {
-        sendText(res, 400, `image_ref must equal ${expectedImageRef} for template_version ${templateVersion}\n`);
-        return;
-    }
-    const target = setHearthTarget({ target_template_version: templateVersion, target_image_ref: imageRef, source: 'image-workflow' }, db);
-    sendText(res, 200, `hearth target = ${target.target_template_version} (${target.target_image_ref})\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 MODEL_AUTH_START_PATH = '/__hearth/model-auth/anthropic/start';
-const MODEL_AUTH_FINISH_PATH = '/__hearth/model-auth/anthropic/finish';
-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: MODEL_AUTH_START_PATH, auth: 'write' },
-    { method: 'POST', path: MODEL_AUTH_FINISH_PATH, 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. */
-/** OAuth-in-progress marker: the CP's own proxied `start`/`finish` dispatch
- *  is the seam — mark a window open the moment a
- *  `start` is about to be proxied (regardless of what the guest does with
- *  it), close it once the `finish` proxy call resolves (success OR failure;
- *  a failed finish still ends the CP-visible window — the bounded TTL in
- *  `serving.ts` is the backstop for a `start` that never gets a `finish` at
- *  all, e.g. an abandoned browser tab). */
-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;
-    }
-    const pathname = requestUrl(req).pathname;
-    const isOAuthStart = pathname === MODEL_AUTH_START_PATH;
-    const isOAuthFinish = pathname === MODEL_AUTH_FINISH_PATH;
-    if (isOAuthStart)
-        beginOAuth(home.home_id);
-    try {
-        await relay.proxyHttp(req, res, home);
-    }
-    finally {
-        if (isOAuthFinish)
-            endOAuth(home.home_id);
-    }
-}
-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;
-    }
-    // Admin push-notify lane. Authenticated by the CP admin bearer token inside
-    // the handler, so — like the webhook lane — it sits BEFORE and outside the
-    // session/registry gate. A wrong method on the admin path is a 405, never a
-    // fall-through to the relay.
-    if (url.pathname === ADMIN_HEARTH_IMAGE_PATH) {
-        if (req.method !== 'POST') {
-            sendText(res, 405, 'method not allowed\n');
-            return;
-        }
-        await respondAdminHearthImage(req, res, db);
-        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/serving.d.ts

@@ -1,15 +0,0 @@
-import type { HomeId } from './types.js';
-export declare function beginHttp(id: HomeId): void;
-export declare function endHttp(id: HomeId): void;
-export declare function beginWs(id: HomeId): void;
-export declare function endWs(id: HomeId): void;
-export declare function beginOAuth(id: HomeId): void;
-export declare function endOAuth(id: HomeId): void;
-/** Is `id` currently serving — any active relay HTTP request, any open relay
- *  WebSocket bridge, or a live (non-stale) OAuth start->finish window? This is
- *  the ONLY signal `wake.ts`'s `homeIsServing` consults — it does not depend
- *  on `resolveRunning`/`WARM_VERDICT_TTL_MS` at all. */
-export declare function isHomeServing(id: HomeId): boolean;
-/** Test/smoke-script hygiene only — production never needs this (one CP
- *  process, S2, and every counter self-clears on its own end/dec path). */
-export declare function resetServingForTests(): void;

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

@@ -1,106 +0,0 @@
-// control-plane/serving.ts — CP-layer active-session tracker, independent of
-// the wake path's warm-verdict TTL.
-//
-// `wake.ts`'s `resolveRunning`/`WARM_VERDICT_TTL_MS` answers "did we recently
-// confirm this home is up" for exactly 10s — a cheap fast-path cache, not a
-// live-session signal. A destructive roll must never fire while a home has
-// an open browser/broker WebSocket, an in-flight HTTP request, or an open
-// OAuth start->finish window, no matter how long that session has been
-// running (design §3's "no active turn / no in-flight OAuth" safety
-// invariant).
-//
-// Three independent live-count maps, keyed by HomeId, are bumped directly at
-// the relay's HTTP/WS lifecycle seams and at the CP's OAuth start/finish
-// dispatch — NOT derived from any cache/TTL. A home is "serving" whenever
-// any one of them is non-zero. Single CP process (S2), in-process only, no
-// persistence — a CP restart naturally drops to zero, which is correct (a
-// fresh process has no in-flight anything).
-const httpInflight = new Map();
-const wsOpen = new Map();
-const oauthInProgress = new Map();
-// Timestamp of the most recent `beginOAuth` call for this home — the TTL
-// clock for the bounded-safety rule below. Refreshed on every `beginOAuth`,
-// so each new `start` gets its own full TTL window regardless of how stale
-// an earlier, still-uncompleted start's marker had become. Cleared once the
-// counter returns to 0 (no window is open, nothing to bound).
-const oauthStartedAt = new Map();
-// Bounded safety — "do not let a dropped OAuth pin a home un-rollable
-// forever": a `start` with no matching `finish` (browser tab closed
-// mid-flow, network drop, abandoned auth) must not hold `isHomeServing` true
-// indefinitely. Chose a TTL over a "clear on idle" scheme because idle here
-// has no other natural signal to key off (no heartbeat on the OAuth lane)
-// and a TTL is simplest to reason about / test. 5 minutes is generous for a
-// real human completing an OAuth redirect+approve+callback round trip (the
-// M0 in-guest flow is a single localhost redirect, seconds in the happy
-// path) while still bounding the worst case to a single-digit-minutes window
-// rather than forever.
-const OAUTH_MARKER_TTL_MS = 5 * 60_000;
-function inc(map, id) {
-    map.set(id, (map.get(id) ?? 0) + 1);
-}
-function dec(map, id) {
-    const current = map.get(id) ?? 0;
-    const next = current - 1;
-    if (next <= 0) {
-        map.delete(id);
-    }
-    else {
-        map.set(id, next);
-    }
-}
-export function beginHttp(id) {
-    inc(httpInflight, id);
-}
-export function endHttp(id) {
-    dec(httpInflight, id);
-}
-export function beginWs(id) {
-    inc(wsOpen, id);
-}
-export function endWs(id) {
-    dec(wsOpen, id);
-}
-export function beginOAuth(id) {
-    // Every real OAuth `start` is a fresh auth window and earns its own full
-    // TTL, not just the first one since the counter hit 0 — otherwise a stale,
-    // abandoned start's marker would age out from under a brand-new retry that
-    // shares its counter, letting that retry's own wake see `!isHomeServing`.
-    oauthStartedAt.set(id, Date.now());
-    inc(oauthInProgress, id);
-}
-export function endOAuth(id) {
-    dec(oauthInProgress, id);
-    if ((oauthInProgress.get(id) ?? 0) === 0)
-        oauthStartedAt.delete(id);
-}
-/** Is an OAuth window open for `id` right now, per the counter, and still
- *  within the bounded-safety TTL of the MOST RECENT `beginOAuth`? A marker
- *  past TTL is treated as stale (does NOT count as serving) so a dropped
- *  `start` can't pin a home un-rollable forever; the counter itself is left
- *  alone (an eventual late `finish` still decrements it correctly, and `dec`
- *  floors at 0 regardless), and a later `beginOAuth` on the same counter
- *  refreshes the timestamp so its own window is judged live. */
-function oauthMarkerLive(id) {
-    const count = oauthInProgress.get(id) ?? 0;
-    if (count <= 0)
-        return false;
-    const startedAt = oauthStartedAt.get(id);
-    if (startedAt === undefined)
-        return true; // defensive: count>0 with no timestamp — treat as live
-    return Date.now() - startedAt < OAUTH_MARKER_TTL_MS;
-}
-/** Is `id` currently serving — any active relay HTTP request, any open relay
- *  WebSocket bridge, or a live (non-stale) OAuth start->finish window? This is
- *  the ONLY signal `wake.ts`'s `homeIsServing` consults — it does not depend
- *  on `resolveRunning`/`WARM_VERDICT_TTL_MS` at all. */
-export function isHomeServing(id) {
-    return (httpInflight.get(id) ?? 0) > 0 || (wsOpen.get(id) ?? 0) > 0 || oauthMarkerLive(id);
-}
-/** Test/smoke-script hygiene only — production never needs this (one CP
- *  process, S2, and every counter self-clears on its own end/dec path). */
-export function resetServingForTests() {
-    httpInflight.clear();
-    wsOpen.clear();
-    oauthInProgress.clear();
-    oauthStartedAt.clear();
-}

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

@@ -1,68 +0,0 @@
-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 {};