@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/__tests__/webhook-ingress.test.js

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict';
+import { createHmac } from 'node:crypto';
+import { test } from 'node:test';
+import { extractRoutingKey, processWebhookDelivery, } from '../ingress/webhook-route.js';
+import { serializeEnvelope } from '../triggers/envelope.js';
+// Category-3 test (CLAUDE.md "Testing policy" #3 — load-bearing Hearth/CP
+// security regression). Invariants: master plan P5.5 / part-plan T-C3 R-ING-1/
+// R-ING-3. (1) A webhook is delivered ONLY after HMAC-over-raw-body
+// verification; a bad signature never reaches route delivery or the replay
+// ledger. (2) Replay/idempotency: a duplicate delivery is acknowledged and NOT
+// re-delivered. (3) The routing key is NEVER present in the envelope the home
+// receives. (4) The pre-resolution rate limit sheds a flood before any route
+// lookup. Every one of these is a silent-if-regressed security boundary.
+const SECRET = 'whsec_test_value';
+const ROUTE = {
+    route_id: 'r1',
+    tenant_id: 't1',
+    user_id: 'u1',
+    home_id: 'h1',
+    channel: 'webhook',
+    routing_key: 'my-public-routing-key',
+    routing_key_kind: 'opaque',
+    channel_secret_ref: 'ref-r1',
+    delivery_template: null,
+    enabled: true,
+    created_at: '2026-06-30T00:00:00.000Z',
+    updated_at: '2026-06-30T00:00:00.000Z',
+};
+function sign(body) {
+    return createHmac('sha256', SECRET).update(Buffer.from(body, 'utf8')).digest('hex');
+}
+function makeRequest(overrides = {}) {
+    const rawBody = Buffer.from(JSON.stringify({ event: 'ping', n: 1 }), 'utf8');
+    return {
+        routingKey: ROUTE.routing_key,
+        rawBody,
+        signatureHeader: sign(rawBody.toString('utf8')),
+        deliveryIdHeader: 'delivery-abc',
+        contentType: 'application/json',
+        ...overrides,
+    };
+}
+function makeDeps(cap, overrides = {}) {
+    return {
+        checkRate: () => ({ ok: true }),
+        resolveRoute: (channel, key) => {
+            cap.routeLookups += 1;
+            return channel === 'webhook' && key === ROUTE.routing_key ? ROUTE : null;
+        },
+        resolveSecret: (ref) => {
+            if (ref !== ROUTE.channel_secret_ref)
+                throw new Error(`unknown handle ${ref}`);
+            return SECRET;
+        },
+        claimWebhookDelivery: (input) => {
+            cap.claims += 1;
+            return {
+                delivery: {
+                    delivery_id: 'd1',
+                    route_id: input.route_id,
+                    tenant_id: 't1',
+                    user_id: 'u1',
+                    home_id: 'h1',
+                    replay_key: input.replay_key,
+                    replay_window_start: input.replay_window_start,
+                    payload_sha256: input.payload_sha256 ?? null,
+                    signature_sha256: input.signature_sha256 ?? null,
+                    state: 'received',
+                    received_at: input.received_at ?? '2026-06-30T12:00:00.000Z',
+                    delivered_at: null,
+                    last_error: null,
+                    created_at: '2026-06-30T12:00:00.000Z',
+                    updated_at: '2026-06-30T12:00:00.000Z',
+                },
+                claimed: true,
+            };
+        },
+        setWebhookDeliveryState: () => { },
+        deliverTrigger: async (input) => {
+            cap.deliveries.push({ home_id: input.home_id, source_ref: input.source_ref, envelope: input.envelope, serialized: serializeEnvelope(input.envelope) });
+            return { outcome: 'delivered' };
+        },
+        now: () => new Date('2026-06-30T12:00:00.000Z'),
+        ...overrides,
+    };
+}
+function makeCaptured() {
+    return { deliveries: [], routeLookups: 0, claims: 0 };
+}
+test('a validly-signed webhook delivers once; envelope carries NO routing key', async () => {
+    const cap = makeCaptured();
+    const res = await processWebhookDelivery(makeRequest(), makeDeps(cap));
+    assert.equal(res.status, 202);
+    assert.equal(cap.deliveries.length, 1);
+    const d = cap.deliveries[0];
+    assert.equal(d.home_id, 'h1');
+    assert.equal(d.source_ref, 'r1');
+    const parsed = JSON.parse(d.serialized);
+    // R-ING-3: exactly the four canonical fields, no routing key anywhere.
+    assert.deepEqual(Object.keys(parsed).sort(), ['payload', 'received_at', 'source', 'trigger_id']);
+    assert.equal(d.serialized.includes(ROUTE.routing_key), false);
+    assert.equal(parsed['source'], 'webhook');
+    assert.equal(parsed['trigger_id'], `r1:delivery-abc`); // stable route-derived + per-delivery
+    assert.deepEqual(parsed['payload'], { event: 'ping', n: 1 });
+});
+test('a bad signature is rejected with no delivery and no replay-ledger write', async () => {
+    const cap = makeCaptured();
+    const res = await processWebhookDelivery(makeRequest({ signatureHeader: 'deadbeef' }), makeDeps(cap));
+    assert.equal(res.status, 401);
+    assert.equal(cap.deliveries.length, 0);
+    assert.equal(cap.claims, 0); // no webhook_delivery row for an unverified request
+});
+test('a missing signature is rejected', async () => {
+    const cap = makeCaptured();
+    const res = await processWebhookDelivery(makeRequest({ signatureHeader: null }), makeDeps(cap));
+    assert.equal(res.status, 401);
+    assert.equal(cap.deliveries.length, 0);
+});
+test('a replayed delivery is acknowledged idempotently and not re-delivered', async () => {
+    const cap = makeCaptured();
+    const deps = makeDeps(cap, {
+        claimWebhookDelivery: (input) => ({
+            delivery: {
+                delivery_id: 'd1',
+                route_id: input.route_id,
+                tenant_id: 't1',
+                user_id: 'u1',
+                home_id: 'h1',
+                replay_key: input.replay_key,
+                replay_window_start: input.replay_window_start,
+                payload_sha256: null,
+                signature_sha256: null,
+                state: 'delivered',
+                received_at: '2026-06-30T11:00:00.000Z',
+                delivered_at: '2026-06-30T11:00:00.000Z',
+                last_error: null,
+                created_at: '2026-06-30T11:00:00.000Z',
+                updated_at: '2026-06-30T11:00:00.000Z',
+            },
+            claimed: false, // slot already held → replay
+        }),
+    });
+    const res = await processWebhookDelivery(makeRequest(), deps);
+    assert.equal(res.status, 200);
+    assert.equal(cap.deliveries.length, 0);
+});
+test('an unknown routing key is a 404 with no delivery', async () => {
+    const cap = makeCaptured();
+    const res = await processWebhookDelivery(makeRequest({ routingKey: 'nope' }), makeDeps(cap));
+    assert.equal(res.status, 404);
+    assert.equal(cap.deliveries.length, 0);
+});
+test('the pre-resolution rate limit sheds before any route lookup', async () => {
+    const cap = makeCaptured();
+    const deps = makeDeps(cap, { checkRate: () => ({ ok: false, retryAfterMs: 1_000 }) });
+    const res = await processWebhookDelivery(makeRequest(), deps);
+    assert.equal(res.status, 429);
+    assert.equal(cap.routeLookups, 0); // rate limit is evaluated before resolveRoute
+    assert.equal(cap.deliveries.length, 0);
+});
+test('extractRoutingKey rejects traversal / multi-segment / empty keys', () => {
+    assert.equal(extractRoutingKey('/webhook/abc'), 'abc');
+    assert.equal(extractRoutingKey('/webhook/a%2Fb'), null); // decoded embedded slash
+    assert.equal(extractRoutingKey('/webhook/a/b'), null);
+    assert.equal(extractRoutingKey('/webhook/'), null);
+    assert.equal(extractRoutingKey('/webhook'), null);
+});

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

