@crouton-kit/crouter 0.3.33 → 0.3.34

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

@@ -0,0 +1,273 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { general } from '../../core/errors.js';
+export const HEARTH_SESSION_COOKIE = 'hearth_session';
+const SESSION_TOKENS_ENV = 'CRTR_HEARTH_CP_SESSION_TOKENS';
+// Real Hearth login seam (not implemented in this cutover increment): the
+// future login/issuance flow plugs in by creating or resolving a tenant and
+// minting one of the token records consumed by `createTenantSessionStore`.
+// This module only validates pre-provisioned records and performs the optional
+// one-time query-token-to-cookie swap for the M0 handoff.
+function sha256Hex(token) {
+    return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+function normalizeHash(hash) {
+    const trimmed = hash.trim();
+    const body = trimmed.startsWith('sha256:') ? trimmed.slice('sha256:'.length) : trimmed;
+    return /^[0-9a-fA-F]{64}$/.test(body) ? body.toLowerCase() : '';
+}
+function tokenHash(seed, field) {
+    const fromHash = seed.token_hash === undefined ? '' : normalizeHash(seed.token_hash);
+    if (fromHash !== '')
+        return fromHash;
+    const token = seed.token?.trim() ?? '';
+    if (token !== '')
+        return sha256Hex(token);
+    throw general(`${field} requires token or token_hash`);
+}
+function optionalQueryTokenHash(seed) {
+    if (seed.query_token_hash !== undefined) {
+        const normalized = normalizeHash(seed.query_token_hash);
+        if (normalized === '')
+            throw general('query_token_hash must be a sha256 hash');
+        return normalized;
+    }
+    const token = seed.query_token?.trim() ?? '';
+    return token === '' ? null : sha256Hex(token);
+}
+function nonEmpty(name, value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        throw general(`${name} must not be empty`, { field: name });
+    return trimmed;
+}
+export function createTenantSessionStore(seeds) {
+    const sessionHashes = new Set();
+    const queryHashes = new Set();
+    const records = seeds.map((seed) => {
+        const normalized = {
+            tenant_id: nonEmpty('tenant_id', seed.tenant_id),
+            user_id: nonEmpty('user_id', seed.user_id),
+            token_hash: tokenHash(seed, 'tenant session token'),
+            token: seed.token?.trim() || null,
+            query_token_hash: optionalQueryTokenHash(seed),
+        };
+        if (sessionHashes.has(normalized.token_hash))
+            throw general('duplicate tenant session token hash');
+        sessionHashes.add(normalized.token_hash);
+        if (normalized.query_token_hash !== null) {
+            if (queryHashes.has(normalized.query_token_hash))
+                throw general('duplicate tenant query token hash');
+            queryHashes.add(normalized.query_token_hash);
+        }
+        return normalized;
+    });
+    return { records, consumed_query_token_hashes: new Set() };
+}
+let envStoreCache = null;
+export function loadTenantSessionStore(env = process.env) {
+    const raw = env[SESSION_TOKENS_ENV];
+    if (envStoreCache !== null && envStoreCache.raw === raw)
+        return envStoreCache.store;
+    if (raw === undefined || raw.trim() === '') {
+        const empty = createTenantSessionStore([]);
+        envStoreCache = { raw, store: empty };
+        return empty;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw general(`${SESSION_TOKENS_ENV} must be JSON`);
+    }
+    if (!Array.isArray(parsed))
+        throw general(`${SESSION_TOKENS_ENV} must be a JSON array`);
+    const store = createTenantSessionStore(parsed);
+    envStoreCache = { raw, store };
+    return store;
+}
+function parseCookieHeader(header) {
+    const out = {};
+    if (header === undefined || header.trim() === '')
+        return out;
+    for (const part of header.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        const value = part.slice(idx + 1).trim();
+        if (key !== '')
+            out[key] = value;
+    }
+    return out;
+}
+function requestUrl(req) {
+    return new URL(req.url ?? '/', 'http://127.0.0.1');
+}
+function queryToken(req) {
+    const token = requestUrl(req).searchParams.get('token')?.trim() ?? '';
+    return token === '' ? null : token;
+}
+function bearerToken(req) {
+    const authorization = req.headers.authorization;
+    if (typeof authorization !== 'string')
+        return null;
+    const match = /^Bearer\s+(.+)$/.exec(authorization.trim());
+    const token = match?.[1]?.trim() ?? '';
+    return token === '' ? null : token;
+}
+function cookieToken(req) {
+    const token = parseCookieHeader(req.headers.cookie)[HEARTH_SESSION_COOKIE];
+    if (token === undefined || token.trim() === '')
+        return null;
+    try {
+        return decodeURIComponent(token.trim());
+    }
+    catch {
+        return null;
+    }
+}
+function constantTimeMatch(expectedHash, candidateHash) {
+    if (expectedHash === '')
+        return false;
+    return timingSafeEqual(Buffer.from(expectedHash, 'hex'), Buffer.from(candidateHash, 'hex'));
+}
+function lookupBySessionToken(token, store) {
+    const trimmed = token.trim();
+    if (trimmed === '')
+        return null;
+    const candidate = sha256Hex(trimmed);
+    let match = null;
+    for (const record of store.records) {
+        if (constantTimeMatch(record.token_hash, candidate)) {
+            match = { tenant_id: record.tenant_id, user_id: record.user_id };
+        }
+    }
+    return match;
+}
+function lookupByQueryToken(token, store) {
+    const trimmed = token.trim();
+    if (trimmed === '')
+        return null;
+    const candidate = sha256Hex(trimmed);
+    let match = null;
+    for (const record of store.records) {
+        if (record.query_token_hash !== null && constantTimeMatch(record.query_token_hash, candidate)) {
+            match = record;
+        }
+    }
+    return match;
+}
+function trustedOrigin(req, publicOrigin) {
+    const expected = publicOrigin.trim();
+    if (expected === '')
+        throw general('publicOrigin is required for tenant session origin checks');
+    const origin = req.headers.origin?.trim() ?? '';
+    return origin !== '' && origin === expected;
+}
+/** Origin policy for the one-time query-token swap on a safe top-level
+ *  GET/HEAD navigation. Ordinary top-level navigations (the only way this
+ *  swap is reachable — see `swapQueryTokenForCookie`) do not reliably carry
+ *  an `Origin` header at all, so requiring one regressed the M0 open-link
+ *  handoff into an unusable 401. The token itself is a one-time secret: a
+ *  party that can already supply the correct `?token=` value has already
+ *  obtained the secret, so Origin adds no protection against that. If a
+ *  browser-style `Origin` header IS present (e.g. a cross-origin fetch/XHR
+ *  rather than a plain top-level navigation), it must still match
+ *  `publicOrigin` exactly — this only relaxes the "no Origin header at all"
+ *  case, it does not accept a mismatched one. */
+function originAcceptableForQueryTokenSwap(req, publicOrigin) {
+    const origin = req.headers.origin?.trim() ?? '';
+    if (origin === '')
+        return true;
+    return origin === publicOrigin.trim();
+}
+export function setSessionCookie(res, token, options = {}) {
+    const maxAge = options.maxAgeSeconds ?? 365 * 24 * 60 * 60;
+    const path = options.path ?? '/';
+    const sameSite = options.sameSite ?? 'Lax';
+    const secure = options.secure ?? true;
+    const parts = [
+        `${HEARTH_SESSION_COOKIE}=${encodeURIComponent(token)}`,
+        `Path=${path}`,
+        'HttpOnly',
+        `SameSite=${sameSite}`,
+        `Max-Age=${maxAge}`,
+    ];
+    if (secure)
+        parts.push('Secure');
+    res.setHeader('Set-Cookie', parts.join('; '));
+}
+export function clearSessionCookie(res, options = {}) {
+    setSessionCookie(res, '', { ...options, maxAgeSeconds: 0 });
+}
+/** Validate durable session credentials only: HttpOnly cookie for browsers or
+ *  Bearer for non-browser clients. Query tokens are intentionally ignored here
+ *  so a copied `?token=` URL is never durable authorization. */
+export function resolveTenantSession(req, options = {}) {
+    const store = options.store ?? loadTenantSessionStore();
+    const cookie = cookieToken(req);
+    if (cookie !== null) {
+        const session = lookupBySessionToken(cookie, store);
+        return session === null ? null : { ...session, source: 'cookie' };
+    }
+    const bearer = bearerToken(req);
+    if (bearer !== null) {
+        if ((req.headers.origin?.trim() ?? '') !== '')
+            return null;
+        const session = lookupBySessionToken(bearer, store);
+        return session === null ? null : { ...session, source: 'bearer' };
+    }
+    return null;
+}
+/** State-changing browser lanes require a valid session AND a trusted Origin;
+ *  query tokens are not accepted here. Bearer remains available only to
+ *  non-browser clients (no Origin header). */
+export function resolveTenantWriteAuth(req, options) {
+    const auth = resolveTenantSession(req, options);
+    if (auth === null)
+        return null;
+    if (auth.source === 'cookie')
+        return trustedOrigin(req, options.publicOrigin) ? auth : null;
+    return auth.source === 'bearer' ? auth : null;
+}
+/** Consume an optional M0 handoff `?token=` exactly once and swap it to the
+ *  HttpOnly/Secure/SameSite Hearth session cookie. This is the only query-token
+ *  path. Safe top-level navigations (`GET`/`HEAD`) are permitted without a
+ *  matching `Origin` header (see `originAcceptableForQueryTokenSwap`); any
+ *  other method still requires a trusted Origin, matching the write-lane
+ *  policy. Returns null on replay, invalid token, missing token, or a
+ *  rejected Origin. */
+export function swapQueryTokenForCookie(req, res, options) {
+    const method = req.method ?? 'GET';
+    const isSafeTopLevelNavigation = method === 'GET' || method === 'HEAD';
+    const originOk = isSafeTopLevelNavigation
+        ? originAcceptableForQueryTokenSwap(req, options.publicOrigin)
+        : trustedOrigin(req, options.publicOrigin);
+    if (!originOk)
+        return null;
+    const store = options.store ?? loadTenantSessionStore();
+    const token = queryToken(req);
+    if (token === null)
+        return null;
+    const record = lookupByQueryToken(token, store);
+    if (record === null || record.query_token_hash === null)
+        return null;
+    if (store.consumed_query_token_hashes.has(record.query_token_hash))
+        return null;
+    if (record.token === null) {
+        throw general('query token swap requires a raw pre-provisioned session token for Set-Cookie');
+    }
+    store.consumed_query_token_hashes.add(record.query_token_hash);
+    setSessionCookie(res, record.token, options.cookie);
+    return { tenant_id: record.tenant_id, user_id: record.user_id, source: 'query-swap' };
+}
+export function tenantSessionAuthRedactedMessage(message) {
+    return message
+        .replace(/(Authorization:\s*Bearer\s+)[^\s]+/gi, '$1[redacted]')
+        .replace(/([?&]token=)[^&#\s]+/gi, '$1[redacted]')
+        .replace(new RegExp(`(${HEARTH_SESSION_COOKIE}=)[^;\\s]+`, 'gi'), '$1[redacted]');
+}
+export function resetTenantSessionStoreCacheForTests() {
+    envStoreCache = null;
+}

package/dist/hearth/control-plane/triggers/acl.d.ts

@@ -0,0 +1,14 @@
+import type { HomeId } from '../types.js';
+import type { TriggerSource } from './envelope.js';
+export interface AuthorizeTriggerResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Structural authorization for delivering `source`/`sourceRef` to `homeId`.
+ * Rejects when the source row is absent, when the target `homeId` differs from
+ * the source-bound home (cross-home targeting), or when the target home is
+ * absent or terminated. Returns `{ ok: true }` only for a source whose FK
+ * home matches the target and resolves to a live home.
+ */
+export declare function authorizeTrigger(source: TriggerSource, sourceRef: string, homeId: HomeId): AuthorizeTriggerResult;

package/dist/hearth/control-plane/triggers/acl.js

@@ -0,0 +1,52 @@
+// control-plane/triggers/acl.ts — the R-TRIG-4 STRUCTURAL trigger authorization
+// guard (master plan P5.2). This is the FK-integrity check only: "which source
+// may target which home". The permission/ownership POLICY beyond this
+// (per-user grants, capability scoping, etc.) is explicitly post-cutover
+// (part-plan gap note 11) and is NOT implemented here.
+//
+// The guard: a trigger's bound source row (`schedule_fire` for cron,
+// `ingress_route` for webhook) carries a `home_id` FK. A delivery is
+// authorized only when the target `home_id` EQUALS that source-bound home_id
+// (no cross-home targeting) AND that home resolves to an existing,
+// non-terminated `home` row. Anything else is rejected before any wake/exec.
+import { getControlPlaneDb } from '../db.js';
+import { getHomeById } from '../registry.js';
+/** Terminated/terminating homes are not valid delivery targets — a trigger
+ *  must never wake or exec against a home that is being torn down. */
+const DEAD_HOME_STATUSES = new Set(['terminating', 'terminated']);
+/** Read the `home_id` a source row (`schedule_fire.fire_id` for cron,
+ *  `ingress_route.route_id` for webhook) is bound to. `null` when the source
+ *  row does not exist — a hard reject (no home to target). */
+function sourceBoundHomeId(source, sourceRef) {
+    const db = getControlPlaneDb();
+    if (source === 'cron') {
+        const row = db.prepare('SELECT home_id FROM schedule_fire WHERE fire_id = ?').get(sourceRef);
+        return row === undefined ? null : row.home_id;
+    }
+    const row = db.prepare('SELECT home_id FROM ingress_route WHERE route_id = ?').get(sourceRef);
+    return row === undefined ? null : row.home_id;
+}
+/**
+ * Structural authorization for delivering `source`/`sourceRef` to `homeId`.
+ * Rejects when the source row is absent, when the target `homeId` differs from
+ * the source-bound home (cross-home targeting), or when the target home is
+ * absent or terminated. Returns `{ ok: true }` only for a source whose FK
+ * home matches the target and resolves to a live home.
+ */
+export function authorizeTrigger(source, sourceRef, homeId) {
+    const boundHomeId = sourceBoundHomeId(source, sourceRef);
+    if (boundHomeId === null) {
+        return { ok: false, reason: 'source not found' };
+    }
+    if (boundHomeId !== homeId) {
+        return { ok: false, reason: 'cross-home targeting rejected' };
+    }
+    const home = getHomeById(homeId);
+    if (home === null) {
+        return { ok: false, reason: 'target home not found' };
+    }
+    if (DEAD_HOME_STATUSES.has(home.status)) {
+        return { ok: false, reason: `target home ${home.status}` };
+    }
+    return { ok: true };
+}

package/dist/hearth/control-plane/triggers/audit-store.d.ts

@@ -0,0 +1,38 @@
+export type TriggerSource = 'cron' | 'webhook';
+export type TriggerTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+export type TriggerOutcome = 'delivered' | 'rejected' | 'failed';
+export interface TriggerAuditRow {
+    audit_id: string;
+    tenant_id: string;
+    user_id: string;
+    home_id: string;
+    source: TriggerSource;
+    source_ref: string;
+    trigger_id: string;
+    tier: TriggerTier;
+    outcome: TriggerOutcome;
+    reason: string | null;
+    payload_sha256: string | null;
+    metadata_json: Record<string, unknown> | null;
+    at: string;
+}
+export interface RecordTriggerAuditInput {
+    audit_id?: string;
+    source: TriggerSource;
+    source_ref: string;
+    trigger_id: string;
+    tier: TriggerTier;
+    outcome: TriggerOutcome;
+    reason?: string | null;
+    payload_sha256?: string | null;
+    metadata_json?: Record<string, unknown> | null;
+    at?: string;
+}
+export interface ListTriggerAuditOptions {
+    from?: string;
+    to?: string;
+    limit?: number;
+}
+export declare function recordTriggerAudit(input: RecordTriggerAuditInput): TriggerAuditRow;
+export declare function getTriggerAuditById(auditId: string): TriggerAuditRow | null;
+export declare function listTriggerAudit(homeId: string, options?: ListTriggerAuditOptions): TriggerAuditRow[];

package/dist/hearth/control-plane/triggers/audit-store.js

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+import { getControlPlaneDb } from '../db.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function sourceIdentity(source, sourceRef) {
+    if (source === 'cron') {
+        const row = getControlPlaneDb()
+            .prepare('SELECT home_id, tenant_id, user_id FROM schedule_fire WHERE fire_id = ?')
+            .get(sourceRef);
+        if (row === undefined)
+            throw new Error(`schedule fire not found: ${sourceRef}`);
+        return row;
+    }
+    const row = getControlPlaneDb()
+        .prepare('SELECT home_id, tenant_id, user_id FROM ingress_route WHERE route_id = ?')
+        .get(sourceRef);
+    if (row === undefined)
+        throw new Error(`ingress route not found: ${sourceRef}`);
+    return row;
+}
+function auditFrom(row) {
+    const metadata = row['metadata_json'];
+    return {
+        audit_id: row['audit_id'],
+        tenant_id: row['tenant_id'],
+        user_id: row['user_id'],
+        home_id: row['home_id'],
+        source: row['source'],
+        source_ref: row['source_ref'],
+        trigger_id: row['trigger_id'],
+        tier: row['tier'],
+        outcome: row['outcome'],
+        reason: row['reason'] ?? null,
+        payload_sha256: row['payload_sha256'] ?? null,
+        metadata_json: metadata === null ? null : JSON.parse(metadata),
+        at: row['at'],
+    };
+}
+export function recordTriggerAudit(input) {
+    const auditId = input.audit_id ?? `audit-${randomUUID()}`;
+    const at = input.at ?? nowIso();
+    const identity = sourceIdentity(input.source, input.source_ref);
+    getControlPlaneDb()
+        .prepare(`INSERT INTO trigger_audit (
+         audit_id, tenant_id, user_id, home_id, source, source_ref, trigger_id,
+         tier, outcome, reason, payload_sha256, metadata_json, at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(auditId, identity.tenant_id, identity.user_id, identity.home_id, input.source, input.source_ref, input.trigger_id, input.tier, input.outcome, input.reason ?? null, input.payload_sha256 ?? null, input.metadata_json == null ? null : JSON.stringify(input.metadata_json), at);
+    return getTriggerAuditById(auditId);
+}
+export function getTriggerAuditById(auditId) {
+    const row = getControlPlaneDb().prepare('SELECT * FROM trigger_audit WHERE audit_id = ?').get(auditId);
+    return row === undefined ? null : auditFrom(row);
+}
+export function listTriggerAudit(homeId, options = {}) {
+    const limit = options.limit ?? 100;
+    const db = getControlPlaneDb();
+    let rows;
+    if (options.from !== undefined && options.to !== undefined) {
+        rows = db
+            .prepare('SELECT * FROM trigger_audit WHERE home_id = ? AND at >= ? AND at <= ? ORDER BY at DESC LIMIT ?')
+            .all(homeId, options.from, options.to, limit);
+    }
+    else if (options.from !== undefined) {
+        rows = db
+            .prepare('SELECT * FROM trigger_audit WHERE home_id = ? AND at >= ? ORDER BY at DESC LIMIT ?')
+            .all(homeId, options.from, limit);
+    }
+    else if (options.to !== undefined) {
+        rows = db
+            .prepare('SELECT * FROM trigger_audit WHERE home_id = ? AND at <= ? ORDER BY at DESC LIMIT ?')
+            .all(homeId, options.to, limit);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM trigger_audit WHERE home_id = ? ORDER BY at DESC LIMIT ?').all(homeId, limit);
+    }
+    return rows.map(auditFrom);
+}

package/dist/hearth/control-plane/triggers/deliver.d.ts

@@ -0,0 +1,43 @@
+import type { HomeId } from '../types.js';
+import { recordTriggerAudit } from './audit-store.js';
+import { authorizeTrigger } from './acl.js';
+import { type TriggerEnvelope } from './envelope.js';
+import { wakeAndExecNodeMessage, type NodeMessageTier } from '../node-message.js';
+export type DeliveryOutcome = 'delivered' | 'rejected' | 'failed';
+export interface DeliverTriggerInput {
+    home_id: HomeId;
+    /** The source row this delivery is bound to: `schedule_fire.fire_id` (cron)
+     *  or `ingress_route.route_id` (webhook). Used for both the ACL FK guard and
+     *  the audit `source_ref`. */
+    source_ref: string;
+    envelope: TriggerEnvelope;
+    tier: NodeMessageTier;
+    /** Optional pre-computed payload hash (e.g. webhook raw-body sha256). When
+     *  omitted, a hash over the serialized envelope payload is recorded. The raw
+     *  payload itself is NEVER stored. */
+    payload_sha256?: string;
+    /** Bounded, non-sensitive audit metadata (e.g. byte length, content-type).
+     *  Never the raw payload. */
+    metadata?: Record<string, unknown>;
+}
+export interface DeliverTriggerResult {
+    outcome: DeliveryOutcome;
+    reason?: string;
+}
+/** Indirection seam so a test/smoke script can fake the guard, the exec
+ *  primitive, and the audit writer without a real DB/provider. Production
+ *  never reassigns these. */
+export declare const deliverInternals: {
+    authorizeTrigger: typeof authorizeTrigger;
+    wakeAndExecNodeMessage: typeof wakeAndExecNodeMessage;
+    recordTriggerAudit: typeof recordTriggerAudit;
+};
+/**
+ * Deliver `input.envelope` to `input.home_id` through the P4.4 wake+exec
+ * primitive, gated by the FK-integrity ACL and recorded in the trigger audit.
+ * Returns `{ outcome: 'rejected' }` (no wake/exec) for an unauthorized target,
+ * `{ outcome: 'delivered' }` after a successful in-guest `node msg`, or
+ * `{ outcome: 'failed' }` when the wake/exec threw. Every path writes exactly
+ * one audit row (rejected/delivered/failed).
+ */
+export declare function deliverTrigger(input: DeliverTriggerInput): Promise<DeliverTriggerResult>;

package/dist/hearth/control-plane/triggers/deliver.js

@@ -0,0 +1,76 @@
+// control-plane/triggers/deliver.ts — the single SEAM-5 trigger delivery
+// chokepoint (master plan P5.3). BOTH producers (cron scan loop, webhook
+// ingress) deliver through here and only here, so the R-TRIG-4 hooks
+// (authorize + audit) can never be bypassed by a producer.
+//
+// Flow: (1) `authorizeTrigger` (FK-integrity guard, acl.ts) — an unauthorized
+// trigger records a `rejected` audit row and returns WITHOUT ever waking or
+// exec'ing a home; (2) on authorize, call the P4.4 primitive
+// `wakeAndExecNodeMessage(home_id, serializeEnvelope(envelope), tier)` — which
+// wakes the home FIRST, then runs `crtr node msg --to <target> --tier <tier>`
+// in-guest with the serialized envelope on STDIN (never in argv/heredoc/
+// base64); (3) record a `delivered` or `failed` audit row.
+//
+// This module NEVER touches provider exec directly and NEVER writes a home's
+// inbox file — the P4.4 primitive is the only delivery path. It also never
+// persists the raw untrusted payload: the audit row carries a content HASH and
+// bounded metadata only (R-CP-8 / audit-is-metadata-only).
+import { createHash } from 'node:crypto';
+import { redactSecrets } from '../secrets.js';
+import { recordTriggerAudit } from './audit-store.js';
+import { authorizeTrigger } from './acl.js';
+import { serializeEnvelope } from './envelope.js';
+import { wakeAndExecNodeMessage } from '../node-message.js';
+/** Indirection seam so a test/smoke script can fake the guard, the exec
+ *  primitive, and the audit writer without a real DB/provider. Production
+ *  never reassigns these. */
+export const deliverInternals = {
+    authorizeTrigger,
+    wakeAndExecNodeMessage,
+    recordTriggerAudit,
+};
+function hashPayload(payload) {
+    return createHash('sha256').update(JSON.stringify(payload ?? null)).digest('hex');
+}
+/** Bound + redact an error into an audit `reason`. The P4.4 primitive's error
+ *  messages do not include the payload body, but this is defense-in-depth:
+ *  truncate and strip any resolved secret before it lands in a DB row. */
+function auditReason(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return redactSecrets(raw).slice(0, 200);
+}
+/**
+ * Deliver `input.envelope` to `input.home_id` through the P4.4 wake+exec
+ * primitive, gated by the FK-integrity ACL and recorded in the trigger audit.
+ * Returns `{ outcome: 'rejected' }` (no wake/exec) for an unauthorized target,
+ * `{ outcome: 'delivered' }` after a successful in-guest `node msg`, or
+ * `{ outcome: 'failed' }` when the wake/exec threw. Every path writes exactly
+ * one audit row (rejected/delivered/failed).
+ */
+export async function deliverTrigger(input) {
+    const { home_id, source_ref, envelope, tier } = input;
+    const payloadSha256 = input.payload_sha256 ?? hashPayload(envelope.payload);
+    const auditBase = {
+        source: envelope.source,
+        source_ref,
+        trigger_id: envelope.trigger_id,
+        tier,
+        payload_sha256: payloadSha256,
+        metadata_json: input.metadata ?? null,
+    };
+    const authorized = deliverInternals.authorizeTrigger(envelope.source, source_ref, home_id);
+    if (!authorized.ok) {
+        deliverInternals.recordTriggerAudit({ ...auditBase, outcome: 'rejected', reason: authorized.reason ?? 'unauthorized' });
+        return { outcome: 'rejected', reason: authorized.reason };
+    }
+    try {
+        await deliverInternals.wakeAndExecNodeMessage(home_id, serializeEnvelope(envelope), tier);
+    }
+    catch (error) {
+        const reason = auditReason(error);
+        deliverInternals.recordTriggerAudit({ ...auditBase, outcome: 'failed', reason });
+        return { outcome: 'failed', reason };
+    }
+    deliverInternals.recordTriggerAudit({ ...auditBase, outcome: 'delivered' });
+    return { outcome: 'delivered' };
+}

package/dist/hearth/control-plane/triggers/envelope.d.ts

@@ -0,0 +1,29 @@
+export type TriggerSource = 'cron' | 'webhook';
+/**
+ * The delivered envelope. `payload` is deliberately `unknown` — it is
+ * untrusted external content and callers/home-side code must narrow it
+ * defensively. `trigger_id` is the home-side dedupe key: the durable
+ * `schedule_fire.fire_id` for cron, a stable route-derived id for webhook.
+ */
+export interface TriggerEnvelope {
+    source: TriggerSource;
+    trigger_id: string;
+    payload: unknown;
+    received_at: string;
+}
+export interface BuildTriggerEnvelopeInput {
+    source: TriggerSource;
+    trigger_id: string;
+    payload: unknown;
+    /** Override the received-at stamp (tests/replays); defaults to now. */
+    received_at?: string;
+}
+/** Build a canonical envelope. Takes NO routing-key argument by construction
+ *  (R-ING-3) — `payload` is channel-shaped content only. */
+export declare function buildTriggerEnvelope(input: BuildTriggerEnvelopeInput): TriggerEnvelope;
+/** Serialize an envelope to the compact JSON body carried on the `node msg`
+ *  stdin. Emits EXACTLY the four canonical fields in a fixed order — any
+ *  extra property on the passed object (e.g. a stray routing key) is dropped
+ *  here, so the home only ever sees `{source, trigger_id, payload,
+ *  received_at}`. */
+export declare function serializeEnvelope(envelope: TriggerEnvelope): string;

package/dist/hearth/control-plane/triggers/envelope.js

@@ -0,0 +1,38 @@
+// control-plane/triggers/envelope.ts — the R-TRIG-2 trigger delivery envelope
+// (master plan P5.1). The exact JSON shape delivered in-guest to a home agent
+// over `crtr node msg --to <target>` (stdin body), for both cron and webhook
+// sources.
+//
+// Two hard invariants this module encodes:
+//   1. `payload` is UNTRUSTED external data. For a webhook it is attacker-
+//      controlled request-body content; for cron it is the operator-authored
+//      `schedule.delivery_payload`. Home agents / scaffolding must treat it as
+//      data, never as instructions (the C7 image defaults say so too).
+//   2. The envelope NEVER carries the ingress routing key (R-ING-3). The
+//      builder takes no routing-key argument, and `serializeEnvelope` emits
+//      ONLY the four canonical fields, so a routing key can never leak to a
+//      home even if a caller stuffed one into an ad-hoc object.
+/** Build a canonical envelope. Takes NO routing-key argument by construction
+ *  (R-ING-3) — `payload` is channel-shaped content only. */
+export function buildTriggerEnvelope(input) {
+    return {
+        source: input.source,
+        trigger_id: input.trigger_id,
+        payload: input.payload,
+        received_at: input.received_at ?? new Date().toISOString(),
+    };
+}
+/** Serialize an envelope to the compact JSON body carried on the `node msg`
+ *  stdin. Emits EXACTLY the four canonical fields in a fixed order — any
+ *  extra property on the passed object (e.g. a stray routing key) is dropped
+ *  here, so the home only ever sees `{source, trigger_id, payload,
+ *  received_at}`. */
+export function serializeEnvelope(envelope) {
+    const canonical = {
+        source: envelope.source,
+        trigger_id: envelope.trigger_id,
+        payload: envelope.payload,
+        received_at: envelope.received_at,
+    };
+    return JSON.stringify(canonical);
+}