@crouton-kit/crouter 0.3.40 → 0.3.41

package/dist/hearth/control-plane/scheduler/fire-store.d.ts

@@ -1,36 +0,0 @@
-export type ScheduleFireState = 'pending' | 'waking' | 'delivered' | 'failed';
-export interface ScheduleFireRow {
-    fire_id: string;
-    schedule_id: string;
-    home_id: string;
-    tenant_id: string;
-    user_id: string;
-    scheduled_for: string;
-    state: ScheduleFireState;
-    attempts: number;
-    last_error: string | null;
-    delivered_at: string | null;
-    created_at: string;
-    updated_at: string;
-}
-export interface ClaimFireInput {
-    fire_id?: string;
-    schedule_id: string;
-    scheduled_for: string;
-    now?: string;
-}
-export interface ClaimFireResult {
-    fire: ScheduleFireRow;
-    claimed: boolean;
-}
-export interface SetFireStateOptions {
-    last_error?: string | null;
-    delivered_at?: string | null;
-    increment_attempts?: boolean;
-    now?: string;
-}
-export declare function claimFire(input: ClaimFireInput): ClaimFireResult;
-export declare function getFireById(fireId: string): ScheduleFireRow | null;
-export declare function getFireByScheduleSlot(scheduleId: string, scheduledFor: string): ScheduleFireRow | null;
-export declare function setFireState(fireId: string, state: ScheduleFireState, options?: SetFireStateOptions): void;
-export declare function selectResumableFires(limit?: number): ScheduleFireRow[];

package/dist/hearth/control-plane/scheduler/fire-store.js

@@ -1,73 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { getControlPlaneDb } from '../db.js';
-function nowIso() {
-    return new Date().toISOString();
-}
-function scheduleIdentity(scheduleId) {
-    const row = getControlPlaneDb()
-        .prepare('SELECT home_id, tenant_id, user_id FROM schedule WHERE schedule_id = ?')
-        .get(scheduleId);
-    if (row === undefined)
-        throw new Error(`schedule not found: ${scheduleId}`);
-    return row;
-}
-function fireFrom(row) {
-    return {
-        fire_id: row['fire_id'],
-        schedule_id: row['schedule_id'],
-        home_id: row['home_id'],
-        tenant_id: row['tenant_id'],
-        user_id: row['user_id'],
-        scheduled_for: row['scheduled_for'],
-        state: row['state'],
-        attempts: Number(row['attempts']),
-        last_error: row['last_error'] ?? null,
-        delivered_at: row['delivered_at'] ?? null,
-        created_at: row['created_at'],
-        updated_at: row['updated_at'],
-    };
-}
-export function claimFire(input) {
-    const fireId = input.fire_id ?? `fire-${randomUUID()}`;
-    const stamped = input.now ?? nowIso();
-    const identity = scheduleIdentity(input.schedule_id);
-    const result = getControlPlaneDb()
-        .prepare(`INSERT OR IGNORE INTO schedule_fire (
-         fire_id, schedule_id, home_id, tenant_id, user_id, scheduled_for,
-         state, attempts, last_error, delivered_at, created_at, updated_at
-       ) VALUES (?, ?, ?, ?, ?, ?, 'pending', 0, NULL, NULL, ?, ?)`)
-        .run(fireId, input.schedule_id, identity.home_id, identity.tenant_id, identity.user_id, input.scheduled_for, stamped, stamped);
-    const fire = getFireByScheduleSlot(input.schedule_id, input.scheduled_for);
-    if (fire === null)
-        throw new Error(`failed to claim schedule fire ${input.schedule_id} at ${input.scheduled_for}`);
-    return { fire, claimed: result.changes === 1 };
-}
-export function getFireById(fireId) {
-    const row = getControlPlaneDb().prepare('SELECT * FROM schedule_fire WHERE fire_id = ?').get(fireId);
-    return row === undefined ? null : fireFrom(row);
-}
-export function getFireByScheduleSlot(scheduleId, scheduledFor) {
-    const row = getControlPlaneDb()
-        .prepare('SELECT * FROM schedule_fire WHERE schedule_id = ? AND scheduled_for = ?')
-        .get(scheduleId, scheduledFor);
-    return row === undefined ? null : fireFrom(row);
-}
-export function setFireState(fireId, state, options = {}) {
-    const stamped = options.now ?? nowIso();
-    const deliveredAt = options.delivered_at === undefined ? (state === 'delivered' ? stamped : null) : options.delivered_at;
-    getControlPlaneDb()
-        .prepare(`UPDATE schedule_fire
-       SET state = ?,
-           attempts = attempts + ?,
-           last_error = ?,
-           delivered_at = COALESCE(?, delivered_at),
-           updated_at = ?
-       WHERE fire_id = ?`)
-        .run(state, options.increment_attempts === true ? 1 : 0, options.last_error ?? null, deliveredAt, stamped, fireId);
-}
-export function selectResumableFires(limit = 100) {
-    const rows = getControlPlaneDb()
-        .prepare("SELECT * FROM schedule_fire WHERE state IN ('pending', 'waking') ORDER BY scheduled_for LIMIT ?")
-        .all(limit);
-    return rows.map(fireFrom);
-}

