@crouton-kit/crouter 0.3.33 → 0.3.34

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

@@ -0,0 +1,534 @@
+// control-plane.db — the CP's own SQLite store, separate from canvas.db. This
+// module is the SOLE owner of the cached `DatabaseSync` connection and the
+// migration gate: every other CP store (registry, scheduler, ingress) imports
+// `getControlPlaneDb()` from here rather than opening a second connection
+// (master plan decision 9 / orchestration brief non-negotiable). It lives on
+// the CP's own data volume — NOT canvas home, NOT `canvasDbPath()` — because
+// the control plane is a separate always-on process from any home/node.
+//
+// Mirrors `src/core/canvas/db.ts` exactly: `DatabaseSync` + WAL, schema
+// expressed as a forward-only `MIGRATIONS` list gated by `PRAGMA user_version`.
+// Migrations are append-only — never edit a shipped step.
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+const ENV = {
+    // Same data-dir convention `secrets.ts` (P1.3) uses, so the CP's SQLite db
+    // and its secrets file default to living side by side on one data volume.
+    dataDir: 'CRTR_HEARTH_CP_DATA_DIR',
+    // Explicit override for the db file itself, for deployments that want the
+    // db on a different mount than the rest of the CP data dir.
+    dbPath: 'CRTR_HEARTH_CP_DB_PATH',
+};
+const DB_FILE_NAME = 'control-plane.db';
+function expandHomePath(input) {
+    if (input.startsWith('~'))
+        return join(homedir(), input.slice(1));
+    return resolve(input);
+}
+function defaultDataDir(env) {
+    const dataDir = env[ENV.dataDir]?.trim();
+    return dataDir !== undefined && dataDir !== ''
+        ? expandHomePath(dataDir)
+        : expandHomePath('~/.crouter/hearth-control-plane');
+}
+/** 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 function controlPlaneDbPath(env = process.env) {
+    const override = env[ENV.dbPath]?.trim();
+    if (override !== undefined && override !== '')
+        return expandHomePath(override);
+    return join(defaultDataDir(env), DB_FILE_NAME);
+}
+// --- Schema as a forward-only migration list ------------------------------
+/** v1 — the `home` registry table (design.md §5.1). `home_id` is the stable
+ *  PK, independent of provider sandbox/node churn; `schedule` and
+ *  `ingress_route` (added by later sibling migrations against this same
+ *  handle) FK to it. Every secret is stored as a HANDLE
+ *  (`relay_auth_ref`) — never a model credential, never an inline value
+ *  (R-REG-3 / R-CP-8). `IF NOT EXISTS` makes this a no-op on re-open. */
+function homeTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS home (
+  home_id                 TEXT PRIMARY KEY,
+  tenant_id               TEXT NOT NULL,
+  user_id                 TEXT NOT NULL,
+  provider                TEXT NOT NULL DEFAULT 'blaxel',
+  provider_sandbox_id     TEXT,
+  provider_volume_id      TEXT,
+  preview_endpoint        TEXT,
+  home_agent_target       TEXT,
+  relay_auth_ref          TEXT,
+  status                  TEXT NOT NULL DEFAULT 'provisioning',
+  template_version        TEXT,
+  last_ready_at           TEXT,
+  last_wake_at            TEXT,
+  last_suspend_at         TEXT,
+  last_wake_latency_ms    INTEGER,
+  health_verdict          TEXT NOT NULL DEFAULT 'unknown',
+  created_at              TEXT NOT NULL,
+  updated_at              TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_home_tenant_user ON home(tenant_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_home_provider_sandbox ON home(provider_sandbox_id);
+`);
+}
+/** v2 — cron schedule definitions. `next_fire_at` is the durable timer the CP
+ *  scan loop selects on; home agents keep no cron scheduler state. */
+function scheduleTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS schedule (
+  schedule_id       TEXT PRIMARY KEY,
+  tenant_id         TEXT NOT NULL,
+  user_id           TEXT NOT NULL,
+  home_id           TEXT NOT NULL,
+  label             TEXT NOT NULL,
+  recurrence        TEXT NOT NULL,
+  timezone          TEXT NOT NULL,
+  delivery_payload  TEXT NOT NULL,
+  next_fire_at      TEXT NOT NULL,
+  last_fired_at     TEXT,
+  enabled           INTEGER NOT NULL DEFAULT 1,
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL,
+  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
+  CHECK (enabled IN (0, 1))
+);
+
+CREATE INDEX IF NOT EXISTS idx_schedule_next_fire_at ON schedule(next_fire_at);
+CREATE INDEX IF NOT EXISTS idx_schedule_tenant_user ON schedule(tenant_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_schedule_home ON schedule(home_id);
+`);
+}
+/** v3 — cron fire idempotency ledger. The unique slot key is the load-bearing
+ *  restart/double-scan guard: one schedule can own only one fire per instant. */
+function scheduleFireTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS schedule_fire (
+  fire_id        TEXT PRIMARY KEY,
+  schedule_id    TEXT NOT NULL,
+  home_id        TEXT NOT NULL,
+  tenant_id      TEXT NOT NULL,
+  user_id        TEXT NOT NULL,
+  scheduled_for  TEXT NOT NULL,
+  state          TEXT NOT NULL DEFAULT 'pending',
+  attempts       INTEGER NOT NULL DEFAULT 0,
+  last_error     TEXT,
+  delivered_at   TEXT,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL,
+  FOREIGN KEY (schedule_id) REFERENCES schedule(schedule_id) ON DELETE CASCADE,
+  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
+  UNIQUE (schedule_id, scheduled_for),
+  CHECK (state IN ('pending', 'waking', 'delivered', 'failed')),
+  CHECK (attempts >= 0)
+);
+
+CREATE INDEX IF NOT EXISTS idx_schedule_fire_schedule ON schedule_fire(schedule_id);
+CREATE INDEX IF NOT EXISTS idx_schedule_fire_home ON schedule_fire(home_id);
+CREATE INDEX IF NOT EXISTS idx_schedule_fire_resumable ON schedule_fire(state, scheduled_for);
+CREATE INDEX IF NOT EXISTS idx_schedule_fire_tenant_user ON schedule_fire(tenant_id, user_id);
+`);
+}
+/** v4 — public ingress demux routes. `(channel, routing_key)` is deliberately
+ *  globally unique because public webhook/phone/email addresses are global. */
+function ingressRouteTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS ingress_route (
+  route_id            TEXT PRIMARY KEY,
+  tenant_id           TEXT NOT NULL,
+  user_id             TEXT NOT NULL,
+  home_id             TEXT NOT NULL,
+  channel             TEXT NOT NULL,
+  routing_key         TEXT NOT NULL,
+  routing_key_kind    TEXT NOT NULL,
+  channel_secret_ref  TEXT,
+  delivery_template   TEXT NOT NULL,
+  enabled             INTEGER NOT NULL DEFAULT 1,
+  created_at          TEXT NOT NULL,
+  updated_at          TEXT NOT NULL,
+  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
+  UNIQUE (channel, routing_key),
+  CHECK (enabled IN (0, 1))
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingress_route_lookup ON ingress_route(channel, routing_key);
+CREATE INDEX IF NOT EXISTS idx_ingress_route_tenant_user ON ingress_route(tenant_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_ingress_route_home ON ingress_route(home_id);
+`);
+}
+/** v5 — webhook replay/idempotency ledger. Stores delivery identity and hashes
+ *  only; raw public webhook bodies belong in the transient request path. */
+function webhookDeliveryTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS webhook_delivery (
+  delivery_id          TEXT PRIMARY KEY,
+  route_id             TEXT NOT NULL,
+  tenant_id            TEXT NOT NULL,
+  user_id              TEXT NOT NULL,
+  home_id              TEXT NOT NULL,
+  replay_key           TEXT NOT NULL,
+  replay_window_start  TEXT NOT NULL,
+  payload_sha256       TEXT,
+  signature_sha256     TEXT,
+  state                TEXT NOT NULL DEFAULT 'received',
+  received_at          TEXT NOT NULL,
+  delivered_at         TEXT,
+  last_error           TEXT,
+  created_at           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL,
+  FOREIGN KEY (route_id) REFERENCES ingress_route(route_id) ON DELETE CASCADE,
+  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
+  UNIQUE (route_id, replay_key, replay_window_start),
+  CHECK (state IN ('received', 'delivered', 'rejected', 'failed'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_delivery_route ON webhook_delivery(route_id, received_at);
+CREATE INDEX IF NOT EXISTS idx_webhook_delivery_home ON webhook_delivery(home_id, received_at);
+CREATE INDEX IF NOT EXISTS idx_webhook_delivery_tenant_user ON webhook_delivery(tenant_id, user_id);
+`);
+}
+/** v6 — append-only trigger delivery audit. Stores operational metadata and
+ *  content hashes; no public payload body and no secret literal columns. */
+function triggerAuditTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS trigger_audit (
+  audit_id        TEXT PRIMARY KEY,
+  tenant_id       TEXT NOT NULL,
+  user_id         TEXT NOT NULL,
+  home_id         TEXT NOT NULL,
+  source          TEXT NOT NULL,
+  source_ref      TEXT NOT NULL,
+  trigger_id      TEXT NOT NULL,
+  tier            TEXT NOT NULL,
+  outcome         TEXT NOT NULL,
+  reason          TEXT,
+  payload_sha256  TEXT,
+  metadata_json   TEXT,
+  at              TEXT NOT NULL,
+  FOREIGN KEY (home_id) REFERENCES home(home_id) ON DELETE CASCADE,
+  CHECK (source IN ('cron', 'webhook')),
+  CHECK (tier IN ('critical', 'urgent', 'normal', 'deferred')),
+  CHECK (outcome IN ('delivered', 'rejected', 'failed'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_trigger_audit_home_at ON trigger_audit(home_id, at);
+CREATE INDEX IF NOT EXISTS idx_trigger_audit_tenant_user_at ON trigger_audit(tenant_id, user_id, at);
+CREATE INDEX IF NOT EXISTS idx_trigger_audit_trigger ON trigger_audit(trigger_id);
+`);
+}
+/** v7 — DB-level consistency guards for denormalized tenant/user/home keys.
+ *  Stores derive these values from parents; these triggers keep direct SQL from
+ *  making tenant/user columns untrustworthy query or security boundaries. */
+function tenantIdentityTriggers(db) {
+    db.exec(`
+CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_insert
+BEFORE INSERT ON schedule
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM home
+  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'schedule tenant/user/home mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_update
+BEFORE UPDATE OF home_id, tenant_id, user_id ON schedule
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM home
+  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'schedule tenant/user/home mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_insert
+BEFORE INSERT ON schedule_fire
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM schedule
+  WHERE schedule_id = NEW.schedule_id
+    AND home_id = NEW.home_id
+    AND tenant_id = NEW.tenant_id
+    AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'schedule_fire schedule identity mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_update
+BEFORE UPDATE OF schedule_id, home_id, tenant_id, user_id ON schedule_fire
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM schedule
+  WHERE schedule_id = NEW.schedule_id
+    AND home_id = NEW.home_id
+    AND tenant_id = NEW.tenant_id
+    AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'schedule_fire schedule identity mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_insert
+BEFORE INSERT ON ingress_route
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM home
+  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'ingress_route tenant/user/home mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_update
+BEFORE UPDATE OF home_id, tenant_id, user_id ON ingress_route
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM home
+  WHERE home_id = NEW.home_id AND tenant_id = NEW.tenant_id AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'ingress_route tenant/user/home mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_webhook_delivery_identity_insert
+BEFORE INSERT ON webhook_delivery
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM ingress_route
+  WHERE route_id = NEW.route_id
+    AND home_id = NEW.home_id
+    AND tenant_id = NEW.tenant_id
+    AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'webhook_delivery route identity mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_webhook_delivery_identity_update
+BEFORE UPDATE OF route_id, home_id, tenant_id, user_id ON webhook_delivery
+FOR EACH ROW
+WHEN NOT EXISTS (
+  SELECT 1 FROM ingress_route
+  WHERE route_id = NEW.route_id
+    AND home_id = NEW.home_id
+    AND tenant_id = NEW.tenant_id
+    AND user_id = NEW.user_id
+)
+BEGIN
+  SELECT RAISE(ABORT, 'webhook_delivery route identity mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_trigger_audit_identity_insert
+BEFORE INSERT ON trigger_audit
+FOR EACH ROW
+WHEN (
+  NEW.source = 'cron'
+  AND NOT EXISTS (
+    SELECT 1 FROM schedule_fire
+    WHERE fire_id = NEW.source_ref
+      AND home_id = NEW.home_id
+      AND tenant_id = NEW.tenant_id
+      AND user_id = NEW.user_id
+  )
+) OR (
+  NEW.source = 'webhook'
+  AND NOT EXISTS (
+    SELECT 1 FROM ingress_route
+    WHERE route_id = NEW.source_ref
+      AND home_id = NEW.home_id
+      AND tenant_id = NEW.tenant_id
+      AND user_id = NEW.user_id
+  )
+)
+BEGIN
+  SELECT RAISE(ABORT, 'trigger_audit source identity mismatch');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_trigger_audit_identity_update
+BEFORE UPDATE OF source, source_ref, home_id, tenant_id, user_id ON trigger_audit
+FOR EACH ROW
+WHEN (
+  NEW.source = 'cron'
+  AND NOT EXISTS (
+    SELECT 1 FROM schedule_fire
+    WHERE fire_id = NEW.source_ref
+      AND home_id = NEW.home_id
+      AND tenant_id = NEW.tenant_id
+      AND user_id = NEW.user_id
+  )
+) OR (
+  NEW.source = 'webhook'
+  AND NOT EXISTS (
+    SELECT 1 FROM ingress_route
+    WHERE route_id = NEW.source_ref
+      AND home_id = NEW.home_id
+      AND tenant_id = NEW.tenant_id
+      AND user_id = NEW.user_id
+  )
+)
+BEGIN
+  SELECT RAISE(ABORT, 'trigger_audit source identity mismatch');
+END;
+`);
+}
+/** v8 — parent-identity update guards. v7 validates a child row's own
+ *  denormalized tenant/user/home tuple against its immediate parent on
+ *  INSERT/UPDATE, but said nothing about editing the PARENT side: nothing
+ *  stopped `UPDATE home SET tenant_id = ...` (or schedule/ingress_route/
+ *  schedule_fire identity columns) out from under existing children, which
+ *  would strand them with stale denormalized keys without tripping any
+ *  v7 check (those only fire on the child table). These triggers reject an
+ *  identity-column update on a parent row whenever a dependent child row
+ *  already exists, so identity is write-once after first child creation;
+ *  non-identity columns (status, timestamps, next_fire_at, metadata, etc.)
+ *  are untouched by these triggers and remain freely updatable. Each guard
+ *  checks only its immediate denormalizing child(ren) — sufficient because
+ *  v7 already keeps every deeper descendant's copy in lockstep with that
+ *  immediate child for as long as the immediate child row exists. */
+function parentIdentityUpdateGuards(db) {
+    db.exec(`
+CREATE TRIGGER IF NOT EXISTS trg_home_identity_update_guard
+BEFORE UPDATE OF tenant_id, user_id ON home
+FOR EACH ROW
+WHEN (NEW.tenant_id IS NOT OLD.tenant_id OR NEW.user_id IS NOT OLD.user_id)
+  AND (
+    EXISTS (SELECT 1 FROM schedule WHERE home_id = OLD.home_id)
+    OR EXISTS (SELECT 1 FROM ingress_route WHERE home_id = OLD.home_id)
+    OR EXISTS (SELECT 1 FROM trigger_audit WHERE home_id = OLD.home_id)
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'home identity update blocked: dependent schedule/ingress_route/trigger_audit rows exist');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_schedule_identity_update_guard
+BEFORE UPDATE OF home_id, tenant_id, user_id ON schedule
+FOR EACH ROW
+WHEN (
+    NEW.home_id IS NOT OLD.home_id
+    OR NEW.tenant_id IS NOT OLD.tenant_id
+    OR NEW.user_id IS NOT OLD.user_id
+  )
+  AND EXISTS (SELECT 1 FROM schedule_fire WHERE schedule_id = OLD.schedule_id)
+BEGIN
+  SELECT RAISE(ABORT, 'schedule identity update blocked: dependent schedule_fire rows exist');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_ingress_route_identity_update_guard
+BEFORE UPDATE OF home_id, tenant_id, user_id ON ingress_route
+FOR EACH ROW
+WHEN (
+    NEW.home_id IS NOT OLD.home_id
+    OR NEW.tenant_id IS NOT OLD.tenant_id
+    OR NEW.user_id IS NOT OLD.user_id
+  )
+  AND (
+    EXISTS (SELECT 1 FROM webhook_delivery WHERE route_id = OLD.route_id)
+    OR EXISTS (
+      SELECT 1 FROM trigger_audit WHERE source = 'webhook' AND source_ref = OLD.route_id
+    )
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'ingress_route identity update blocked: dependent webhook_delivery/trigger_audit rows exist');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_schedule_fire_identity_update_guard
+BEFORE UPDATE OF schedule_id, home_id, tenant_id, user_id ON schedule_fire
+FOR EACH ROW
+WHEN (
+    NEW.schedule_id IS NOT OLD.schedule_id
+    OR NEW.home_id IS NOT OLD.home_id
+    OR NEW.tenant_id IS NOT OLD.tenant_id
+    OR NEW.user_id IS NOT OLD.user_id
+  )
+  AND EXISTS (
+    SELECT 1 FROM trigger_audit WHERE source = 'cron' AND source_ref = OLD.fire_id
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'schedule_fire identity update blocked: dependent trigger_audit rows exist');
+END;
+`);
+}
+/** 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 const MIGRATIONS = [
+    /* v1 */ homeTable,
+    /* v2 */ scheduleTable,
+    /* v3 */ scheduleFireTable,
+    /* v4 */ ingressRouteTable,
+    /* v5 */ webhookDeliveryTable,
+    /* v6 */ triggerAuditTable,
+    /* v7 */ tenantIdentityTriggers,
+    /* v8 */ parentIdentityUpdateGuards,
+];
+/** 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 function migrate(db) {
+    let v = db.prepare('PRAGMA user_version').get().user_version;
+    for (; v < MIGRATIONS.length; v++) {
+        MIGRATIONS[v](db);
+        // `user_version` takes no bound parameters; v is a controlled integer.
+        db.exec(`PRAGMA user_version = ${v + 1}`);
+    }
+}
+const handles = new Map();
+/** 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 function openControlPlaneDb(path) {
+    const existing = handles.get(path);
+    if (existing) {
+        try {
+            existing.prepare('PRAGMA database_list').all();
+            return existing;
+        }
+        catch {
+            try {
+                existing.close();
+            }
+            catch {
+                /* ignore */
+            }
+            handles.delete(path);
+        }
+    }
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec('PRAGMA busy_timeout = 5000;');
+    migrate(db);
+    handles.set(path, db);
+    return db;
+}
+/** 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 function getControlPlaneDb(env = process.env) {
+    return openControlPlaneDb(controlPlaneDbPath(env));
+}
+/** Close and forget the handle for `path` (defaults to the standard
+ *  resolved path). Mainly for tests. */
+export function closeControlPlaneDb(path = controlPlaneDbPath()) {
+    const db = handles.get(path);
+    if (db) {
+        db.close();
+        handles.delete(path);
+    }
+}