@@ -0,0 +1,21 @@
+export interface ControlPlaneConfig {
+    host: string;
+    port: number;
+    publicOrigin: string;
+    /** Whether the Hearth session cookie should carry `Secure` — true whenever
+     *  `publicOrigin` is `https://`, mirroring the wake-proxy's rule. */
+    cookieSecure: boolean;
+    /** Upper bound P4.2's wake orchestration (`ensureAwake`) uses for a
+     *  resume/recreate cycle before giving up. Not read by this module or by
+     *  server.ts in this phase — carried here so the CP has exactly one config
+     *  object once wake.ts lands. */
+    wakeTimeoutMs: number;
+    /** Ready-probe retry window P4.2's wake orchestration uses against
+     *  `/node/<target>`. Not read by this module or by server.ts in this
+     *  phase. */
+    readyTimeoutMs: number;
+}
+/** Load the CP server config from the environment (defaults applied for
+ *  dogfood: loopback bind, port 8080). Throws on an invalid/missing value
+ *  rather than silently falling back to an insecure default. */
+export declare function loadControlPlaneConfig(env?: NodeJS.ProcessEnv): ControlPlaneConfig;

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

@@ -0,0 +1,77 @@
+// control-plane/config.ts — the CP server's own config: bind address, public
+// origin (used by session.ts for cookie security and state-changing
+// browser-origin checks), and the wake/ready timeout knobs P4.2's wake
+// orchestration will read off this same config object. Deliberately does
+// NOT duplicate CP data-path resolution: the CP db path
+// (`CRTR_HEARTH_CP_DATA_DIR`/`CRTR_HEARTH_CP_DB_PATH`, db.ts) and the
+// secrets-file path (`CRTR_HEARTH_CP_SECRETS_FILE`, secrets.ts) are each
+// resolved by their own module — callers go to those modules directly
+// rather than threading a second, possibly-divergent copy through here.
+import { general } from '../../core/errors.js';
+const ENV = {
+    host: 'CRTR_HEARTH_CP_HOST',
+    port: 'CRTR_HEARTH_CP_PORT',
+    publicOrigin: 'CRTR_HEARTH_CP_PUBLIC_ORIGIN',
+    wakeTimeoutMs: 'CRTR_HEARTH_CP_WAKE_TIMEOUT_MS',
+    readyTimeoutMs: 'CRTR_HEARTH_CP_READY_TIMEOUT_MS',
+};
+function parsePort(value, fallback) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw general(`invalid ${ENV.port}: ${value}`, { env: ENV.port });
+    }
+    return parsed;
+}
+function parseDuration(value, fallback, name) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw general(`invalid ${name}: ${value}`, { env: name });
+    }
+    return parsed;
+}
+function isLoopbackHostname(hostname) {
+    return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '::1' || hostname === '::ffff:127.0.0.1' || hostname.startsWith('127.');
+}
+function parsePublicOrigin(env, host, port) {
+    const raw = env[ENV.publicOrigin]?.trim() ?? '';
+    if (raw !== '') {
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            throw general(`invalid ${ENV.publicOrigin}: must be a valid URL`, { env: ENV.publicOrigin });
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw general(`invalid ${ENV.publicOrigin}: scheme must be http: or https:`, { env: ENV.publicOrigin, scheme: parsed.protocol });
+        }
+        const origin = parsed.origin;
+        if (origin === 'null' || origin === '') {
+            throw general(`invalid ${ENV.publicOrigin}: must be a valid web origin`, { env: ENV.publicOrigin });
+        }
+        if (parsed.protocol !== 'https:' && !isLoopbackHostname(parsed.hostname)) {
+            throw general(`${ENV.publicOrigin} must use https: for a non-loopback origin`, { env: ENV.publicOrigin, hostname: parsed.hostname });
+        }
+        return { publicOrigin: origin, cookieSecure: parsed.protocol === 'https:' };
+    }
+    if (isLoopbackHostname(host)) {
+        const origin = `http://127.0.0.1:${port}`;
+        return { publicOrigin: origin, cookieSecure: false };
+    }
+    throw general(`${ENV.publicOrigin} is required when ${ENV.host} is bound off-loopback`, { env: ENV.publicOrigin, host });
+}
+/** Load the CP server config from the environment (defaults applied for
+ *  dogfood: loopback bind, port 8080). Throws on an invalid/missing value
+ *  rather than silently falling back to an insecure default. */
+export function loadControlPlaneConfig(env = process.env) {
+    const host = (env[ENV.host] ?? '127.0.0.1').trim() || '127.0.0.1';
+    const port = parsePort(env[ENV.port], 8080);
+    const { publicOrigin, cookieSecure } = parsePublicOrigin(env, host, port);
+    const wakeTimeoutMs = parseDuration(env[ENV.wakeTimeoutMs], 150_000, ENV.wakeTimeoutMs);
+    const readyTimeoutMs = parseDuration(env[ENV.readyTimeoutMs], 8_000, ENV.readyTimeoutMs);
+    return { host, port, publicOrigin, cookieSecure, wakeTimeoutMs, readyTimeoutMs };
+}

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

