@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/ingress/route-store.js

@@ -0,0 +1,61 @@
+import { randomUUID } from 'node:crypto';
+import { getControlPlaneDb } from '../db.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function homeIdentity(homeId) {
+    const row = getControlPlaneDb().prepare('SELECT tenant_id, user_id FROM home WHERE home_id = ?').get(homeId);
+    if (row === undefined)
+        throw new Error(`home not found: ${homeId}`);
+    return row;
+}
+function routeFrom(row) {
+    return {
+        route_id: row['route_id'],
+        tenant_id: row['tenant_id'],
+        user_id: row['user_id'],
+        home_id: row['home_id'],
+        channel: row['channel'],
+        routing_key: row['routing_key'],
+        routing_key_kind: row['routing_key_kind'],
+        channel_secret_ref: row['channel_secret_ref'] ?? null,
+        delivery_template: JSON.parse(row['delivery_template']),
+        enabled: Number(row['enabled']) !== 0,
+        created_at: row['created_at'],
+        updated_at: row['updated_at'],
+    };
+}
+export function registerRoute(input) {
+    const routeId = input.route_id ?? `route-${randomUUID()}`;
+    const stamped = input.now ?? nowIso();
+    const identity = homeIdentity(input.home_id);
+    getControlPlaneDb()
+        .prepare(`INSERT INTO ingress_route (
+         route_id, tenant_id, user_id, home_id, channel, routing_key,
+         routing_key_kind, channel_secret_ref, delivery_template, enabled,
+         created_at, updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(routeId, identity.tenant_id, identity.user_id, input.home_id, input.channel, input.routing_key, input.routing_key_kind, input.channel_secret_ref ?? null, JSON.stringify(input.delivery_template), input.enabled === false ? 0 : 1, stamped, stamped);
+    return getRouteById(routeId);
+}
+export function getRouteById(routeId) {
+    const row = getControlPlaneDb().prepare('SELECT * FROM ingress_route WHERE route_id = ?').get(routeId);
+    return row === undefined ? null : routeFrom(row);
+}
+export function resolveRoute(channel, routingKey) {
+    const row = getControlPlaneDb()
+        .prepare('SELECT * FROM ingress_route WHERE channel = ? AND routing_key = ? AND enabled = 1')
+        .get(channel, routingKey);
+    return row === undefined ? null : routeFrom(row);
+}
+export function listRoutesForUser(tenantId, userId) {
+    const rows = getControlPlaneDb()
+        .prepare('SELECT * FROM ingress_route WHERE tenant_id = ? AND user_id = ? ORDER BY channel, routing_key')
+        .all(tenantId, userId);
+    return rows.map(routeFrom);
+}
+export function setRouteEnabled(routeId, enabled, now = nowIso()) {
+    getControlPlaneDb()
+        .prepare('UPDATE ingress_route SET enabled = ?, updated_at = ? WHERE route_id = ?')
+        .run(enabled ? 1 : 0, now, routeId);
+}

package/dist/hearth/control-plane/ingress/webhook-delivery-store.d.ts

@@ -0,0 +1,41 @@
+export type WebhookDeliveryState = 'received' | 'delivered' | 'rejected' | 'failed';
+export interface WebhookDeliveryRow {
+    delivery_id: string;
+    route_id: string;
+    tenant_id: string;
+    user_id: string;
+    home_id: string;
+    replay_key: string;
+    replay_window_start: string;
+    payload_sha256: string | null;
+    signature_sha256: string | null;
+    state: WebhookDeliveryState;
+    received_at: string;
+    delivered_at: string | null;
+    last_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ClaimWebhookDeliveryInput {
+    delivery_id?: string;
+    route_id: string;
+    replay_key: string;
+    replay_window_start: string;
+    payload_sha256?: string | null;
+    signature_sha256?: string | null;
+    received_at?: string;
+    now?: string;
+}
+export interface ClaimWebhookDeliveryResult {
+    delivery: WebhookDeliveryRow;
+    claimed: boolean;
+}
+export interface SetWebhookDeliveryStateOptions {
+    delivered_at?: string | null;
+    last_error?: string | null;
+    now?: string;
+}
+export declare function claimWebhookDelivery(input: ClaimWebhookDeliveryInput): ClaimWebhookDeliveryResult;
+export declare function getWebhookDeliveryById(deliveryId: string): WebhookDeliveryRow | null;
+export declare function getWebhookDeliveryByReplayKey(routeId: string, replayKey: string, replayWindowStart: string): WebhookDeliveryRow | null;
+export declare function setWebhookDeliveryState(deliveryId: string, state: WebhookDeliveryState, options?: SetWebhookDeliveryStateOptions): void;

package/dist/hearth/control-plane/ingress/webhook-delivery-store.js

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+import { getControlPlaneDb } from '../db.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function routeIdentity(routeId) {
+    const row = getControlPlaneDb()
+        .prepare('SELECT home_id, tenant_id, user_id FROM ingress_route WHERE route_id = ?')
+        .get(routeId);
+    if (row === undefined)
+        throw new Error(`ingress route not found: ${routeId}`);
+    return row;
+}
+function deliveryFrom(row) {
+    return {
+        delivery_id: row['delivery_id'],
+        route_id: row['route_id'],
+        tenant_id: row['tenant_id'],
+        user_id: row['user_id'],
+        home_id: row['home_id'],
+        replay_key: row['replay_key'],
+        replay_window_start: row['replay_window_start'],
+        payload_sha256: row['payload_sha256'] ?? null,
+        signature_sha256: row['signature_sha256'] ?? null,
+        state: row['state'],
+        received_at: row['received_at'],
+        delivered_at: row['delivered_at'] ?? null,
+        last_error: row['last_error'] ?? null,
+        created_at: row['created_at'],
+        updated_at: row['updated_at'],
+    };
+}
+export function claimWebhookDelivery(input) {
+    const deliveryId = input.delivery_id ?? `whdel-${randomUUID()}`;
+    const stamped = input.now ?? nowIso();
+    const receivedAt = input.received_at ?? stamped;
+    const identity = routeIdentity(input.route_id);
+    const result = getControlPlaneDb()
+        .prepare(`INSERT OR IGNORE INTO webhook_delivery (
+         delivery_id, route_id, tenant_id, user_id, home_id, replay_key,
+         replay_window_start, payload_sha256, signature_sha256, state,
+         received_at, delivered_at, last_error, created_at, updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'received', ?, NULL, NULL, ?, ?)`)
+        .run(deliveryId, input.route_id, identity.tenant_id, identity.user_id, identity.home_id, input.replay_key, input.replay_window_start, input.payload_sha256 ?? null, input.signature_sha256 ?? null, receivedAt, stamped, stamped);
+    const delivery = getWebhookDeliveryByReplayKey(input.route_id, input.replay_key, input.replay_window_start);
+    if (delivery === null) {
+        throw new Error(`failed to claim webhook delivery for route ${input.route_id} replay key ${input.replay_key}`);
+    }
+    return { delivery, claimed: result.changes === 1 };
+}
+export function getWebhookDeliveryById(deliveryId) {
+    const row = getControlPlaneDb().prepare('SELECT * FROM webhook_delivery WHERE delivery_id = ?').get(deliveryId);
+    return row === undefined ? null : deliveryFrom(row);
+}
+export function getWebhookDeliveryByReplayKey(routeId, replayKey, replayWindowStart) {
+    const row = getControlPlaneDb()
+        .prepare('SELECT * FROM webhook_delivery WHERE route_id = ? AND replay_key = ? AND replay_window_start = ?')
+        .get(routeId, replayKey, replayWindowStart);
+    return row === undefined ? null : deliveryFrom(row);
+}
+export function setWebhookDeliveryState(deliveryId, state, options = {}) {
+    const stamped = options.now ?? nowIso();
+    const deliveredAt = options.delivered_at === undefined ? (state === 'delivered' ? stamped : null) : options.delivered_at;
+    getControlPlaneDb()
+        .prepare(`UPDATE webhook_delivery
+       SET state = ?, delivered_at = COALESCE(?, delivered_at), last_error = ?, updated_at = ?
+       WHERE delivery_id = ?`)
+        .run(state, deliveredAt, options.last_error ?? null, stamped, deliveryId);
+}

package/dist/hearth/control-plane/ingress/webhook-route.d.ts

@@ -0,0 +1,55 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { buildTriggerEnvelope } from '../triggers/envelope.js';
+import { type DeliverTriggerResult } from '../triggers/deliver.js';
+import { type IngressRouteRow } from './route-store.js';
+import { claimWebhookDelivery, setWebhookDeliveryState } from './webhook-delivery-store.js';
+import { type RateCheckResult } from './rate-limit.js';
+export interface WebhookProcessDeps {
+    checkRate: (key: string) => RateCheckResult;
+    resolveRoute: (channel: 'webhook', routingKey: string) => IngressRouteRow | null;
+    resolveSecret: (ref: string) => string;
+    claimWebhookDelivery: typeof claimWebhookDelivery;
+    setWebhookDeliveryState: typeof setWebhookDeliveryState;
+    deliverTrigger: (input: {
+        home_id: string;
+        source_ref: string;
+        envelope: ReturnType<typeof buildTriggerEnvelope>;
+        tier: 'urgent';
+        payload_sha256?: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<DeliverTriggerResult>;
+    now: () => Date;
+}
+export interface WebhookRequest {
+    routingKey: string;
+    rawBody: Buffer;
+    signatureHeader: string | null;
+    deliveryIdHeader: string | null;
+    contentType: string | null;
+}
+export interface WebhookResult {
+    status: number;
+    message: string;
+    retryAfterMs?: number;
+}
+/** Production defaults — real rate limiter, stores, secret resolver, and
+ *  delivery chokepoint. Tests inject fakes. */
+export declare function defaultWebhookProcessDeps(): WebhookProcessDeps;
+/**
+ * The verification + delivery core, independent of HTTP plumbing so the
+ * security invariants (signature, replay, no-routing-key) are directly
+ * testable. Returns the status + message the HTTP layer writes back.
+ */
+export declare function processWebhookDelivery(req: WebhookRequest, deps: WebhookProcessDeps): Promise<WebhookResult>;
+/** Extract the single `routing_key` path segment from `/webhook/<key>`.
+ *  Rejects an empty key, extra segments, embedded slash/backslash, or
+ *  malformed percent-encoding. */
+export declare function extractRoutingKey(pathname: string): string | null;
+/**
+ * HTTP handler for `POST /webhook/:routing_key`. Reads the raw body (bounded),
+ * extracts the routing key + signature/delivery headers, runs
+ * `processWebhookDelivery`, and writes the resulting status. This is a PUBLIC
+ * endpoint — its only authentication is the per-route HMAC signature, so it
+ * must be mounted OUTSIDE the session/registry gate.
+ */
+export declare function handleWebhook(req: IncomingMessage, res: ServerResponse, deps?: WebhookProcessDeps): Promise<void>;

package/dist/hearth/control-plane/ingress/webhook-route.js

@@ -0,0 +1,285 @@
+// control-plane/ingress/webhook-route.ts — the generic webhook ingress
+// endpoint (master plan P5.5 / part-plan T-C3): `POST /webhook/:routing_key`.
+// The ONLY ingress channel mounted this increment (SMS/email/chat/persistent-
+// socket connectors are out of scope).
+//
+// Order of operations (security-load-bearing):
+//   1. PRE-RESOLUTION rate limit on the routing key — a flood is shed before
+//      any DB lookup / secret resolution / write.
+//   2. Route lookup (`resolveRoute('webhook', key)`) — unknown key → 404, no
+//      delivery.
+//   3. HMAC-SHA256 over the RAW request body using the route's resolved
+//      signing secret (`channel_secret_ref` → `resolveSecret`), constant-time
+//      compared. The secret is DISTINCT from the routing key (the key is
+//      public/demux-only). Missing/invalid signature → reject, no delivery.
+//      A bad signature never writes a `webhook_delivery` row (no amplification).
+//   4. Replay/idempotency via `webhook_delivery` (unique per route + replay
+//      key + window). A duplicate is acknowledged idempotently and NOT
+//      re-delivered.
+//   5. Build the trigger envelope — `trigger_id` is route-derived + per-
+//      delivery (`<route_id>:<replay_key>`) for stable home-side dedupe. The
+//      ROUTING KEY IS NEVER PLACED IN THE ENVELOPE (R-ING-3).
+//   6. Deliver through the shared `deliverTrigger` chokepoint at tier
+//      `urgent` (R-TRIG-3) — which authorizes, wakes, exec's in-guest, audits.
+//
+// The raw public body is never persisted: `webhook_delivery`/`trigger_audit`
+// carry only content hashes + bounded metadata.
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { buildTriggerEnvelope } from '../triggers/envelope.js';
+import { deliverTrigger } from '../triggers/deliver.js';
+import { resolveSecret } from '../secrets.js';
+import { resolveRoute } from './route-store.js';
+import { claimWebhookDelivery, setWebhookDeliveryState, } from './webhook-delivery-store.js';
+import { createRateLimiter, loadRateLimiterConfig } from './rate-limit.js';
+const ENV = {
+    maxBodyBytes: 'CRTR_HEARTH_CP_WEBHOOK_MAX_BODY_BYTES',
+};
+const DEFAULT_MAX_BODY_BYTES = 1_048_576; // 1 MiB
+/** Canonical signing header (hex HMAC-SHA256 of the raw body). The GitHub-
+ *  style `x-hub-signature-256: sha256=<hex>` header is also accepted for
+ *  compatibility; both are verified identically against the raw body. */
+const SIGNATURE_HEADERS = ['x-hearth-signature-256', 'x-hub-signature-256', 'x-signature-256'];
+const DELIVERY_ID_HEADERS = ['x-hearth-delivery-id', 'x-idempotency-key', 'x-github-delivery'];
+const sharedRateLimiter = createRateLimiter(loadRateLimiterConfig());
+/** Production defaults — real rate limiter, stores, secret resolver, and
+ *  delivery chokepoint. Tests inject fakes. */
+export function defaultWebhookProcessDeps() {
+    return {
+        checkRate: (key) => sharedRateLimiter.checkRate(key),
+        resolveRoute: (channel, routingKey) => resolveRoute(channel, routingKey),
+        resolveSecret,
+        claimWebhookDelivery,
+        setWebhookDeliveryState,
+        deliverTrigger: (input) => deliverTrigger(input),
+        now: () => new Date(),
+    };
+}
+/** Coarse hour bucket bounding the replay table + defining the replay window. */
+function replayWindowStart(now) {
+    const bucket = new Date(now.getTime());
+    bucket.setUTCMinutes(0, 0, 0);
+    return bucket.toISOString();
+}
+/** Strip an optional `sha256=` prefix and normalize to lowercase hex. */
+function normalizeSignature(raw) {
+    const trimmed = raw.trim();
+    const eq = trimmed.indexOf('=');
+    const value = trimmed.slice(0, eq).toLowerCase() === 'sha256' ? trimmed.slice(eq + 1) : trimmed;
+    return value.trim().toLowerCase();
+}
+/** Constant-time HMAC-SHA256 verification over the raw body. Returns false on
+ *  any malformed/absent signature or length mismatch — never throws. */
+function verifySignature(secret, rawBody, signatureHeader) {
+    if (signatureHeader === null || signatureHeader.trim() === '')
+        return false;
+    const provided = normalizeSignature(signatureHeader);
+    if (!/^[0-9a-f]+$/.test(provided) || provided.length % 2 !== 0)
+        return false;
+    const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+    const providedBuf = Buffer.from(provided, 'hex');
+    const expectedBuf = Buffer.from(expected, 'hex');
+    if (providedBuf.length !== expectedBuf.length)
+        return false;
+    return timingSafeEqual(providedBuf, expectedBuf);
+}
+function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/** Parse the untrusted body into the envelope payload. JSON when the content
+ *  type is JSON and it parses; otherwise the raw UTF-8 string. Malformed JSON
+ *  is delivered as the raw string rather than rejected — payload is untrusted
+ *  data the home narrows defensively, not something ingress validates. */
+function parsePayload(rawBody, contentType) {
+    const text = rawBody.toString('utf8');
+    if (contentType !== null && /application\/(?:[\w.+-]+\+)?json/i.test(contentType)) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/**
+ * The verification + delivery core, independent of HTTP plumbing so the
+ * security invariants (signature, replay, no-routing-key) are directly
+ * testable. Returns the status + message the HTTP layer writes back.
+ */
+export async function processWebhookDelivery(req, deps) {
+    // 1. Pre-resolution rate limit.
+    const rate = deps.checkRate(req.routingKey);
+    if (!rate.ok) {
+        return { status: 429, message: 'rate limited', retryAfterMs: rate.retryAfterMs };
+    }
+    // 2. Route lookup.
+    const route = deps.resolveRoute('webhook', req.routingKey);
+    if (route === null || route.channel !== 'webhook') {
+        return { status: 404, message: 'unknown webhook route' };
+    }
+    // 3. Signature verification over the raw body. A route with no signing
+    //    secret cannot be verified and is treated as unverifiable — no delivery.
+    if (route.channel_secret_ref === null || route.channel_secret_ref.trim() === '') {
+        return { status: 503, message: 'webhook route not verifiable' };
+    }
+    let secret;
+    try {
+        secret = deps.resolveSecret(route.channel_secret_ref);
+    }
+    catch {
+        return { status: 503, message: 'webhook route not verifiable' };
+    }
+    if (!verifySignature(secret, req.rawBody, req.signatureHeader)) {
+        return { status: 401, message: 'invalid signature' };
+    }
+    // 4. Replay / idempotency. A bad signature never reached here, so no
+    //    delivery row is ever written for an unverified request.
+    const now = deps.now();
+    const payloadSha256 = sha256Hex(req.rawBody);
+    const signatureSha256 = req.signatureHeader === null ? null : sha256Hex(req.signatureHeader);
+    const replayKey = req.deliveryIdHeader !== null && req.deliveryIdHeader.trim() !== '' ? req.deliveryIdHeader.trim() : payloadSha256;
+    const windowStart = replayWindowStart(now);
+    const claim = deps.claimWebhookDelivery({
+        route_id: route.route_id,
+        replay_key: replayKey,
+        replay_window_start: windowStart,
+        payload_sha256: payloadSha256,
+        signature_sha256: signatureSha256,
+        received_at: now.toISOString(),
+    });
+    if (!claim.claimed) {
+        return { status: 200, message: 'duplicate delivery ignored' };
+    }
+    // 5. Envelope — routing key deliberately absent (R-ING-3); trigger_id is
+    //    route-derived + per-delivery for stable home-side dedupe.
+    const envelope = buildTriggerEnvelope({
+        source: 'webhook',
+        trigger_id: `${route.route_id}:${replayKey}`,
+        payload: parsePayload(req.rawBody, req.contentType),
+        received_at: now.toISOString(),
+    });
+    // 6. Deliver through the shared chokepoint (authorize + wake + exec + audit).
+    const outcome = await deps.deliverTrigger({
+        home_id: route.home_id,
+        source_ref: route.route_id,
+        envelope,
+        tier: 'urgent',
+        payload_sha256: payloadSha256,
+        metadata: { byte_length: req.rawBody.length, content_type: req.contentType },
+    });
+    if (outcome.outcome === 'delivered') {
+        deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'delivered');
+        return { status: 202, message: 'delivered' };
+    }
+    if (outcome.outcome === 'rejected') {
+        deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'rejected', { last_error: outcome.reason ?? 'rejected' });
+        return { status: 403, message: 'delivery rejected' };
+    }
+    deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'failed', { last_error: outcome.reason ?? 'failed' });
+    return { status: 502, message: 'delivery failed' };
+}
+/** Extract the single `routing_key` path segment from `/webhook/<key>`.
+ *  Rejects an empty key, extra segments, embedded slash/backslash, or
+ *  malformed percent-encoding. */
+export function extractRoutingKey(pathname) {
+    const match = /^\/webhook\/([^/]+)$/.exec(pathname);
+    if (match === null)
+        return null;
+    const raw = match[1];
+    if (raw.includes('\\'))
+        return null;
+    let key;
+    try {
+        key = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    if (key === '' || /[/\\]/.test(key))
+        return null;
+    return key;
+}
+function firstHeader(req, names) {
+    for (const name of names) {
+        const value = req.headers[name];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+        if (Array.isArray(value) && value.length > 0 && value[0].trim() !== '')
+            return value[0];
+    }
+    return null;
+}
+function readBody(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)));
+        });
+    });
+}
+function maxBodyBytes(env = process.env) {
+    const raw = env[ENV.maxBodyBytes]?.trim();
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_BODY_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return DEFAULT_MAX_BODY_BYTES;
+    return parsed;
+}
+function sendText(res, status, message, retryAfterMs) {
+    const headers = {
+        'content-type': 'text/plain; charset=utf-8',
+        'cache-control': 'no-store',
+        'referrer-policy': 'no-referrer',
+    };
+    if (retryAfterMs !== undefined)
+        headers['retry-after'] = String(Math.ceil(retryAfterMs / 1000));
+    const body = `${message}\n`;
+    headers['content-length'] = String(Buffer.byteLength(body));
+    res.writeHead(status, headers);
+    res.end(body);
+}
+/**
+ * HTTP handler for `POST /webhook/:routing_key`. Reads the raw body (bounded),
+ * extracts the routing key + signature/delivery headers, runs
+ * `processWebhookDelivery`, and writes the resulting status. This is a PUBLIC
+ * endpoint — its only authentication is the per-route HMAC signature, so it
+ * must be mounted OUTSIDE the session/registry gate.
+ */
+export async function handleWebhook(req, res, deps = defaultWebhookProcessDeps()) {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    const routingKey = extractRoutingKey(url.pathname);
+    if (routingKey === null) {
+        sendText(res, 404, 'unknown webhook route');
+        return;
+    }
+    const { body, tooLarge } = await readBody(req, maxBodyBytes());
+    if (tooLarge) {
+        sendText(res, 413, 'payload too large');
+        return;
+    }
+    const result = await processWebhookDelivery({
+        routingKey,
+        rawBody: body,
+        signatureHeader: firstHeader(req, SIGNATURE_HEADERS),
+        deliveryIdHeader: firstHeader(req, DELIVERY_ID_HEADERS),
+        contentType: firstHeader(req, ['content-type']),
+    }, deps);
+    sendText(res, result.status, result.message, result.retryAfterMs);
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,88 @@
+// control-plane/main.ts — the CP process entrypoint. Generalizes the
+// wake-proxy's main.ts startup shape (load config, build server, install
+// signal handling, listen) onto the CP modules: config.ts, db.ts (open +
+// migrate, never seed), and server.ts. Run via the `hearth:control-plane`
+// package script.
+import { general } from '../../core/errors.js';
+import { loadControlPlaneConfig } from './config.js';
+import { getControlPlaneDb } from './db.js';
+import { redactSecrets } from './secrets.js';
+import { tenantSessionAuthRedactedMessage } from './session.js';
+import { createControlPlaneServer } from './server.js';
+import { controlPlaneRelay } from './relay.js';
+import { startSchedulerIngress } from './register.js';
+function redact(message) {
+    return redactSecrets(tenantSessionAuthRedactedMessage(message));
+}
+function log(level, message, details = {}) {
+    process.stderr.write(`${JSON.stringify({ level, message, details })}\n`);
+}
+async function shutdown(server, scheduler, signal) {
+    log('info', 'hearth control plane shutting down', { signal });
+    scheduler.stop();
+    server.closeIdleConnections?.();
+    server.closeAllConnections?.();
+    await new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+    process.exit(0);
+}
+async function main() {
+    const config = loadControlPlaneConfig();
+    // Opens (or reuses) the CP db and runs the schema migration gate only —
+    // no row is ever written here. The control plane registers no homes at
+    // startup; `home` rows are created by the provisioner (P3.2) via
+    // `createHome`, not by this process.
+    const db = getControlPlaneDb();
+    const server = createControlPlaneServer(config, { db, relay: controlPlaneRelay });
+    // Start the always-on cron scan loop. Webhook ingress is mounted inside the
+    // server route tree (register.ts); the scheduler is the one background loop
+    // that needs an explicit start/stop handle.
+    const scheduler = startSchedulerIngress();
+    let shuttingDown = false;
+    const beginShutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        void shutdown(server, scheduler, signal).catch((error) => {
+            const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+            log('error', 'hearth control plane shutdown failed', { error: redact(message) });
+            process.exit(1);
+        });
+    };
+    process.on('SIGINT', () => beginShutdown('SIGINT'));
+    process.on('SIGTERM', () => beginShutdown('SIGTERM'));
+    process.on('uncaughtException', (error) => {
+        log('error', 'hearth control plane uncaught exception', { error: redact(error instanceof Error ? (error.stack ?? error.message) : String(error)) });
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        log('error', 'hearth control plane unhandled rejection', { error: redact(reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)) });
+        process.exit(1);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(config.port, config.host, () => {
+            log('info', 'hearth control plane listening', {
+                host: config.host,
+                port: config.port,
+                publicOrigin: config.publicOrigin,
+                cookieSecure: config.cookieSecure,
+                wakeTimeoutMs: config.wakeTimeoutMs,
+                readyTimeoutMs: config.readyTimeoutMs,
+            });
+            resolve();
+        });
+    }).catch((error) => {
+        throw general(`hearth control plane failed to bind ${config.host}:${config.port}`, {
+            host: config.host,
+            port: config.port,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    log('error', 'hearth control plane failed to start', { error: redact(message) });
+    process.exit(1);
+});

package/dist/hearth/control-plane/node-message.d.ts

@@ -0,0 +1,31 @@
+import { type HomeBackend } from '../../core/hearth/provider.js';
+import type { M0Config } from '../../core/hearth/types.js';
+import { getHomeById } from './registry.js';
+import type { HomeId } from './types.js';
+import { ensureAwake } from './wake.js';
+export type NodeMessageTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+/** 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 declare const nodeMessageInternals: {
+    ensureAwake: typeof ensureAwake;
+    getHomeById: typeof getHomeById;
+    getHomeBackend: (config: M0Config) => HomeBackend;
+    loadM0Config: () => M0Config;
+};
+/**
+ * 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 declare function wakeAndExecNodeMessage(home_id: HomeId, body: string, tier: string): Promise<void>;