@crouton-kit/crouter 0.3.33 → 0.3.35

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.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.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;