@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/control-plane/__tests__/relay-security.test.js

@@ -0,0 +1,314 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import { test } from 'node:test';
+import { WebSocket, WebSocketServer } from 'ws';
+import { buildUpstreamHttpUrl, proxyHttp, proxyUpgrade } from '../relay.js';
+// Category-3 test (CLAUDE.md "Testing policy" #3 — load-bearing Hearth/CP
+// security regression). Approved by Silas 2026-06-30 as a narrow carve-out
+// after the P4.3 relay review (mr16xp6d-2a5061f5 / mr16z2lz-3cd35b0c) found
+// these exact invariants had zero durable coverage — only a throwaway smoke
+// that was deleted after the implementation pass. The invariants below are
+// the ones part-plan T3.2's acceptance checks and design.md's R-CP-2/R-CP-3/
+// R-CP-6 non-negotiables name explicitly:
+//   - R-CP-3: the browser leg never supplies, and never sees reflected, the
+//     CP->home relay token; the home leg sees ONLY `Authorization: Bearer
+//     <relayToken>`.
+//   - criterion 4 (origin-form-only request target): scheme-relative,
+//     absolute, raw/encoded-backslash, and encoded-CRLF request targets are
+//     rejected before any upstream contact (open-proxy/SSRF prevention).
+//   - R-CP-2/R-CP-6: `home` is resolved once, server-side, from the
+//     caller's session; no client-supplied `?target=`/`/node/<id>` can move
+//     the request onto a different home's preview origin or node target.
+// A regression in any of these is silent (still typechecks, still serves
+// chat) and is exactly the kind of defect this carve-out exists for.
+const testConfig = {
+    host: '127.0.0.1',
+    port: 0,
+    publicOrigin: 'http://127.0.0.1:0',
+    cookieSecure: false,
+    wakeTimeoutMs: 2_000,
+    readyTimeoutMs: 2_000,
+};
+function makeHome(overrides = {}) {
+    const now = '2026-06-30T00:00:00.000Z';
+    return {
+        home_id: 'home-a',
+        tenant_id: 'tenant-1',
+        user_id: 'user-1',
+        provider: 'blaxel',
+        provider_sandbox_id: 'sandbox-a',
+        provider_volume_id: 'volume-a',
+        preview_endpoint: 'https://home-a.example.invalid',
+        home_agent_target: 'node-a',
+        relay_auth_ref: 'ref-a',
+        status: 'running',
+        template_version: null,
+        last_ready_at: null,
+        last_wake_at: null,
+        last_suspend_at: null,
+        last_wake_latency_ms: null,
+        health_verdict: 'healthy',
+        created_at: now,
+        updated_at: now,
+        ...overrides,
+    };
+}
+// --- Minimal req/res fakes (same shape as wake-proxy/__tests__'s FakeReq/
+// FakeRes — only the surface proxyHttp actually touches). ------------------
+class FakeReq extends EventEmitter {
+    url;
+    method;
+    headers;
+    constructor(path, headers = {}, method = 'GET') {
+        super();
+        this.url = path;
+        this.method = method;
+        this.headers = headers;
+    }
+}
+class FakeRes extends EventEmitter {
+    statusCode = 200;
+    statusMessage = '';
+    headersSent = false;
+    writableEnded = false;
+    headers = new Map();
+    chunks = [];
+    socket = { setNoDelay() { } };
+    setHeader(name, value) {
+        this.headers.set(name.toLowerCase(), value);
+    }
+    getHeader(name) {
+        return this.headers.get(name.toLowerCase());
+    }
+    hasHeader(name) {
+        return this.headers.has(name.toLowerCase());
+    }
+    writeHead(code, headers) {
+        this.statusCode = code;
+        this.headersSent = true;
+        if (headers)
+            for (const [k, v] of Object.entries(headers))
+                this.setHeader(k, v);
+    }
+    flushHeaders() {
+        this.headersSent = true;
+    }
+    write(chunk) {
+        this.headersSent = true;
+        this.chunks.push(Buffer.from(chunk));
+        return true;
+    }
+    end(chunk) {
+        this.headersSent = true;
+        if (chunk !== undefined)
+            this.chunks.push(Buffer.from(chunk));
+        this.writableEnded = true;
+        this.emit('finish');
+    }
+    destroy() {
+        this.writableEnded = true;
+    }
+    body() {
+        return Buffer.concat(this.chunks).toString('utf8');
+    }
+}
+function asReq(req) {
+    return req;
+}
+function asRes(res) {
+    return res;
+}
+async function listen(server) {
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('expected a network address');
+    return {
+        origin: `http://127.0.0.1:${address.port}`,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+// --- 1. HTTP browser->home header/token isolation -------------------------
+test('proxyHttp: browser auth/cookie/forwarding headers never reach upstream; only the relay Bearer token does; the token is never reflected to the browser', async () => {
+    let captured = null;
+    const upstream = http.createServer((req, res) => {
+        captured = req.headers;
+        // Deliberately reflect the relay token back in the response, the way a
+        // misbehaving or compromised home might — this is what makes the
+        // browser-side assertion below non-vacuous.
+        res.writeHead(200, { 'content-type': 'text/plain', authorization: 'Bearer RELAY_TOKEN_A' });
+        res.end('upstream-ok');
+    });
+    const { origin, close } = await listen(upstream);
+    try {
+        const req = new FakeReq('/views/chat', {
+            authorization: 'Bearer BROWSER_OWN_TOKEN',
+            cookie: 'session=browser-cookie',
+            forwarded: 'for=1.2.3.4;proto=https',
+            'x-forwarded-for': '1.2.3.4',
+            'x-forwarded-proto': 'https',
+            'x-forwarded-host': 'evil.example',
+            'x-real-ip': '1.2.3.4',
+            'proxy-authorization': 'Basic evil',
+            'sec-websocket-key': 'not-a-real-ws-request',
+            'x-keep-me': 'safe-custom-header',
+        });
+        const res = new FakeRes();
+        await proxyHttp(asReq(req), asRes(res), makeHome(), {
+            ensureAwake: async () => ({ preview_endpoint: origin, relayToken: 'RELAY_TOKEN_A' }),
+            resolveRunning: () => null,
+            invalidateWarmVerdict: () => undefined,
+            loadConfig: () => testConfig,
+        });
+        assert.equal(res.statusCode, 200);
+        assert.equal(res.body(), 'upstream-ok');
+        assert.ok(captured, 'upstream must have received the forwarded request');
+        const upstreamHeaders = captured;
+        assert.equal(upstreamHeaders.authorization, 'Bearer RELAY_TOKEN_A', 'upstream must see only the relay token');
+        assert.equal(upstreamHeaders.cookie, undefined, 'browser cookie must not reach upstream');
+        assert.equal(upstreamHeaders.forwarded, undefined, 'client-supplied Forwarded must not reach upstream');
+        assert.equal(upstreamHeaders['x-forwarded-for'], undefined);
+        assert.equal(upstreamHeaders['x-forwarded-proto'], undefined);
+        assert.equal(upstreamHeaders['x-forwarded-host'], undefined);
+        assert.equal(upstreamHeaders['x-real-ip'], undefined);
+        assert.equal(upstreamHeaders['proxy-authorization'], undefined);
+        assert.equal(upstreamHeaders['sec-websocket-key'], undefined);
+        assert.equal(upstreamHeaders['x-keep-me'], 'safe-custom-header', 'a safe custom header must still pass through');
+        assert.equal(res.getHeader('authorization'), undefined, 'an upstream-reflected relay token must never reach the browser response');
+    }
+    finally {
+        await close();
+    }
+});
+// --- 2. Origin-form / SSRF rejection --------------------------------------
+test('buildUpstreamHttpUrl: rejects dangerous request targets before any upstream contact', () => {
+    const previewEndpoint = 'https://home-a.example.invalid';
+    const dangerous = [
+        '//evil.example.com/path',
+        'http://evil.example.com/path',
+        '\\evil.example.com/path',
+        '%5Cevil.example.com/path',
+        '%0d%0aHost:%20evil.example.com',
+    ];
+    for (const target of dangerous) {
+        assert.throws(() => buildUpstreamHttpUrl(previewEndpoint, target), `expected rejection for: ${target}`);
+    }
+});
+test('buildUpstreamHttpUrl: accepts an ordinary origin-form target and stays on the home origin', () => {
+    const url = buildUpstreamHttpUrl('https://home-a.example.invalid', '/views/chat?x=1');
+    assert.equal(url.origin, 'https://home-a.example.invalid');
+    assert.equal(url.pathname, '/views/chat');
+});
+// --- 3. Cross-home/target isolation ---------------------------------------
+test('proxyHttp: a session-resolved home A is never widened by a client ?target= to home B', async () => {
+    let hitsA = 0;
+    let hitsB = 0;
+    const upstreamA = http.createServer((_req, res) => {
+        hitsA += 1;
+        res.writeHead(200);
+        res.end('home-a-ok');
+    });
+    const upstreamB = http.createServer((_req, res) => {
+        hitsB += 1;
+        res.writeHead(200);
+        res.end('home-b-ok');
+    });
+    const a = await listen(upstreamA);
+    const b = await listen(upstreamB);
+    try {
+        const req = new FakeReq('/views/chat?target=home-b');
+        const res = new FakeRes();
+        let ensureAwakeAskedFor = null;
+        let resolveRunningAskedFor = null;
+        await proxyHttp(asReq(req), asRes(res), makeHome({ home_id: 'home-a' }), {
+            ensureAwake: async (home_id) => {
+                ensureAwakeAskedFor = home_id;
+                // The relay's only home-selection input is the `home` row it was
+                // called with — never the request's own query string.
+                if (home_id !== 'home-a')
+                    return { preview_endpoint: b.origin, relayToken: 'RELAY_TOKEN_B' };
+                return { preview_endpoint: a.origin, relayToken: 'RELAY_TOKEN_A' };
+            },
+            resolveRunning: (home_id) => {
+                resolveRunningAskedFor = home_id;
+                return null;
+            },
+            invalidateWarmVerdict: () => undefined,
+            loadConfig: () => testConfig,
+        });
+        assert.equal(resolveRunningAskedFor, 'home-a', 'resolveRunning must be asked for the session-resolved home, never a client-supplied target');
+        assert.equal(ensureAwakeAskedFor, 'home-a', 'ensureAwake must be asked for the session-resolved home, never a client-supplied target');
+        assert.equal(res.body(), 'home-a-ok');
+        assert.equal(hitsA, 1);
+        assert.equal(hitsB, 0, 'home B must never be contacted for a home-A-resolved request');
+    }
+    finally {
+        await Promise.all([a.close(), b.close()]);
+    }
+});
+test('proxyUpgrade: WS upstream target is always home.home_agent_target, never the client-claimed /node/<id> path or ?target=', async () => {
+    let upstreamAHits = [];
+    let upstreamBHits = 0;
+    const wssA = new WebSocketServer({ port: 0 });
+    wssA.on('connection', (ws, req) => {
+        upstreamAHits.push({ url: req.url, authorization: req.headers.authorization, cookie: req.headers.cookie });
+        ws.on('message', (data) => ws.send(data));
+    });
+    const wssB = new WebSocketServer({ port: 0 });
+    wssB.on('connection', () => {
+        upstreamBHits += 1;
+    });
+    const aPort = wssA.address().port;
+    const bPort = wssB.address().port;
+    const home = makeHome({ home_id: 'home-a', home_agent_target: 'node-a' });
+    let ensureAwakeAskedFor = null;
+    const relayServer = http.createServer((_req, res) => {
+        res.writeHead(404);
+        res.end();
+    });
+    relayServer.on('upgrade', (req, socket, head) => {
+        proxyUpgrade(req, socket, head, home, {
+            ensureAwake: async (home_id) => {
+                ensureAwakeAskedFor = home_id;
+                // Same DI seam as the HTTP cross-home test: a regression that derived
+                // the wake target from the client's `?target=` would make this
+                // resolve to home B's listener, and the assertions below would catch
+                // the resulting connection landing on wssB instead of wssA.
+                if (home_id !== 'home-a')
+                    return { preview_endpoint: `http://127.0.0.1:${bPort}`, relayToken: 'RELAY_TOKEN_B' };
+                return { preview_endpoint: `http://127.0.0.1:${aPort}`, relayToken: 'RELAY_TOKEN_A' };
+            },
+            loadConfig: () => testConfig,
+        });
+    });
+    const relay = await listen(relayServer);
+    let client = null;
+    try {
+        client = new WebSocket(`${relay.origin.replace('http://', 'ws://')}/node/some-other-client-claimed-id?target=home-b`, {
+            headers: { authorization: 'Bearer BROWSER_OWN_TOKEN', cookie: 'session=browser-cookie' },
+        });
+        const echoed = await new Promise((resolve, reject) => {
+            client.once('open', () => client.send('ping'));
+            client.once('message', (data) => resolve(data.toString()));
+            client.once('error', reject);
+        });
+        assert.equal(echoed, 'ping');
+        assert.equal(ensureAwakeAskedFor, 'home-a', 'ensureAwake must be asked for the session-resolved home, never the client-claimed path/target');
+        assert.equal(upstreamAHits.length, 1);
+        assert.equal(upstreamAHits[0]?.url, '/node/node-a', 'upstream path must be the server-resolved home_agent_target, not the client path/target');
+        assert.equal(upstreamAHits[0]?.authorization, 'Bearer RELAY_TOKEN_A');
+        assert.equal(upstreamAHits[0]?.cookie, undefined, 'the browser cookie must never reach the upstream websocket');
+        assert.equal(upstreamBHits, 0, 'home B must never receive a connection for a home-A-resolved request');
+    }
+    finally {
+        if (client) {
+            if (client.readyState === WebSocket.OPEN || client.readyState === WebSocket.CONNECTING) {
+                client.terminate();
+            }
+        }
+        await new Promise((resolve) => wssA.close(() => resolve()));
+        await new Promise((resolve) => wssB.close(() => resolve()));
+        await relay.close();
+    }
+});

package/dist/hearth/control-plane/__tests__/scheduler-scan-loop.test.d.ts

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

package/dist/hearth/control-plane/__tests__/scheduler-scan-loop.test.js

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { runSchedulerScan } from '../scheduler/scan-loop.js';
+// Category-3 test (CLAUDE.md "Testing policy" #3 — load-bearing Hearth/CP
+// regression). Invariant: master plan P5.4 / part-plan T-C1 R-CRON-3 — the CP
+// cron scan is idempotent and restart-safe. A due schedule fires exactly once
+// per slot even across repeated scans, and a fire left `waking` by a crashed
+// CP is re-driven to a SINGLE delivery, never a double. A regression here is
+// silent (still typechecks) and directly re-introduces the double-fire failure
+// mode this ledger exists to prevent.
+const SCHEDULE = {
+    schedule_id: 's1',
+    tenant_id: 't1',
+    user_id: 'u1',
+    home_id: 'h1',
+    label: 'nightly',
+    recurrence: '*/5 * * * *',
+    timezone: 'UTC',
+    delivery_payload: { hello: 'world' },
+    next_fire_at: '2026-06-30T12:00:00.000Z',
+    last_fired_at: null,
+    enabled: true,
+    created_at: '2026-06-30T00:00:00.000Z',
+    updated_at: '2026-06-30T00:00:00.000Z',
+};
+function fireFor(schedule, state) {
+    return {
+        fire_id: 'f1',
+        schedule_id: schedule.schedule_id,
+        home_id: schedule.home_id,
+        tenant_id: schedule.tenant_id,
+        user_id: schedule.user_id,
+        scheduled_for: schedule.next_fire_at,
+        state,
+        attempts: 0,
+        last_error: null,
+        delivered_at: null,
+        created_at: schedule.created_at,
+        updated_at: schedule.updated_at,
+    };
+}
+function makeDeps(rec, overrides, outcome = { outcome: 'delivered' }) {
+    return {
+        selectDueSchedules: () => [],
+        getScheduleById: (id) => (id === SCHEDULE.schedule_id ? SCHEDULE : null),
+        claimFire: (input) => {
+            rec.claimCount += 1;
+            return { fire: fireFor(SCHEDULE, 'pending'), claimed: rec.claimCount === 1 };
+        },
+        setFireState: (fire_id, state) => {
+            rec.fireStates.push({ fire_id, state });
+        },
+        advanceNextFire: (schedule_id, next, last) => {
+            rec.advances.push({ schedule_id, next, last });
+        },
+        selectResumableFires: () => [],
+        computeNextFire: () => '2026-06-30T12:05:00.000Z',
+        deliverTrigger: async (input) => {
+            rec.deliveries.push({
+                home_id: input.home_id,
+                source_ref: input.source_ref,
+                trigger_id: input.envelope.trigger_id,
+                tier: input.tier,
+                source: input.envelope.source,
+                payload: input.envelope.payload,
+            });
+            return outcome;
+        },
+        now: () => '2026-06-30T12:00:01.000Z',
+        intervalMs: 15_000,
+        ...overrides,
+    };
+}
+function makeRecorder() {
+    return { deliveries: [], fireStates: [], advances: [], claimCount: 0 };
+}
+test('a due schedule fires exactly once with urgent tier and trigger_id == fire_id', async () => {
+    const rec = makeRecorder();
+    const deps = makeDeps(rec, { selectDueSchedules: () => [SCHEDULE] });
+    await runSchedulerScan(deps);
+    assert.equal(rec.deliveries.length, 1);
+    const d = rec.deliveries[0];
+    assert.equal(d.tier, 'urgent');
+    assert.equal(d.source, 'cron');
+    assert.equal(d.trigger_id, 'f1'); // R-CRON-5: envelope trigger_id is the durable fire_id
+    assert.equal(d.home_id, 'h1');
+    assert.deepEqual(d.payload, { hello: 'world' });
+    // next_fire_at advanced before delivery so the slot cannot be re-selected.
+    assert.deepEqual(rec.advances, [{ schedule_id: 's1', next: '2026-06-30T12:05:00.000Z', last: '2026-06-30T12:00:00.000Z' }]);
+    assert.deepEqual(rec.fireStates.map((s) => s.state), ['waking', 'delivered']);
+});
+test('the same due slot is claimed only once across repeated scans (no double fire)', async () => {
+    const rec = makeRecorder();
+    // Both scans see the schedule as due, but claimFire grants the slot once.
+    const deps = makeDeps(rec, { selectDueSchedules: () => [SCHEDULE] });
+    await runSchedulerScan(deps);
+    await runSchedulerScan(deps);
+    assert.equal(rec.claimCount, 2); // both passes attempted a claim
+    assert.equal(rec.deliveries.length, 1); // only the winning claim delivered
+});
+test('a fire left waking by a crashed CP is resumed to a single delivery, not doubled', async () => {
+    const rec = makeRecorder();
+    let resumables = [fireFor(SCHEDULE, 'waking')];
+    const deps = makeDeps(rec, {
+        selectResumableFires: () => {
+            const out = resumables;
+            resumables = []; // next scan finds it resolved
+            return out;
+        },
+        selectDueSchedules: () => [], // slot already advanced/claimed pre-crash
+    });
+    await runSchedulerScan(deps);
+    await runSchedulerScan(deps);
+    assert.equal(rec.claimCount, 0); // resume path never re-claims
+    assert.equal(rec.deliveries.length, 1); // exactly one delivery for the stranded fire
+    assert.equal(rec.deliveries[0].trigger_id, 'f1');
+});
+test('a failed delivery marks the fire failed with an incremented attempt, no retry storm', async () => {
+    const rec = makeRecorder();
+    const attemptFlags = [];
+    const deps = makeDeps(rec, {
+        selectDueSchedules: () => [SCHEDULE],
+        setFireState: (fire_id, state, options) => {
+            rec.fireStates.push({ fire_id, state });
+            if (options?.increment_attempts !== undefined)
+                attemptFlags.push(options.increment_attempts);
+        },
+    }, { outcome: 'failed', reason: 'boom' });
+    await runSchedulerScan(deps);
+    assert.deepEqual(rec.fireStates.map((s) => s.state), ['waking', 'failed']);
+    assert.deepEqual(attemptFlags, [true]);
+    assert.equal(rec.deliveries.length, 1); // one attempt; the natural next tick is the only re-fire
+});

package/dist/hearth/control-plane/__tests__/trigger-delivery.test.d.ts

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

package/dist/hearth/control-plane/__tests__/trigger-delivery.test.js

@@ -0,0 +1,170 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+// Category-3 test (CLAUDE.md "Testing policy" #3 — load-bearing Hearth/CP
+// security regression). Invariants: master plan P5.2/P5.3, part-plan T-B2/T-B4,
+// R-TRIG-1/R-TRIG-4. (1) The delivery chokepoint carries the envelope on STDIN
+// via the P4.4 primitive, never in argv — and only for an AUTHORIZED trigger.
+// (2) The FK-integrity ACL rejects cross-home targeting and terminated homes.
+// (3) An unauthorized trigger NEVER execs and writes a `rejected` audit row; an
+// authorized one writes a `delivered` row. Silent regressions here defeat the
+// R-TRIG-4 auth/audit boundary that all cron+webhook delivery funnels through.
+let dbDir;
+function setupDb() {
+    dbDir = mkdtempSync(join(tmpdir(), 'crtr-cp-trigger-'));
+    process.env['CRTR_HEARTH_CP_DB_PATH'] = join(dbDir, 'control-plane.db');
+}
+function teardownDb(dbPath) {
+    // Lazy import to avoid pinning the module before env is set.
+    void dbPath;
+    rmSync(dbDir, { recursive: true, force: true });
+    delete process.env['CRTR_HEARTH_CP_DB_PATH'];
+}
+test('deliverTrigger carries the serialized envelope on stdin at the requested tier for an authorized trigger', async () => {
+    const { deliverTrigger, deliverInternals } = await import('../triggers/deliver.js');
+    const { buildTriggerEnvelope, serializeEnvelope } = await import('../triggers/envelope.js');
+    const orig = { ...deliverInternals };
+    const execCalls = [];
+    const audits = [];
+    deliverInternals.authorizeTrigger = () => ({ ok: true });
+    deliverInternals.wakeAndExecNodeMessage = async (home_id, body, tier) => {
+        execCalls.push({ home_id, body, tier });
+    };
+    deliverInternals.recordTriggerAudit = ((entry) => {
+        audits.push({ outcome: entry.outcome, trigger_id: entry.trigger_id, source_ref: entry.source_ref });
+        return {};
+    });
+    try {
+        const envelope = buildTriggerEnvelope({ source: 'webhook', trigger_id: 'r1:abc', payload: { a: 1, quote: 'has "quotes" & spaces' } });
+        const result = await deliverTrigger({ home_id: 'h1', source_ref: 'r1', envelope, tier: 'urgent' });
+        assert.equal(result.outcome, 'delivered');
+        assert.equal(execCalls.length, 1);
+        // The envelope travels as the exec STDIN body verbatim, never in argv.
+        assert.equal(execCalls[0].body, serializeEnvelope(envelope));
+        assert.equal(execCalls[0].tier, 'urgent');
+        assert.equal(execCalls[0].home_id, 'h1');
+        assert.equal(audits.length, 1);
+        assert.equal(audits[0].outcome, 'delivered');
+        assert.equal(audits[0].trigger_id, 'r1:abc');
+    }
+    finally {
+        Object.assign(deliverInternals, orig);
+    }
+});
+test('an unauthorized trigger never execs and records a rejected audit', async () => {
+    const { deliverTrigger, deliverInternals } = await import('../triggers/deliver.js');
+    const { buildTriggerEnvelope } = await import('../triggers/envelope.js');
+    const orig = { ...deliverInternals };
+    let execCalled = false;
+    const audits = [];
+    deliverInternals.authorizeTrigger = () => ({ ok: false, reason: 'cross-home targeting rejected' });
+    deliverInternals.wakeAndExecNodeMessage = async () => {
+        execCalled = true;
+    };
+    deliverInternals.recordTriggerAudit = ((entry) => {
+        audits.push({ outcome: entry.outcome, reason: entry.reason ?? null });
+        return {};
+    });
+    try {
+        const envelope = buildTriggerEnvelope({ source: 'cron', trigger_id: 'f1', payload: {} });
+        const result = await deliverTrigger({ home_id: 'h2', source_ref: 'f1', envelope, tier: 'urgent' });
+        assert.equal(result.outcome, 'rejected');
+        assert.equal(execCalled, false); // unauthorized never reaches the exec primitive
+        assert.equal(audits.length, 1);
+        assert.equal(audits[0].outcome, 'rejected');
+        assert.equal(audits[0].reason, 'cross-home targeting rejected');
+    }
+    finally {
+        Object.assign(deliverInternals, orig);
+    }
+});
+test('authorizeTrigger enforces the FK-integrity guard against a real CP db', async () => {
+    setupDb();
+    const dbPath = process.env['CRTR_HEARTH_CP_DB_PATH'];
+    try {
+        const { getControlPlaneDb, closeControlPlaneDb } = await import('../db.js');
+        const { createHome, setHomeStatus } = await import('../registry.js');
+        const { createSchedule } = await import('../scheduler/schedule-store.js');
+        const { claimFire } = await import('../scheduler/fire-store.js');
+        const { authorizeTrigger } = await import('../triggers/acl.js');
+        getControlPlaneDb(); // open + migrate
+        createHome({ home_id: 'h1', tenant_id: 't1', user_id: 'u1', status: 'running' });
+        createHome({ home_id: 'h2', tenant_id: 't2', user_id: 'u2', status: 'running' });
+        const schedule = createSchedule({
+            home_id: 'h1',
+            label: 'x',
+            recurrence: '*/5 * * * *',
+            timezone: 'UTC',
+            delivery_payload: {},
+            next_fire_at: '2026-06-30T12:00:00.000Z',
+        });
+        const claim = claimFire({ schedule_id: schedule.schedule_id, scheduled_for: schedule.next_fire_at });
+        const fireId = claim.fire.fire_id;
+        // Matching target home → authorized.
+        assert.deepEqual(authorizeTrigger('cron', fireId, 'h1'), { ok: true });
+        // Cross-home targeting → rejected.
+        assert.equal(authorizeTrigger('cron', fireId, 'h2').ok, false);
+        // Absent source row → rejected.
+        assert.equal(authorizeTrigger('cron', 'no-such-fire', 'h1').ok, false);
+        // Terminated target home → rejected even though the FK matches.
+        setHomeStatus('h1', 'terminated');
+        assert.equal(authorizeTrigger('cron', fireId, 'h1').ok, false);
+        closeControlPlaneDb(dbPath);
+    }
+    finally {
+        teardownDb(dbPath);
+    }
+});
+test('deliverTrigger writes real delivered/rejected audit rows through the chokepoint', async () => {
+    setupDb();
+    const dbPath = process.env['CRTR_HEARTH_CP_DB_PATH'];
+    try {
+        const { getControlPlaneDb, closeControlPlaneDb } = await import('../db.js');
+        const { createHome } = await import('../registry.js');
+        const { createSchedule } = await import('../scheduler/schedule-store.js');
+        const { claimFire } = await import('../scheduler/fire-store.js');
+        const { listTriggerAudit } = await import('../triggers/audit-store.js');
+        const { deliverTrigger, deliverInternals } = await import('../triggers/deliver.js');
+        const { buildTriggerEnvelope } = await import('../triggers/envelope.js');
+        getControlPlaneDb();
+        createHome({ home_id: 'h1', tenant_id: 't1', user_id: 'u1', status: 'running' });
+        createHome({ home_id: 'h2', tenant_id: 't2', user_id: 'u2', status: 'running' });
+        const schedule = createSchedule({
+            home_id: 'h1',
+            label: 'x',
+            recurrence: '*/5 * * * *',
+            timezone: 'UTC',
+            delivery_payload: { secret: 'never-persisted-raw' },
+            next_fire_at: '2026-06-30T12:00:00.000Z',
+        });
+        const fireId = claimFire({ schedule_id: schedule.schedule_id, scheduled_for: schedule.next_fire_at }).fire.fire_id;
+        const orig = { ...deliverInternals };
+        deliverInternals.wakeAndExecNodeMessage = async () => { }; // fake the provider exec only
+        try {
+            const okEnv = buildTriggerEnvelope({ source: 'cron', trigger_id: fireId, payload: { secret: 'never-persisted-raw' } });
+            const okRes = await deliverTrigger({ home_id: 'h1', source_ref: fireId, envelope: okEnv, tier: 'urgent' });
+            assert.equal(okRes.outcome, 'delivered');
+            // Cross-home target → chokepoint rejects (real ACL) and never execs.
+            const badEnv = buildTriggerEnvelope({ source: 'cron', trigger_id: fireId, payload: {} });
+            const badRes = await deliverTrigger({ home_id: 'h2', source_ref: fireId, envelope: badEnv, tier: 'urgent' });
+            assert.equal(badRes.outcome, 'rejected');
+        }
+        finally {
+            Object.assign(deliverInternals, orig);
+        }
+        const rows = listTriggerAudit('h1');
+        const outcomes = rows.map((r) => r.outcome).sort();
+        assert.deepEqual(outcomes, ['delivered', 'rejected']);
+        // No raw payload persisted — only a hash.
+        for (const row of rows) {
+            assert.equal(row.payload_sha256 !== null && row.payload_sha256.length === 64, true);
+            assert.equal(JSON.stringify(row).includes('never-persisted-raw'), false);
+        }
+        closeControlPlaneDb(dbPath);
+    }
+    finally {
+        teardownDb(dbPath);
+    }
+});

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

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