@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/node-message.js

@@ -0,0 +1,98 @@
+// control-plane/node-message.ts — P4.4 lower-level node-message exec primitive.
+//
+// `wakeAndExecNodeMessage(home_id, body, tier)`: `ensureAwake(home_id)`
+// (wake.ts, T3.1) FIRST, then run `crtr node msg --to <home_agent_target>
+// --tier <tier>` in-guest through the P2.6 stdin-capable provider exec seam
+// (`HomeBackend.exec`, provider.ts) — `body` travels on stdin (the `msg`
+// command's body is positional-or-stdin; this primitive always uses stdin),
+// never as a positional argv element, shell-interpolated command string,
+// heredoc, or base64 blob. The ONLY things passed as argv tokens are the
+// static command words, `--to`/`--tier` flags, the resolved
+// `home_agent_target`, and the whitelisted tier — never the body.
+//
+// This is the LOWER-LEVEL primitive only (master plan P4.4): no envelope
+// construction, no ACL, no rate-limit, no audit. Those are P5's
+// `triggers/deliver.ts` chokepoint (P5.3) — it authorizes, audits, and calls
+// THIS primitive with the serialized envelope on stdin. The CP never writes
+// a home's inbox file directly; this primitive (via the in-guest `crtr`
+// CLI's own inbox-append) is the only path to it, and scheduler/ingress must
+// call this — never provider exec directly.
+import { general } from '../../core/errors.js';
+import { loadM0Config } from '../../core/hearth/config.js';
+import { getHomeBackend } from '../../core/hearth/provider.js';
+import { getHomeById } from './registry.js';
+import { ensureAwake } from './wake.js';
+const TIERS = ['critical', 'urgent', 'normal', 'deferred'];
+/** Reject anything outside the whitelist BEFORE any wake/exec is attempted —
+ *  an invalid tier never reaches the provider, let alone a home. */
+function requireTier(tier) {
+    if (TIERS.includes(tier))
+        return tier;
+    throw general(`invalid node-message tier: ${tier}`, { tier, allowed: TIERS });
+}
+function requireHomeField(value, field, home_id) {
+    if (value === null || value === undefined || (typeof value === 'string' && value.trim() === '')) {
+        throw general(`home ${home_id} is missing ${field} — cannot deliver node message`, { home_id, field });
+    }
+    return value;
+}
+/** Indirection seam so a smoke script can fake `ensureAwake`/the registry/the
+ *  provider backend without a real DB/provider (mirrors `wake.ts`'s
+ *  `wakeInternals`). Production code never reassigns these. */
+export const nodeMessageInternals = {
+    ensureAwake,
+    getHomeById,
+    getHomeBackend: (config) => getHomeBackend(config),
+    loadM0Config: () => loadM0Config(),
+};
+function readHome(home_id) {
+    const home = nodeMessageInternals.getHomeById(home_id);
+    if (home === null)
+        throw general(`home not found: ${home_id}`, { home_id });
+    return home;
+}
+/**
+ * Wake `home_id` then deliver `body` to its home agent by running
+ * `crtr node msg --to <home_agent_target> --tier <tier>` in-guest, through
+ * the provider exec stdin seam (P2.6) — `body` is the exec `stdin`, never
+ * part of `argv`/command text.
+ *
+ * Exec happens only AFTER `ensureAwake` resolves (R-TRIG-1), so the in-guest
+ * broker + inbox watcher exist to receive it. `home_agent_target` is read
+ * fresh from the registry both before and after the wake and asserted equal
+ * — a provider recreate during `ensureAwake` may refresh
+ * `provider_sandbox_id`/`preview_endpoint`, but the target node id is stable
+ * across recreate (R-WAKE-6) and this primitive refuses to deliver if that
+ * invariant is ever violated. The sandbox id used for exec is read
+ * POST-wake, since a recreate makes the pre-wake sandbox id stale.
+ */
+export async function wakeAndExecNodeMessage(home_id, body, tier) {
+    const validTier = requireTier(tier);
+    const before = readHome(home_id);
+    const target = requireHomeField(before.home_agent_target, 'home_agent_target', home_id);
+    await nodeMessageInternals.ensureAwake(home_id);
+    const after = readHome(home_id);
+    if (after.home_agent_target !== target) {
+        throw general(`home_agent_target changed during wake for home ${home_id} — refusing to deliver`, {
+            home_id,
+            before: target,
+            after: after.home_agent_target,
+        });
+    }
+    const sandboxId = requireHomeField(after.provider_sandbox_id, 'provider_sandbox_id', home_id);
+    const backend = nodeMessageInternals.getHomeBackend(nodeMessageInternals.loadM0Config());
+    // Static argv only: command words, the `--to`/`--tier` flags, the resolved
+    // target, and the whitelisted tier. `body` is carried on `stdin` — never
+    // appended here.
+    const result = await backend.exec(sandboxId, {
+        argv: ['crtr', 'node', 'msg', '--to', target, '--tier', validTier],
+        stdin: body,
+    });
+    if (result.exitCode !== 0) {
+        throw general(`node-message exec failed for home ${home_id} (exit ${String(result.exitCode)})`, {
+            home_id,
+            exitCode: result.exitCode,
+            stderr: result.stderr,
+        });
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type SchedulerLoopHandle } from './scheduler/scan-loop.js';
+/** True for `POST /webhook/:routing_key` (the only ingress method/shape). A
+ *  non-POST on a `/webhook/*` path is reported by the caller as 405; a
+ *  malformed key is handled as 404 inside `handleWebhook`. */
+export declare function isWebhookRequest(method: string | undefined, pathname: string): boolean;
+/** True when the path is under `/webhook/` regardless of method — lets the CP
+ *  server answer a wrong-method request on the webhook lane with 405 rather
+ *  than falling through to 404. */
+export declare function isWebhookPath(pathname: string): boolean;
+/** Dispatch a webhook request to the ingress handler with production deps. */
+export declare function handleWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Start the cron scan loop. Returns a handle whose `stop()` clears the loop
+ *  timer — call it from CP shutdown. */
+export declare function startSchedulerIngress(): SchedulerLoopHandle;

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

@@ -0,0 +1,34 @@
+// control-plane/register.ts — the single wiring entrypoint for the scheduler +
+// webhook ingress slice (master plan P5.6). The CP `server.ts` and `main.ts`
+// each carry ONE call site into here; this module owns the wiring body.
+//
+// Two seams:
+//   - `isWebhookRequest` / `handleWebhookRequest`: the PUBLIC webhook ingress
+//     lane. It is authenticated ONLY by the per-route HMAC signature (verified
+//     inside `handleWebhook`), so it is mounted OUTSIDE the CP's session/
+//     registry gate — a browser session is neither required nor consulted.
+//   - `startSchedulerIngress`: launches the always-on cron scan loop at CP
+//     startup and returns a stop handle for graceful shutdown.
+import { extractRoutingKey, handleWebhook } from './ingress/webhook-route.js';
+import { startSchedulerLoop } from './scheduler/scan-loop.js';
+/** True for `POST /webhook/:routing_key` (the only ingress method/shape). A
+ *  non-POST on a `/webhook/*` path is reported by the caller as 405; a
+ *  malformed key is handled as 404 inside `handleWebhook`. */
+export function isWebhookRequest(method, pathname) {
+    return method === 'POST' && extractRoutingKey(pathname) !== null;
+}
+/** True when the path is under `/webhook/` regardless of method — lets the CP
+ *  server answer a wrong-method request on the webhook lane with 405 rather
+ *  than falling through to 404. */
+export function isWebhookPath(pathname) {
+    return pathname === '/webhook' || pathname.startsWith('/webhook/');
+}
+/** Dispatch a webhook request to the ingress handler with production deps. */
+export async function handleWebhookRequest(req, res) {
+    await handleWebhook(req, res);
+}
+/** Start the cron scan loop. Returns a handle whose `stop()` clears the loop
+ *  timer — call it from CP shutdown. */
+export function startSchedulerIngress() {
+    return startSchedulerLoop();
+}

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

@@ -0,0 +1,17 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { CreateHomeInput, Home, HomeId, HomePatch, HomeStatus, RefreshProviderPointersInput, ResolvedHome, TenantSession, TouchWakeInput } from './types.js';
+export declare function createHome(input: CreateHomeInput, db?: DatabaseSync): Home;
+export declare function getHomeById(home_id: HomeId | null | undefined, db?: DatabaseSync): Home | null;
+/** Resolve a tenant session to its registry row. A null return is a hard
+ *  auth/404 boundary: callers must turn it into unauthorized/not-found before
+ *  wake or relay. This module intentionally performs a plain row read, so a
+ *  suspended home remains resolvable/readable (R-REG-1). */
+export declare function resolveHome(tenant_id: string, user_id: string, db?: DatabaseSync): ResolvedHome | null;
+export declare function resolveHomeForSession(session: TenantSession | null, db?: DatabaseSync): ResolvedHome | null;
+export declare function getHomeBySandbox(provider_sandbox_id: string | null | undefined, db?: DatabaseSync): Home | null;
+export declare function updateHome(home_id: HomeId, mutate: (current: Home) => HomePatch, db?: DatabaseSync): Home;
+export declare function refreshProviderPointers(home_id: HomeId, pointers: RefreshProviderPointersInput, db?: DatabaseSync): Home;
+export declare function setHomeStatus(home_id: HomeId, status: HomeStatus, db?: DatabaseSync): Home;
+export declare function touchWake(home_id: HomeId, input?: TouchWakeInput, db?: DatabaseSync): Home;
+export declare function touchReady(home_id: HomeId, at?: string, db?: DatabaseSync): Home;
+export declare function touchSuspend(home_id: HomeId, at?: string, db?: DatabaseSync): Home;

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

@@ -0,0 +1,161 @@
+import { general } from '../../core/errors.js';
+import { getControlPlaneDb } from './db.js';
+const HOME_COLUMNS = [
+    'home_id',
+    'tenant_id',
+    'user_id',
+    'provider',
+    'provider_sandbox_id',
+    'provider_volume_id',
+    'preview_endpoint',
+    'home_agent_target',
+    'relay_auth_ref',
+    'status',
+    'template_version',
+    'last_ready_at',
+    'last_wake_at',
+    'last_suspend_at',
+    'last_wake_latency_ms',
+    'health_verdict',
+    'created_at',
+    'updated_at',
+];
+const SELECT_HOME = `SELECT ${HOME_COLUMNS.join(', ')} FROM home`;
+function nowIso() {
+    return new Date().toISOString();
+}
+function nonEmpty(name, value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        throw general(`${name} must not be empty`, { field: name });
+    return trimmed;
+}
+function normalizeCreateHome(input) {
+    const now = nowIso();
+    return {
+        home_id: nonEmpty('home_id', input.home_id),
+        tenant_id: nonEmpty('tenant_id', input.tenant_id),
+        user_id: nonEmpty('user_id', input.user_id),
+        provider: input.provider ?? 'blaxel',
+        provider_sandbox_id: input.provider_sandbox_id ?? null,
+        provider_volume_id: input.provider_volume_id ?? null,
+        preview_endpoint: input.preview_endpoint ?? null,
+        home_agent_target: input.home_agent_target ?? null,
+        relay_auth_ref: input.relay_auth_ref ?? null,
+        status: input.status ?? 'provisioning',
+        template_version: input.template_version ?? null,
+        last_ready_at: input.last_ready_at ?? null,
+        last_wake_at: input.last_wake_at ?? null,
+        last_suspend_at: input.last_suspend_at ?? null,
+        last_wake_latency_ms: input.last_wake_latency_ms ?? null,
+        health_verdict: input.health_verdict ?? 'unknown',
+        created_at: input.created_at ?? now,
+        updated_at: input.updated_at ?? input.created_at ?? now,
+    };
+}
+function mapHome(row) {
+    if (row === undefined || row === null)
+        return null;
+    return row;
+}
+function changedColumns(patch) {
+    return Object.keys(patch).filter((key) => patch[key] !== undefined);
+}
+function runTransaction(db, body) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const value = body();
+        db.exec('COMMIT');
+        return value;
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            // The original error is the useful one; rollback failure only means the
+            // transaction was already closed by SQLite.
+        }
+        throw error;
+    }
+}
+export function createHome(input, db = getControlPlaneDb()) {
+    const home = normalizeCreateHome(input);
+    db.prepare(`
+INSERT INTO home (${HOME_COLUMNS.join(', ')})
+VALUES (${HOME_COLUMNS.map(() => '?').join(', ')})
+`).run(...HOME_COLUMNS.map((column) => home[column]));
+    return home;
+}
+export function getHomeById(home_id, db = getControlPlaneDb()) {
+    if (home_id === null || home_id === undefined || home_id.trim() === '')
+        return null;
+    return mapHome(db.prepare(`${SELECT_HOME} WHERE home_id = ?`).get(home_id));
+}
+/** Resolve a tenant session to its registry row. A null return is a hard
+ *  auth/404 boundary: callers must turn it into unauthorized/not-found before
+ *  wake or relay. This module intentionally performs a plain row read, so a
+ *  suspended home remains resolvable/readable (R-REG-1). */
+export function resolveHome(tenant_id, user_id, db = getControlPlaneDb()) {
+    const tenant = tenant_id.trim();
+    const user = user_id.trim();
+    if (tenant === '' || user === '')
+        return null;
+    return mapHome(db.prepare(`${SELECT_HOME} WHERE tenant_id = ? AND user_id = ?`).get(tenant, user));
+}
+export function resolveHomeForSession(session, db = getControlPlaneDb()) {
+    if (session === null)
+        return null;
+    return resolveHome(session.tenant_id, session.user_id, db);
+}
+export function getHomeBySandbox(provider_sandbox_id, db = getControlPlaneDb()) {
+    if (provider_sandbox_id === null || provider_sandbox_id === undefined || provider_sandbox_id.trim() === '')
+        return null;
+    return mapHome(db.prepare(`${SELECT_HOME} WHERE provider_sandbox_id = ?`).get(provider_sandbox_id));
+}
+export function updateHome(home_id, mutate, db = getControlPlaneDb()) {
+    return runTransaction(db, () => {
+        const current = getHomeById(home_id, db);
+        if (current === null)
+            throw general(`home not found: ${home_id}`, { home_id });
+        const patch = mutate(current);
+        const columns = changedColumns(patch);
+        const updated_at = nowIso();
+        if (columns.length === 0) {
+            db.prepare('UPDATE home SET updated_at = ? WHERE home_id = ?').run(updated_at, home_id);
+            return { ...current, updated_at };
+        }
+        const assignments = columns.map((column) => `${column} = ?`).join(', ');
+        const values = columns.map((column) => {
+            const value = patch[column];
+            if (value === undefined)
+                throw general(`home patch column ${column} was unexpectedly undefined`, { column });
+            return value;
+        });
+        db.prepare(`UPDATE home SET ${assignments}, updated_at = ? WHERE home_id = ?`).run(...values, updated_at, home_id);
+        return getHomeById(home_id, db);
+    });
+}
+export function refreshProviderPointers(home_id, pointers, db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({
+        provider_sandbox_id: pointers.provider_sandbox_id,
+        preview_endpoint: pointers.preview_endpoint,
+        status: pointers.status,
+        template_version: pointers.template_version,
+    }), db);
+}
+export function setHomeStatus(home_id, status, db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({ status }), db);
+}
+export function touchWake(home_id, input = {}, db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({
+        last_wake_at: input.at ?? nowIso(),
+        last_wake_latency_ms: input.latency_ms,
+    }), db);
+}
+export function touchReady(home_id, at = nowIso(), db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({ last_ready_at: at }), db);
+}
+export function touchSuspend(home_id, at = nowIso(), db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({ last_suspend_at: at }), db);
+}

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