package/dist/hearth/control-plane/scheduler/recurrence.d.ts

@@ -1,7 +0,0 @@
-/**
- * Compute the next fire instant strictly after `after` for `recurrence` in
- * `timezone`, returned as an ISO-8601 UTC string. `after` is an ISO string
- * (typically the just-fired `next_fire_at`, so the advanced slot is strictly
- * in the future and the scan loop cannot re-select it).
- */
-export declare function computeNextFire(recurrence: string, timezone: string, after: string): string;

package/dist/hearth/control-plane/scheduler/recurrence.js

@@ -1,58 +0,0 @@
-// control-plane/scheduler/recurrence.ts — next-fire computation for a
-// `schedule.recurrence` (master plan P5.4). Timezone-aware, using the vetted
-// `cron-parser` rather than a hand-rolled cron implementation.
-//
-// Two recurrence forms are accepted:
-//   - a standard 5- or 6-field cron expression ("*/5 * * * *", "0 9 * * 1-5"),
-//     evaluated in `timezone`;
-//   - a fixed interval "@every <n><unit>" where unit is s/m/h/d
-//     ("@every 30m", "@every 90s"), timezone-independent.
-// Anything else throws — an unparseable recurrence is an operator error, not
-// something to silently skip.
-import { CronExpressionParser } from 'cron-parser';
-import { general } from '../../../core/errors.js';
-const INTERVAL_UNIT_MS = {
-    s: 1_000,
-    m: 60_000,
-    h: 3_600_000,
-    d: 86_400_000,
-};
-function parseIntervalMs(spec) {
-    const match = /^@every\s+(\d+)\s*([smhd])$/.exec(spec.trim());
-    if (match === null)
-        return null;
-    const quantity = Number(match[1]);
-    const unitMs = INTERVAL_UNIT_MS[match[2]];
-    const totalMs = quantity * unitMs;
-    if (totalMs <= 0)
-        return null;
-    return totalMs;
-}
-/**
- * Compute the next fire instant strictly after `after` for `recurrence` in
- * `timezone`, returned as an ISO-8601 UTC string. `after` is an ISO string
- * (typically the just-fired `next_fire_at`, so the advanced slot is strictly
- * in the future and the scan loop cannot re-select it).
- */
-export function computeNextFire(recurrence, timezone, after) {
-    const afterDate = new Date(after);
-    if (Number.isNaN(afterDate.getTime())) {
-        throw general(`invalid "after" instant for recurrence computation: ${after}`, { after });
-    }
-    const intervalMs = parseIntervalMs(recurrence);
-    if (intervalMs !== null) {
-        return new Date(afterDate.getTime() + intervalMs).toISOString();
-    }
-    let interval;
-    try {
-        interval = CronExpressionParser.parse(recurrence, { currentDate: afterDate, tz: timezone });
-    }
-    catch (error) {
-        throw general(`invalid cron recurrence: ${recurrence}`, {
-            recurrence,
-            timezone,
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
-    return interval.next().toDate().toISOString();
-}

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

@@ -1,38 +0,0 @@
-import { advanceNextFire, type ScheduleRow } from './schedule-store.js';
-import { claimFire, setFireState, type ScheduleFireRow } from './fire-store.js';
-import { computeNextFire } from './recurrence.js';
-import { buildTriggerEnvelope } from '../triggers/envelope.js';
-import { type DeliverTriggerResult } from '../triggers/deliver.js';
-export interface SchedulerLoopDeps {
-    selectDueSchedules: (now: string) => ScheduleRow[];
-    getScheduleById: (scheduleId: string) => ScheduleRow | null;
-    claimFire: typeof claimFire;
-    setFireState: typeof setFireState;
-    advanceNextFire: typeof advanceNextFire;
-    selectResumableFires: () => ScheduleFireRow[];
-    computeNextFire: typeof computeNextFire;
-    deliverTrigger: (input: {
-        home_id: string;
-        source_ref: string;
-        envelope: ReturnType<typeof buildTriggerEnvelope>;
-        tier: 'urgent';
-        metadata?: Record<string, unknown>;
-    }) => Promise<DeliverTriggerResult>;
-    now: () => string;
-    intervalMs: number;
-}
-/** Production defaults — every dep resolves to the real store/chokepoint. A
- *  test injects fakes for all of them. */
-export declare function defaultSchedulerLoopDeps(): SchedulerLoopDeps;
-/** One full scan pass: restart-recovery first, then due-schedule firing. */
-export declare function runSchedulerScan(deps: SchedulerLoopDeps): Promise<void>;
-export interface SchedulerLoopHandle {
-    stop: () => void;
-}
-/**
- * Start the scan loop: run one pass immediately, then every `intervalMs`.
- * Passes never overlap (a `running` guard skips a tick still in flight).
- * Returns a handle whose `stop()` clears the interval — no timer is left
- * armed after `stop()`.
- */
-export declare function startSchedulerLoop(deps?: SchedulerLoopDeps): SchedulerLoopHandle;

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

@@ -1,138 +0,0 @@
-// control-plane/scheduler/scan-loop.ts — the always-on cron scan loop
-// (master plan P5.4 / part-plan T-C1). On an interval (and once at startup):
-//
-//   1. RESTART RECOVERY FIRST: `selectResumableFires()` returns any fire left
-//      in `pending|waking` by a CP that crashed mid-fire; re-drive each to a
-//      terminal state. The unique `(schedule_id, scheduled_for)` slot means a
-//      crashed fire is never re-CLAIMED — it is re-DELIVERED (at-least-once;
-//      the home dedupes on `trigger_id == fire_id`), so a mid-fire restart
-//      yields exactly one delivery, never a double.
-//   2. `selectDueSchedules(now)`: for each due schedule, `claimFire` the slot.
-//      A won claim advances `next_fire_at` (so the slot cannot be re-selected)
-//      then delivers; a lost claim (another pass owns it) is skipped.
-//
-// Delivery ALWAYS goes through the shared `deliverTrigger` chokepoint with
-// tier `urgent` (R-TRIG-3) and `trigger_id == fire_id` (R-CRON-5). On failure
-// the fire is marked `failed` with the error and an incremented attempt count;
-// there is NO backoff/retry schedule (part-plan gap 3) — the schedule's next
-// natural `next_fire_at` tick is the only re-fire.
-import { advanceNextFire, getScheduleById, selectDueSchedules } from './schedule-store.js';
-import { claimFire, selectResumableFires, setFireState } from './fire-store.js';
-import { computeNextFire } from './recurrence.js';
-import { buildTriggerEnvelope } from '../triggers/envelope.js';
-import { deliverTrigger } from '../triggers/deliver.js';
-const DEFAULT_SCAN_INTERVAL_MS = 15_000;
-/** Production defaults — every dep resolves to the real store/chokepoint. A
- *  test injects fakes for all of them. */
-export function defaultSchedulerLoopDeps() {
-    return {
-        selectDueSchedules,
-        getScheduleById,
-        claimFire,
-        setFireState,
-        advanceNextFire,
-        selectResumableFires,
-        computeNextFire,
-        deliverTrigger: (input) => deliverTrigger(input),
-        now: () => new Date().toISOString(),
-        intervalMs: DEFAULT_SCAN_INTERVAL_MS,
-    };
-}
-/** Deliver one already-claimed fire. Marks `waking`, builds the cron envelope
- *  (trigger_id == fire_id), delivers through the chokepoint at `urgent`, and
- *  records the terminal fire state. Never throws — a delivery failure is
- *  recorded on the fire, not propagated, so one bad fire cannot abort the
- *  whole scan. */
-async function deliverFire(deps, fire, schedule) {
-    deps.setFireState(fire.fire_id, 'waking');
-    const envelope = buildTriggerEnvelope({
-        source: 'cron',
-        trigger_id: fire.fire_id,
-        payload: schedule.delivery_payload,
-        received_at: deps.now(),
-    });
-    try {
-        const result = await deps.deliverTrigger({
-            home_id: fire.home_id,
-            source_ref: fire.fire_id,
-            envelope,
-            tier: 'urgent',
-            metadata: { schedule_id: schedule.schedule_id, label: schedule.label },
-        });
-        if (result.outcome === 'delivered') {
-            deps.setFireState(fire.fire_id, 'delivered');
-        }
-        else {
-            deps.setFireState(fire.fire_id, 'failed', {
-                last_error: result.reason ?? result.outcome,
-                increment_attempts: true,
-            });
-        }
-    }
-    catch (error) {
-        deps.setFireState(fire.fire_id, 'failed', {
-            last_error: error instanceof Error ? error.message : String(error),
-            increment_attempts: true,
-        });
-    }
-}
-/** Re-drive a fire left `pending|waking` by a crashed CP. Loads its schedule
- *  for the payload and re-delivers; a schedule deleted out from under a
- *  stranded fire marks the fire `failed` rather than looping forever. */
-async function resumeFire(deps, fire) {
-    const schedule = deps.getScheduleById(fire.schedule_id);
-    if (schedule === null) {
-        deps.setFireState(fire.fire_id, 'failed', { last_error: 'schedule deleted before fire completed', increment_attempts: true });
-        return;
-    }
-    await deliverFire(deps, fire, schedule);
-}
-/** One full scan pass: restart-recovery first, then due-schedule firing. */
-export async function runSchedulerScan(deps) {
-    for (const fire of deps.selectResumableFires()) {
-        await resumeFire(deps, fire);
-    }
-    const now = deps.now();
-    for (const schedule of deps.selectDueSchedules(now)) {
-        const claim = deps.claimFire({ schedule_id: schedule.schedule_id, scheduled_for: schedule.next_fire_at });
-        if (!claim.claimed)
-            continue; // another pass owns this slot.
-        // Advance the durable timer BEFORE delivery so the slot cannot be
-        // re-selected on the next scan even if delivery is slow.
-        const nextFireAt = deps.computeNextFire(schedule.recurrence, schedule.timezone, schedule.next_fire_at);
-        deps.advanceNextFire(schedule.schedule_id, nextFireAt, schedule.next_fire_at);
-        await deliverFire(deps, claim.fire, schedule);
-    }
-}
-/**
- * Start the scan loop: run one pass immediately, then every `intervalMs`.
- * Passes never overlap (a `running` guard skips a tick still in flight).
- * Returns a handle whose `stop()` clears the interval — no timer is left
- * armed after `stop()`.
- */
-export function startSchedulerLoop(deps = defaultSchedulerLoopDeps()) {
-    let running = false;
-    let stopped = false;
-    const tick = () => {
-        if (running || stopped)
-            return;
-        running = true;
-        void runSchedulerScan(deps)
-            .catch((error) => {
-            process.stderr.write(`${JSON.stringify({ level: 'error', message: 'hearth scheduler scan failed', error: error instanceof Error ? error.message : String(error) })}\n`);
-        })
-            .finally(() => {
-            running = false;
-        });
-    };
-    const timer = setInterval(tick, deps.intervalMs);
-    // Do not keep the process alive solely for the scan timer.
-    timer.unref?.();
-    tick();
-    return {
-        stop: () => {
-            stopped = true;
-            clearInterval(timer);
-        },
-    };
-}

package/dist/hearth/control-plane/scheduler/schedule-store.d.ts

@@ -1,32 +0,0 @@
-export interface ScheduleRow {
-    schedule_id: string;
-    tenant_id: string;
-    user_id: string;
-    home_id: string;
-    label: string;
-    recurrence: string;
-    timezone: string;
-    delivery_payload: unknown;
-    next_fire_at: string;
-    last_fired_at: string | null;
-    enabled: boolean;
-    created_at: string;
-    updated_at: string;
-}
-export interface CreateScheduleInput {
-    schedule_id?: string;
-    home_id: string;
-    label: string;
-    recurrence: string;
-    timezone: string;
-    delivery_payload: unknown;
-    next_fire_at: string;
-    enabled?: boolean;
-    now?: string;
-}
-export declare function createSchedule(input: CreateScheduleInput): ScheduleRow;
-export declare function getScheduleById(scheduleId: string): ScheduleRow | null;
-export declare function selectDueSchedules(now: string, limit?: number): ScheduleRow[];
-export declare function listSchedulesForUser(tenantId: string, userId: string): ScheduleRow[];
-export declare function advanceNextFire(scheduleId: string, nextFireAt: string, lastFiredAt: string, now?: string): void;
-export declare function setScheduleEnabled(scheduleId: string, enabled: boolean, now?: string): void;

package/dist/hearth/control-plane/scheduler/schedule-store.js

@@ -1,66 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { getControlPlaneDb } from '../db.js';
-function nowIso() {
-    return new Date().toISOString();
-}
-function homeIdentity(homeId) {
-    const row = getControlPlaneDb().prepare('SELECT tenant_id, user_id FROM home WHERE home_id = ?').get(homeId);
-    if (row === undefined)
-        throw new Error(`home not found: ${homeId}`);
-    return row;
-}
-function scheduleFrom(row) {
-    return {
-        schedule_id: row['schedule_id'],
-        tenant_id: row['tenant_id'],
-        user_id: row['user_id'],
-        home_id: row['home_id'],
-        label: row['label'],
-        recurrence: row['recurrence'],
-        timezone: row['timezone'],
-        delivery_payload: JSON.parse(row['delivery_payload']),
-        next_fire_at: row['next_fire_at'],
-        last_fired_at: row['last_fired_at'] ?? null,
-        enabled: Number(row['enabled']) !== 0,
-        created_at: row['created_at'],
-        updated_at: row['updated_at'],
-    };
-}
-export function createSchedule(input) {
-    const scheduleId = input.schedule_id ?? `sch-${randomUUID()}`;
-    const stamped = input.now ?? nowIso();
-    const identity = homeIdentity(input.home_id);
-    getControlPlaneDb()
-        .prepare(`INSERT INTO schedule (
-         schedule_id, tenant_id, user_id, home_id, label, recurrence, timezone,
-         delivery_payload, next_fire_at, last_fired_at, enabled, created_at, updated_at
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)`)
-        .run(scheduleId, identity.tenant_id, identity.user_id, input.home_id, input.label, input.recurrence, input.timezone, JSON.stringify(input.delivery_payload), input.next_fire_at, input.enabled === false ? 0 : 1, stamped, stamped);
-    return getScheduleById(scheduleId);
-}
-export function getScheduleById(scheduleId) {
-    const row = getControlPlaneDb().prepare('SELECT * FROM schedule WHERE schedule_id = ?').get(scheduleId);
-    return row === undefined ? null : scheduleFrom(row);
-}
-export function selectDueSchedules(now, limit = 100) {
-    const rows = getControlPlaneDb()
-        .prepare('SELECT * FROM schedule WHERE enabled = 1 AND next_fire_at <= ? ORDER BY next_fire_at LIMIT ?')
-        .all(now, limit);
-    return rows.map(scheduleFrom);
-}
-export function listSchedulesForUser(tenantId, userId) {
-    const rows = getControlPlaneDb()
-        .prepare('SELECT * FROM schedule WHERE tenant_id = ? AND user_id = ? ORDER BY next_fire_at')
-        .all(tenantId, userId);
-    return rows.map(scheduleFrom);
-}
-export function advanceNextFire(scheduleId, nextFireAt, lastFiredAt, now = nowIso()) {
-    getControlPlaneDb()
-        .prepare('UPDATE schedule SET next_fire_at = ?, last_fired_at = ?, updated_at = ? WHERE schedule_id = ?')
-        .run(nextFireAt, lastFiredAt, now, scheduleId);
-}
-export function setScheduleEnabled(scheduleId, enabled, now = nowIso()) {
-    getControlPlaneDb()
-        .prepare('UPDATE schedule SET enabled = ?, updated_at = ? WHERE schedule_id = ?')
-        .run(enabled ? 1 : 0, now, scheduleId);
-}

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

@@ -1,31 +0,0 @@
-/** Resolve a `relay_auth_ref`/`channel_secret_ref` handle to its live secret
- *  value. Never reads the CP DB — the DB holds only the handle string; this
- *  is the only path that turns it into a value (S4/S5 in the registry/relay
- *  part-plan). Lookup order: an explicit per-handle env override
- *  (`CRTR_HEARTH_CP_SECRET_<SANITIZED_HANDLE>`), then the secrets file
- *  (`CRTR_HEARTH_CP_SECRETS_FILE`, default beside the CP data dir). Throws on
- *  an unknown handle — the thrown message never includes a resolved value,
- *  only the handle name. */
-export declare function resolveSecret(handle: string, env?: NodeJS.ProcessEnv): string;
-/** The secret HANDLE for the CP admin bearer token that gates the
- *  `POST /__admin/*` ingress (the image workflow's push-notify, design
- *  §2-C). Resolves through the SAME `resolveSecret` seam as every other CP
- *  handle: the per-handle env override
- *  `CRTR_HEARTH_CP_SECRET_HEARTH_CP_ADMIN_TOKEN`, else the `HEARTH_CP_ADMIN_TOKEN`
- *  key in the CP secrets file. The GitHub repo secret `HEARTH_CP_ADMIN_TOKEN`
- *  and the deployed Fly CP must carry the SAME value. */
-export declare const HEARTH_CP_ADMIN_TOKEN_HANDLE = "HEARTH_CP_ADMIN_TOKEN";
-/** Resolve the CP admin bearer token, or `null` when it is not configured.
- *  Unlike `resolveSecret` (which throws on an unknown handle), this returns
- *  `null` so the admin route can FAIL CLOSED — a CP with no admin token
- *  configured rejects every `/__admin/*` request rather than crashing the
- *  request handler. Never logs the value. */
-export declare function resolveCpAdminToken(env?: NodeJS.ProcessEnv): string | null;
-/** Redact every secret value resolved so far this process out of a log
- *  line/message. CP code building a log line from data that may carry a
- *  resolved secret (e.g. an upstream request trace) MUST pass it through this
- *  before writing it — never log a resolved value directly. */
-export declare function redactSecrets(message: string): string;
-/** Test-only: clear the in-memory file cache + redaction set so a test run
- *  with a different env/file doesn't see a prior run's cached state. */
-export declare function resetSecretsCacheForTests(): void;

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

@@ -1,134 +0,0 @@
-// CP secret-handle resolution (P1.3). The `home` table (and the channel
-// tables that follow it) stores secret material only as an opaque HANDLE
-// (`relay_auth_ref`, `channel_secret_ref`) — never the secret itself (R-CP-8).
-// This module is the one seam that turns a handle into a live value, sourced
-// from the process env or a flat JSON file for the dogfood cutover (M0 used
-// Fly secrets behind the same shape). Dogfood may keep that file beside the
-// CP SQLite data volume — that is operational indirection for ops
-// convenience, not a host-compromise security boundary.
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { general } from '../../core/errors.js';
-const ENV = {
-    // Explicit override: a flat JSON file mapping handle -> secret value.
-    secretsFile: 'CRTR_HEARTH_CP_SECRETS_FILE',
-    // Where the CP keeps its SQLite data (db.ts will read the same root); the
-    // secrets file defaults to living beside it when no explicit file is set.
-    dataDir: 'CRTR_HEARTH_CP_DATA_DIR',
-};
-const SECRETS_FILE_NAME = 'secrets.json';
-function expandHomePath(input) {
-    if (input.startsWith('~'))
-        return join(homedir(), input.slice(1));
-    return resolve(input);
-}
-function defaultSecretsFilePath(env) {
-    const dataDir = env[ENV.dataDir]?.trim();
-    const base = dataDir !== undefined && dataDir !== '' ? expandHomePath(dataDir) : expandHomePath('~/.crouter/hearth-control-plane');
-    return join(base, SECRETS_FILE_NAME);
-}
-function secretsFilePath(env) {
-    const override = env[ENV.secretsFile]?.trim();
-    return override !== undefined && override !== '' ? expandHomePath(override) : defaultSecretsFilePath(env);
-}
-function sanitizeHandleForEnvName(handle) {
-    return handle.trim().toUpperCase().replace(/[^A-Z0-9]+/g, '_');
-}
-function perHandleEnvName(handle) {
-    return `CRTR_HEARTH_CP_SECRET_${sanitizeHandleForEnvName(handle)}`;
-}
-let fileCache = null;
-function loadSecretsFile(env) {
-    const path = secretsFilePath(env);
-    if (fileCache !== null && fileCache.path === path)
-        return fileCache.values;
-    if (!existsSync(path)) {
-        fileCache = { path, values: {} };
-        return fileCache.values;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        throw general(`invalid secrets file (not valid JSON): ${path}`, { path });
-    }
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw general(`secrets file must be a flat JSON object of handle -> value: ${path}`, { path });
-    }
-    const values = {};
-    for (const [key, value] of Object.entries(parsed)) {
-        if (typeof value === 'string' && value !== '')
-            values[key] = value;
-    }
-    fileCache = { path, values };
-    return values;
-}
-// Every value resolved this process, kept only to redact them back out of
-// log lines. Never logged or persisted itself.
-const resolvedValues = new Set();
-/** Resolve a `relay_auth_ref`/`channel_secret_ref` handle to its live secret
- *  value. Never reads the CP DB — the DB holds only the handle string; this
- *  is the only path that turns it into a value (S4/S5 in the registry/relay
- *  part-plan). Lookup order: an explicit per-handle env override
- *  (`CRTR_HEARTH_CP_SECRET_<SANITIZED_HANDLE>`), then the secrets file
- *  (`CRTR_HEARTH_CP_SECRETS_FILE`, default beside the CP data dir). Throws on
- *  an unknown handle — the thrown message never includes a resolved value,
- *  only the handle name. */
-export function resolveSecret(handle, env = process.env) {
-    const trimmed = handle.trim();
-    if (trimmed === '')
-        throw general('secret handle must not be empty');
-    const envOverride = env[perHandleEnvName(trimmed)];
-    if (envOverride !== undefined && envOverride.trim() !== '') {
-        resolvedValues.add(envOverride);
-        return envOverride;
-    }
-    const fromFile = loadSecretsFile(env)[trimmed];
-    if (fromFile !== undefined) {
-        resolvedValues.add(fromFile);
-        return fromFile;
-    }
-    throw general(`unknown secret handle: ${trimmed}`, { handle: trimmed });
-}
-/** The secret HANDLE for the CP admin bearer token that gates the
- *  `POST /__admin/*` ingress (the image workflow's push-notify, design
- *  §2-C). Resolves through the SAME `resolveSecret` seam as every other CP
- *  handle: the per-handle env override
- *  `CRTR_HEARTH_CP_SECRET_HEARTH_CP_ADMIN_TOKEN`, else the `HEARTH_CP_ADMIN_TOKEN`
- *  key in the CP secrets file. The GitHub repo secret `HEARTH_CP_ADMIN_TOKEN`
- *  and the deployed Fly CP must carry the SAME value. */
-export const HEARTH_CP_ADMIN_TOKEN_HANDLE = 'HEARTH_CP_ADMIN_TOKEN';
-/** Resolve the CP admin bearer token, or `null` when it is not configured.
- *  Unlike `resolveSecret` (which throws on an unknown handle), this returns
- *  `null` so the admin route can FAIL CLOSED — a CP with no admin token
- *  configured rejects every `/__admin/*` request rather than crashing the
- *  request handler. Never logs the value. */
-export function resolveCpAdminToken(env = process.env) {
-    try {
-        return resolveSecret(HEARTH_CP_ADMIN_TOKEN_HANDLE, env);
-    }
-    catch {
-        return null;
-    }
-}
-/** Redact every secret value resolved so far this process out of a log
- *  line/message. CP code building a log line from data that may carry a
- *  resolved secret (e.g. an upstream request trace) MUST pass it through this
- *  before writing it — never log a resolved value directly. */
-export function redactSecrets(message) {
-    let redacted = message;
-    for (const value of resolvedValues) {
-        if (value === '')
-            continue;
-        redacted = redacted.split(value).join('[redacted]');
-    }
-    return redacted;
-}
-/** Test-only: clear the in-memory file cache + redaction set so a test run
- *  with a different env/file doesn't see a prior run's cached state. */
-export function resetSecretsCacheForTests() {
-    fileCache = null;
-    resolvedValues.clear();
-}

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

@@ -1,27 +0,0 @@
-import { type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http';
-import type { Socket } from 'node:net';
-import type { DatabaseSync } from 'node:sqlite';
-import { type TenantSessionStore } from './session.js';
-import type { ControlPlaneConfig } from './config.js';
-import type { ResolvedHome } from './types.js';
-/** The CP→home relay boundary. P4.1 ships only the gate (session+registry
- *  resolution) in front of this seam; the real implementation (ensureAwake,
- *  HTTP/WS forwarding to `preview_endpoint`, relay-token injection) lands in
- *  P4.2/P4.3 and plugs in by passing a `RelayDispatcher` to
- *  `createControlPlaneServer`. */
-export interface RelayDispatcher {
-    proxyHttp(req: IncomingMessage, res: ServerResponse, home: ResolvedHome): void | Promise<void>;
-    proxyUpgrade(req: IncomingMessage, socket: Socket, head: Buffer, home: ResolvedHome): void;
-}
-export interface ControlPlaneRouteDeps {
-    db?: DatabaseSync;
-    sessionStore?: TenantSessionStore;
-    relay?: RelayDispatcher;
-}
-/** Build the CP HTTP+WS server. No registry seeding and no idle timers are
- *  started here or anywhere reachable from this constructor (master plan
- *  P4.1 / S3 — the provider owns idle->suspend, not the CP). `deps` lets
- *  callers inject the db handle, a session store, and a relay dispatcher —
- *  `main.ts` uses the real env-resolved defaults; tests/smoke checks inject
- *  fakes for all three without touching global env state. */
-export declare function createControlPlaneServer(config: ControlPlaneConfig, deps?: ControlPlaneRouteDeps): HttpServer;