package/dist/hearth/control-plane/ingress/rate-limit.d.ts

@@ -0,0 +1,24 @@
+export interface RateLimiterConfig {
+    /** Per-key burst size (max tokens for one routing key). */
+    capacity: number;
+    /** Per-key steady-state refill rate (tokens/second). */
+    refillPerSec: number;
+    /** Global burst ceiling across all keys. */
+    globalCapacity: number;
+    /** Global steady-state refill rate (tokens/second). */
+    globalRefillPerSec: number;
+    /** Injectable clock for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface RateCheckResult {
+    ok: boolean;
+    retryAfterMs?: number;
+}
+export declare function loadRateLimiterConfig(env?: NodeJS.ProcessEnv): RateLimiterConfig;
+export interface RateLimiter {
+    checkRate(key: string): RateCheckResult;
+}
+/** Build a token-bucket rate limiter. Each distinct `key` gets its own bucket
+ *  plus a single shared global bucket; a request must draw one token from BOTH
+ *  to pass. */
+export declare function createRateLimiter(config: RateLimiterConfig): RateLimiter;

package/dist/hearth/control-plane/ingress/rate-limit.js

@@ -0,0 +1,100 @@
+// control-plane/ingress/rate-limit.ts — the R-TRIG-4 pre-resolution ingress
+// rate limiter (master plan P5.2). Burst protection on inbound ingress ONLY,
+// evaluated BEFORE any route lookup / secret resolution / DB write, so a flood
+// against an unknown or unverified routing key is shed cheaply and can never
+// amplify into DB work.
+//
+// An in-memory token bucket keyed by the caller-supplied key (the ingress
+// `routing_key`) plus a coarse GLOBAL ceiling. In-memory is acceptable this
+// increment because the CP is a single always-on instance (design D1 / R-CP-1,
+// HA out of scope) — there is no distributed limiter to coordinate. Detailed
+// backoff tuning is out of scope (part-plan gap note 3): sane defaults only.
+const ENV = {
+    capacity: 'CRTR_HEARTH_CP_WEBHOOK_RATE_CAPACITY',
+    refillPerSec: 'CRTR_HEARTH_CP_WEBHOOK_RATE_REFILL_PER_SEC',
+    globalCapacity: 'CRTR_HEARTH_CP_WEBHOOK_RATE_GLOBAL_CAPACITY',
+    globalRefillPerSec: 'CRTR_HEARTH_CP_WEBHOOK_RATE_GLOBAL_REFILL_PER_SEC',
+};
+const DEFAULTS = {
+    capacity: 20,
+    refillPerSec: 5,
+    globalCapacity: 200,
+    globalRefillPerSec: 50,
+};
+function parsePositive(value, fallback) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+export function loadRateLimiterConfig(env = process.env) {
+    return {
+        capacity: parsePositive(env[ENV.capacity], DEFAULTS.capacity),
+        refillPerSec: parsePositive(env[ENV.refillPerSec], DEFAULTS.refillPerSec),
+        globalCapacity: parsePositive(env[ENV.globalCapacity], DEFAULTS.globalCapacity),
+        globalRefillPerSec: parsePositive(env[ENV.globalRefillPerSec], DEFAULTS.globalRefillPerSec),
+    };
+}
+/** Bound on distinct live per-key buckets before an idle sweep runs. A sweep
+ *  drops any bucket that has refilled back to full capacity (i.e. been idle
+ *  long enough to be indistinguishable from a fresh one), so an attacker
+ *  cycling through unbounded distinct routing keys cannot grow the map without
+ *  limit — they are already shed by the global ceiling. */
+const MAX_KEY_BUCKETS = 10_000;
+/** Build a token-bucket rate limiter. Each distinct `key` gets its own bucket
+ *  plus a single shared global bucket; a request must draw one token from BOTH
+ *  to pass. */
+export function createRateLimiter(config) {
+    const now = config.now ?? (() => Date.now());
+    const keyBuckets = new Map();
+    const globalBucket = { tokens: config.globalCapacity, lastRefillMs: now() };
+    function refill(bucket, capacity, refillPerSec, atMs) {
+        const elapsedSec = Math.max(0, (atMs - bucket.lastRefillMs) / 1000);
+        bucket.tokens = Math.min(capacity, bucket.tokens + elapsedSec * refillPerSec);
+        bucket.lastRefillMs = atMs;
+    }
+    function retryAfterMs(deficit, refillPerSec) {
+        return Math.max(1, Math.ceil((deficit / refillPerSec) * 1000));
+    }
+    /** Drop every key bucket that has refilled to full capacity as of `atMs` —
+     *  such a bucket is behaviourally identical to a fresh one, so removing it
+     *  loses no rate state while reclaiming memory. Active (partially-drained)
+     *  buckets are kept so their limits still bite. */
+    function sweepIdle(atMs) {
+        for (const [key, bucket] of keyBuckets) {
+            refill(bucket, config.capacity, config.refillPerSec, atMs);
+            if (bucket.tokens >= config.capacity)
+                keyBuckets.delete(key);
+        }
+    }
+    return {
+        checkRate(key) {
+            const atMs = now();
+            // Global ceiling first — a flood across many keys is shed even if each
+            // individual key is under its own limit.
+            refill(globalBucket, config.globalCapacity, config.globalRefillPerSec, atMs);
+            if (globalBucket.tokens < 1) {
+                return { ok: false, retryAfterMs: retryAfterMs(1 - globalBucket.tokens, config.globalRefillPerSec) };
+            }
+            let bucket = keyBuckets.get(key);
+            if (bucket === undefined) {
+                if (keyBuckets.size >= MAX_KEY_BUCKETS)
+                    sweepIdle(atMs);
+                bucket = { tokens: config.capacity, lastRefillMs: atMs };
+                keyBuckets.set(key, bucket);
+            }
+            else {
+                refill(bucket, config.capacity, config.refillPerSec, atMs);
+            }
+            if (bucket.tokens < 1) {
+                return { ok: false, retryAfterMs: retryAfterMs(1 - bucket.tokens, config.refillPerSec) };
+            }
+            // Draw from both buckets only when both admit the request.
+            bucket.tokens -= 1;
+            globalBucket.tokens -= 1;
+            return { ok: true };
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+export type IngressChannel = 'webhook' | 'sms' | 'email' | `chat-${string}` | 'discord-gateway' | 'imap-idle';
+export interface IngressRouteRow {
+    route_id: string;
+    tenant_id: string;
+    user_id: string;
+    home_id: string;
+    channel: IngressChannel;
+    routing_key: string;
+    routing_key_kind: string;
+    channel_secret_ref: string | null;
+    delivery_template: unknown;
+    enabled: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface RegisterRouteInput {
+    route_id?: string;
+    home_id: string;
+    channel: IngressChannel;
+    routing_key: string;
+    routing_key_kind: string;
+    channel_secret_ref?: string | null;
+    delivery_template: unknown;
+    enabled?: boolean;
+    now?: string;
+}
+export declare function registerRoute(input: RegisterRouteInput): IngressRouteRow;
+export declare function getRouteById(routeId: string): IngressRouteRow | null;
+export declare function resolveRoute(channel: IngressChannel, routingKey: string): IngressRouteRow | null;
+export declare function listRoutesForUser(tenantId: string, userId: string): IngressRouteRow[];
+export declare function setRouteEnabled(routeId: string, enabled: boolean, now?: string): void;