@@ -0,0 +1,30 @@
+import { DatabaseSync } from 'node:sqlite';
+/** Resolve the CP SQLite db file path: an explicit `CRTR_HEARTH_CP_DB_PATH`
+ *  override, else `<dataDir>/control-plane.db` where `dataDir` follows the
+ *  same `CRTR_HEARTH_CP_DATA_DIR` convention `secrets.ts` uses. Deliberately
+ *  independent of `canvasDbPath()` / `CRTR_HOME` — the control plane is not a
+ *  canvas node and must not share or collide with a home's canvas db. */
+export declare function controlPlaneDbPath(env?: NodeJS.ProcessEnv): string;
+/** The ordered migration list. Index `i` is migration version `i + 1`; the
+ *  db's `user_version` tracks how many have been applied. Append only. */
+export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
+/** Bring `db` up to the latest schema version. Reads `user_version`, runs
+ *  each pending migration in order, and bumps `user_version` after each so
+ *  the work is gated and idempotent: re-running is a no-op once
+ *  `user_version` reaches `MIGRATIONS.length`. Forward-only. */
+export declare function migrate(db: DatabaseSync): void;
+/** Open (or reuse) the CP db at `path`, initializing WAL + schema on first
+ *  open. This is the SOLE function in the codebase that may construct a
+ *  `DatabaseSync` against the CP db file — every CP store goes through this
+ *  (directly or via `getControlPlaneDb()`) and never opens its own
+ *  connection. Keyed by path so tests with distinct temp dbs get independent
+ *  handles, exactly like `src/core/canvas/db.ts`'s `openDb()`. */
+export declare function openControlPlaneDb(path: string): DatabaseSync;
+/** The cached handle accessor every CP store (registry, scheduler, ingress)
+ *  imports — resolves the db path the standard way and opens/reuses the one
+ *  connection for it. Never construct a second `DatabaseSync` against the CP
+ *  db elsewhere in the codebase. */
+export declare function getControlPlaneDb(env?: NodeJS.ProcessEnv): DatabaseSync;
+/** Close and forget the handle for `path` (defaults to the standard
+ *  resolved path). Mainly for tests. */
+export declare function closeControlPlaneDb(path?: string): void;