@@ -0,0 +1,40 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Socket } from 'node:net';
+import { WebSocket } from 'ws';
+import { type ControlPlaneConfig } from './config.js';
+import { type WakeResult } from './wake.js';
+import type { HomeId, ResolvedHome } from './types.js';
+import type { RelayDispatcher } from './server.js';
+/** 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 declare function buildUpstreamHttpUrl(previewEndpoint: string, rawRequestUrl: string | undefined): URL;
+export interface RelayDeps {
+    ensureAwake?: (home_id: HomeId) => Promise<WakeResult>;
+    resolveRunning?: (home_id: HomeId) => WakeResult | null;
+    invalidateWarmVerdict?: (home_id: HomeId) => void;
+    loadConfig?: () => ControlPlaneConfig;
+}
+/** 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 declare function proxyHttp(req: IncomingMessage, res: ServerResponse, home: ResolvedHome, deps?: RelayDeps): Promise<void>;
+export interface ProxyWebSocketDeps extends RelayDeps {
+    createUpstream?: (url: string, relayToken: string) => WebSocket;
+}
+/** `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 declare function proxyUpgrade(req: IncomingMessage, socket: Socket, head: Buffer, home: ResolvedHome, deps?: ProxyWebSocketDeps): void;
+/** 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 declare const controlPlaneRelay: RelayDispatcher;