@crouton-kit/crouter 0.3.40 → 0.3.41

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

@@ -1,24 +0,0 @@
-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

@@ -1,100 +0,0 @@
-// 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

@@ -1,31 +0,0 @@
-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;

package/dist/hearth/control-plane/ingress/route-store.js

@@ -1,61 +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 routeFrom(row) {
-    return {
-        route_id: row['route_id'],
-        tenant_id: row['tenant_id'],
-        user_id: row['user_id'],
-        home_id: row['home_id'],
-        channel: row['channel'],
-        routing_key: row['routing_key'],
-        routing_key_kind: row['routing_key_kind'],
-        channel_secret_ref: row['channel_secret_ref'] ?? null,
-        delivery_template: JSON.parse(row['delivery_template']),
-        enabled: Number(row['enabled']) !== 0,
-        created_at: row['created_at'],
-        updated_at: row['updated_at'],
-    };
-}
-export function registerRoute(input) {
-    const routeId = input.route_id ?? `route-${randomUUID()}`;
-    const stamped = input.now ?? nowIso();
-    const identity = homeIdentity(input.home_id);
-    getControlPlaneDb()
-        .prepare(`INSERT INTO ingress_route (
-         route_id, tenant_id, user_id, home_id, channel, routing_key,
-         routing_key_kind, channel_secret_ref, delivery_template, enabled,
-         created_at, updated_at
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(routeId, identity.tenant_id, identity.user_id, input.home_id, input.channel, input.routing_key, input.routing_key_kind, input.channel_secret_ref ?? null, JSON.stringify(input.delivery_template), input.enabled === false ? 0 : 1, stamped, stamped);
-    return getRouteById(routeId);
-}
-export function getRouteById(routeId) {
-    const row = getControlPlaneDb().prepare('SELECT * FROM ingress_route WHERE route_id = ?').get(routeId);
-    return row === undefined ? null : routeFrom(row);
-}
-export function resolveRoute(channel, routingKey) {
-    const row = getControlPlaneDb()
-        .prepare('SELECT * FROM ingress_route WHERE channel = ? AND routing_key = ? AND enabled = 1')
-        .get(channel, routingKey);
-    return row === undefined ? null : routeFrom(row);
-}
-export function listRoutesForUser(tenantId, userId) {
-    const rows = getControlPlaneDb()
-        .prepare('SELECT * FROM ingress_route WHERE tenant_id = ? AND user_id = ? ORDER BY channel, routing_key')
-        .all(tenantId, userId);
-    return rows.map(routeFrom);
-}
-export function setRouteEnabled(routeId, enabled, now = nowIso()) {
-    getControlPlaneDb()
-        .prepare('UPDATE ingress_route SET enabled = ?, updated_at = ? WHERE route_id = ?')
-        .run(enabled ? 1 : 0, now, routeId);
-}

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

@@ -1,41 +0,0 @@
-export type WebhookDeliveryState = 'received' | 'delivered' | 'rejected' | 'failed';
-export interface WebhookDeliveryRow {
-    delivery_id: string;
-    route_id: string;
-    tenant_id: string;
-    user_id: string;
-    home_id: string;
-    replay_key: string;
-    replay_window_start: string;
-    payload_sha256: string | null;
-    signature_sha256: string | null;
-    state: WebhookDeliveryState;
-    received_at: string;
-    delivered_at: string | null;
-    last_error: string | null;
-    created_at: string;
-    updated_at: string;
-}
-export interface ClaimWebhookDeliveryInput {
-    delivery_id?: string;
-    route_id: string;
-    replay_key: string;
-    replay_window_start: string;
-    payload_sha256?: string | null;
-    signature_sha256?: string | null;
-    received_at?: string;
-    now?: string;
-}
-export interface ClaimWebhookDeliveryResult {
-    delivery: WebhookDeliveryRow;
-    claimed: boolean;
-}
-export interface SetWebhookDeliveryStateOptions {
-    delivered_at?: string | null;
-    last_error?: string | null;
-    now?: string;
-}
-export declare function claimWebhookDelivery(input: ClaimWebhookDeliveryInput): ClaimWebhookDeliveryResult;
-export declare function getWebhookDeliveryById(deliveryId: string): WebhookDeliveryRow | null;
-export declare function getWebhookDeliveryByReplayKey(routeId: string, replayKey: string, replayWindowStart: string): WebhookDeliveryRow | null;
-export declare function setWebhookDeliveryState(deliveryId: string, state: WebhookDeliveryState, options?: SetWebhookDeliveryStateOptions): void;

package/dist/hearth/control-plane/ingress/webhook-delivery-store.js

@@ -1,69 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { getControlPlaneDb } from '../db.js';
-function nowIso() {
-    return new Date().toISOString();
-}
-function routeIdentity(routeId) {
-    const row = getControlPlaneDb()
-        .prepare('SELECT home_id, tenant_id, user_id FROM ingress_route WHERE route_id = ?')
-        .get(routeId);
-    if (row === undefined)
-        throw new Error(`ingress route not found: ${routeId}`);
-    return row;
-}
-function deliveryFrom(row) {
-    return {
-        delivery_id: row['delivery_id'],
-        route_id: row['route_id'],
-        tenant_id: row['tenant_id'],
-        user_id: row['user_id'],
-        home_id: row['home_id'],
-        replay_key: row['replay_key'],
-        replay_window_start: row['replay_window_start'],
-        payload_sha256: row['payload_sha256'] ?? null,
-        signature_sha256: row['signature_sha256'] ?? null,
-        state: row['state'],
-        received_at: row['received_at'],
-        delivered_at: row['delivered_at'] ?? null,
-        last_error: row['last_error'] ?? null,
-        created_at: row['created_at'],
-        updated_at: row['updated_at'],
-    };
-}
-export function claimWebhookDelivery(input) {
-    const deliveryId = input.delivery_id ?? `whdel-${randomUUID()}`;
-    const stamped = input.now ?? nowIso();
-    const receivedAt = input.received_at ?? stamped;
-    const identity = routeIdentity(input.route_id);
-    const result = getControlPlaneDb()
-        .prepare(`INSERT OR IGNORE INTO webhook_delivery (
-         delivery_id, route_id, tenant_id, user_id, home_id, replay_key,
-         replay_window_start, payload_sha256, signature_sha256, state,
-         received_at, delivered_at, last_error, created_at, updated_at
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'received', ?, NULL, NULL, ?, ?)`)
-        .run(deliveryId, input.route_id, identity.tenant_id, identity.user_id, identity.home_id, input.replay_key, input.replay_window_start, input.payload_sha256 ?? null, input.signature_sha256 ?? null, receivedAt, stamped, stamped);
-    const delivery = getWebhookDeliveryByReplayKey(input.route_id, input.replay_key, input.replay_window_start);
-    if (delivery === null) {
-        throw new Error(`failed to claim webhook delivery for route ${input.route_id} replay key ${input.replay_key}`);
-    }
-    return { delivery, claimed: result.changes === 1 };
-}
-export function getWebhookDeliveryById(deliveryId) {
-    const row = getControlPlaneDb().prepare('SELECT * FROM webhook_delivery WHERE delivery_id = ?').get(deliveryId);
-    return row === undefined ? null : deliveryFrom(row);
-}
-export function getWebhookDeliveryByReplayKey(routeId, replayKey, replayWindowStart) {
-    const row = getControlPlaneDb()
-        .prepare('SELECT * FROM webhook_delivery WHERE route_id = ? AND replay_key = ? AND replay_window_start = ?')
-        .get(routeId, replayKey, replayWindowStart);
-    return row === undefined ? null : deliveryFrom(row);
-}
-export function setWebhookDeliveryState(deliveryId, state, options = {}) {
-    const stamped = options.now ?? nowIso();
-    const deliveredAt = options.delivered_at === undefined ? (state === 'delivered' ? stamped : null) : options.delivered_at;
-    getControlPlaneDb()
-        .prepare(`UPDATE webhook_delivery
-       SET state = ?, delivered_at = COALESCE(?, delivered_at), last_error = ?, updated_at = ?
-       WHERE delivery_id = ?`)
-        .run(state, deliveredAt, options.last_error ?? null, stamped, deliveryId);
-}

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

@@ -1,55 +0,0 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import { buildTriggerEnvelope } from '../triggers/envelope.js';
-import { type DeliverTriggerResult } from '../triggers/deliver.js';
-import { type IngressRouteRow } from './route-store.js';
-import { claimWebhookDelivery, setWebhookDeliveryState } from './webhook-delivery-store.js';
-import { type RateCheckResult } from './rate-limit.js';
-export interface WebhookProcessDeps {
-    checkRate: (key: string) => RateCheckResult;
-    resolveRoute: (channel: 'webhook', routingKey: string) => IngressRouteRow | null;
-    resolveSecret: (ref: string) => string;
-    claimWebhookDelivery: typeof claimWebhookDelivery;
-    setWebhookDeliveryState: typeof setWebhookDeliveryState;
-    deliverTrigger: (input: {
-        home_id: string;
-        source_ref: string;
-        envelope: ReturnType<typeof buildTriggerEnvelope>;
-        tier: 'urgent';
-        payload_sha256?: string;
-        metadata?: Record<string, unknown>;
-    }) => Promise<DeliverTriggerResult>;
-    now: () => Date;
-}
-export interface WebhookRequest {
-    routingKey: string;
-    rawBody: Buffer;
-    signatureHeader: string | null;
-    deliveryIdHeader: string | null;
-    contentType: string | null;
-}
-export interface WebhookResult {
-    status: number;
-    message: string;
-    retryAfterMs?: number;
-}
-/** Production defaults — real rate limiter, stores, secret resolver, and
- *  delivery chokepoint. Tests inject fakes. */
-export declare function defaultWebhookProcessDeps(): WebhookProcessDeps;
-/**
- * The verification + delivery core, independent of HTTP plumbing so the
- * security invariants (signature, replay, no-routing-key) are directly
- * testable. Returns the status + message the HTTP layer writes back.
- */
-export declare function processWebhookDelivery(req: WebhookRequest, deps: WebhookProcessDeps): Promise<WebhookResult>;
-/** Extract the single `routing_key` path segment from `/webhook/<key>`.
- *  Rejects an empty key, extra segments, embedded slash/backslash, or
- *  malformed percent-encoding. */
-export declare function extractRoutingKey(pathname: string): string | null;
-/**
- * HTTP handler for `POST /webhook/:routing_key`. Reads the raw body (bounded),
- * extracts the routing key + signature/delivery headers, runs
- * `processWebhookDelivery`, and writes the resulting status. This is a PUBLIC
- * endpoint — its only authentication is the per-route HMAC signature, so it
- * must be mounted OUTSIDE the session/registry gate.
- */
-export declare function handleWebhook(req: IncomingMessage, res: ServerResponse, deps?: WebhookProcessDeps): Promise<void>;

package/dist/hearth/control-plane/ingress/webhook-route.js

@@ -1,285 +0,0 @@
-// control-plane/ingress/webhook-route.ts — the generic webhook ingress
-// endpoint (master plan P5.5 / part-plan T-C3): `POST /webhook/:routing_key`.
-// The ONLY ingress channel mounted this increment (SMS/email/chat/persistent-
-// socket connectors are out of scope).
-//
-// Order of operations (security-load-bearing):
-//   1. PRE-RESOLUTION rate limit on the routing key — a flood is shed before
-//      any DB lookup / secret resolution / write.
-//   2. Route lookup (`resolveRoute('webhook', key)`) — unknown key → 404, no
-//      delivery.
-//   3. HMAC-SHA256 over the RAW request body using the route's resolved
-//      signing secret (`channel_secret_ref` → `resolveSecret`), constant-time
-//      compared. The secret is DISTINCT from the routing key (the key is
-//      public/demux-only). Missing/invalid signature → reject, no delivery.
-//      A bad signature never writes a `webhook_delivery` row (no amplification).
-//   4. Replay/idempotency via `webhook_delivery` (unique per route + replay
-//      key + window). A duplicate is acknowledged idempotently and NOT
-//      re-delivered.
-//   5. Build the trigger envelope — `trigger_id` is route-derived + per-
-//      delivery (`<route_id>:<replay_key>`) for stable home-side dedupe. The
-//      ROUTING KEY IS NEVER PLACED IN THE ENVELOPE (R-ING-3).
-//   6. Deliver through the shared `deliverTrigger` chokepoint at tier
-//      `urgent` (R-TRIG-3) — which authorizes, wakes, exec's in-guest, audits.
-//
-// The raw public body is never persisted: `webhook_delivery`/`trigger_audit`
-// carry only content hashes + bounded metadata.
-import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
-import { buildTriggerEnvelope } from '../triggers/envelope.js';
-import { deliverTrigger } from '../triggers/deliver.js';
-import { resolveSecret } from '../secrets.js';
-import { resolveRoute } from './route-store.js';
-import { claimWebhookDelivery, setWebhookDeliveryState, } from './webhook-delivery-store.js';
-import { createRateLimiter, loadRateLimiterConfig } from './rate-limit.js';
-const ENV = {
-    maxBodyBytes: 'CRTR_HEARTH_CP_WEBHOOK_MAX_BODY_BYTES',
-};
-const DEFAULT_MAX_BODY_BYTES = 1_048_576; // 1 MiB
-/** Canonical signing header (hex HMAC-SHA256 of the raw body). The GitHub-
- *  style `x-hub-signature-256: sha256=<hex>` header is also accepted for
- *  compatibility; both are verified identically against the raw body. */
-const SIGNATURE_HEADERS = ['x-hearth-signature-256', 'x-hub-signature-256', 'x-signature-256'];
-const DELIVERY_ID_HEADERS = ['x-hearth-delivery-id', 'x-idempotency-key', 'x-github-delivery'];
-const sharedRateLimiter = createRateLimiter(loadRateLimiterConfig());
-/** Production defaults — real rate limiter, stores, secret resolver, and
- *  delivery chokepoint. Tests inject fakes. */
-export function defaultWebhookProcessDeps() {
-    return {
-        checkRate: (key) => sharedRateLimiter.checkRate(key),
-        resolveRoute: (channel, routingKey) => resolveRoute(channel, routingKey),
-        resolveSecret,
-        claimWebhookDelivery,
-        setWebhookDeliveryState,
-        deliverTrigger: (input) => deliverTrigger(input),
-        now: () => new Date(),
-    };
-}
-/** Coarse hour bucket bounding the replay table + defining the replay window. */
-function replayWindowStart(now) {
-    const bucket = new Date(now.getTime());
-    bucket.setUTCMinutes(0, 0, 0);
-    return bucket.toISOString();
-}
-/** Strip an optional `sha256=` prefix and normalize to lowercase hex. */
-function normalizeSignature(raw) {
-    const trimmed = raw.trim();
-    const eq = trimmed.indexOf('=');
-    const value = trimmed.slice(0, eq).toLowerCase() === 'sha256' ? trimmed.slice(eq + 1) : trimmed;
-    return value.trim().toLowerCase();
-}
-/** Constant-time HMAC-SHA256 verification over the raw body. Returns false on
- *  any malformed/absent signature or length mismatch — never throws. */
-function verifySignature(secret, rawBody, signatureHeader) {
-    if (signatureHeader === null || signatureHeader.trim() === '')
-        return false;
-    const provided = normalizeSignature(signatureHeader);
-    if (!/^[0-9a-f]+$/.test(provided) || provided.length % 2 !== 0)
-        return false;
-    const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
-    const providedBuf = Buffer.from(provided, 'hex');
-    const expectedBuf = Buffer.from(expected, 'hex');
-    if (providedBuf.length !== expectedBuf.length)
-        return false;
-    return timingSafeEqual(providedBuf, expectedBuf);
-}
-function sha256Hex(input) {
-    return createHash('sha256').update(input).digest('hex');
-}
-/** Parse the untrusted body into the envelope payload. JSON when the content
- *  type is JSON and it parses; otherwise the raw UTF-8 string. Malformed JSON
- *  is delivered as the raw string rather than rejected — payload is untrusted
- *  data the home narrows defensively, not something ingress validates. */
-function parsePayload(rawBody, contentType) {
-    const text = rawBody.toString('utf8');
-    if (contentType !== null && /application\/(?:[\w.+-]+\+)?json/i.test(contentType)) {
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            return text;
-        }
-    }
-    return text;
-}
-/**
- * The verification + delivery core, independent of HTTP plumbing so the
- * security invariants (signature, replay, no-routing-key) are directly
- * testable. Returns the status + message the HTTP layer writes back.
- */
-export async function processWebhookDelivery(req, deps) {
-    // 1. Pre-resolution rate limit.
-    const rate = deps.checkRate(req.routingKey);
-    if (!rate.ok) {
-        return { status: 429, message: 'rate limited', retryAfterMs: rate.retryAfterMs };
-    }
-    // 2. Route lookup.
-    const route = deps.resolveRoute('webhook', req.routingKey);
-    if (route === null || route.channel !== 'webhook') {
-        return { status: 404, message: 'unknown webhook route' };
-    }
-    // 3. Signature verification over the raw body. A route with no signing
-    //    secret cannot be verified and is treated as unverifiable — no delivery.
-    if (route.channel_secret_ref === null || route.channel_secret_ref.trim() === '') {
-        return { status: 503, message: 'webhook route not verifiable' };
-    }
-    let secret;
-    try {
-        secret = deps.resolveSecret(route.channel_secret_ref);
-    }
-    catch {
-        return { status: 503, message: 'webhook route not verifiable' };
-    }
-    if (!verifySignature(secret, req.rawBody, req.signatureHeader)) {
-        return { status: 401, message: 'invalid signature' };
-    }
-    // 4. Replay / idempotency. A bad signature never reached here, so no
-    //    delivery row is ever written for an unverified request.
-    const now = deps.now();
-    const payloadSha256 = sha256Hex(req.rawBody);
-    const signatureSha256 = req.signatureHeader === null ? null : sha256Hex(req.signatureHeader);
-    const replayKey = req.deliveryIdHeader !== null && req.deliveryIdHeader.trim() !== '' ? req.deliveryIdHeader.trim() : payloadSha256;
-    const windowStart = replayWindowStart(now);
-    const claim = deps.claimWebhookDelivery({
-        route_id: route.route_id,
-        replay_key: replayKey,
-        replay_window_start: windowStart,
-        payload_sha256: payloadSha256,
-        signature_sha256: signatureSha256,
-        received_at: now.toISOString(),
-    });
-    if (!claim.claimed) {
-        return { status: 200, message: 'duplicate delivery ignored' };
-    }
-    // 5. Envelope — routing key deliberately absent (R-ING-3); trigger_id is
-    //    route-derived + per-delivery for stable home-side dedupe.
-    const envelope = buildTriggerEnvelope({
-        source: 'webhook',
-        trigger_id: `${route.route_id}:${replayKey}`,
-        payload: parsePayload(req.rawBody, req.contentType),
-        received_at: now.toISOString(),
-    });
-    // 6. Deliver through the shared chokepoint (authorize + wake + exec + audit).
-    const outcome = await deps.deliverTrigger({
-        home_id: route.home_id,
-        source_ref: route.route_id,
-        envelope,
-        tier: 'urgent',
-        payload_sha256: payloadSha256,
-        metadata: { byte_length: req.rawBody.length, content_type: req.contentType },
-    });
-    if (outcome.outcome === 'delivered') {
-        deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'delivered');
-        return { status: 202, message: 'delivered' };
-    }
-    if (outcome.outcome === 'rejected') {
-        deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'rejected', { last_error: outcome.reason ?? 'rejected' });
-        return { status: 403, message: 'delivery rejected' };
-    }
-    deps.setWebhookDeliveryState(claim.delivery.delivery_id, 'failed', { last_error: outcome.reason ?? 'failed' });
-    return { status: 502, message: 'delivery failed' };
-}
-/** Extract the single `routing_key` path segment from `/webhook/<key>`.
- *  Rejects an empty key, extra segments, embedded slash/backslash, or
- *  malformed percent-encoding. */
-export function extractRoutingKey(pathname) {
-    const match = /^\/webhook\/([^/]+)$/.exec(pathname);
-    if (match === null)
-        return null;
-    const raw = match[1];
-    if (raw.includes('\\'))
-        return null;
-    let key;
-    try {
-        key = decodeURIComponent(raw);
-    }
-    catch {
-        return null;
-    }
-    if (key === '' || /[/\\]/.test(key))
-        return null;
-    return key;
-}
-function firstHeader(req, names) {
-    for (const name of names) {
-        const value = req.headers[name];
-        if (typeof value === 'string' && value.trim() !== '')
-            return value;
-        if (Array.isArray(value) && value.length > 0 && value[0].trim() !== '')
-            return value[0];
-    }
-    return null;
-}
-function readBody(req, maxBytes) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let total = 0;
-        let tooLarge = false;
-        req.on('data', (chunk) => {
-            total += chunk.length;
-            if (total > maxBytes) {
-                tooLarge = true;
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => resolve({ body: Buffer.concat(chunks), tooLarge }));
-        req.on('error', (error) => {
-            if (tooLarge) {
-                resolve({ body: Buffer.alloc(0), tooLarge: true });
-                return;
-            }
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
-}
-function maxBodyBytes(env = process.env) {
-    const raw = env[ENV.maxBodyBytes]?.trim();
-    if (raw === undefined || raw === '')
-        return DEFAULT_MAX_BODY_BYTES;
-    const parsed = Number(raw);
-    if (!Number.isInteger(parsed) || parsed <= 0)
-        return DEFAULT_MAX_BODY_BYTES;
-    return parsed;
-}
-function sendText(res, status, message, retryAfterMs) {
-    const headers = {
-        'content-type': 'text/plain; charset=utf-8',
-        'cache-control': 'no-store',
-        'referrer-policy': 'no-referrer',
-    };
-    if (retryAfterMs !== undefined)
-        headers['retry-after'] = String(Math.ceil(retryAfterMs / 1000));
-    const body = `${message}\n`;
-    headers['content-length'] = String(Buffer.byteLength(body));
-    res.writeHead(status, headers);
-    res.end(body);
-}
-/**
- * HTTP handler for `POST /webhook/:routing_key`. Reads the raw body (bounded),
- * extracts the routing key + signature/delivery headers, runs
- * `processWebhookDelivery`, and writes the resulting status. This is a PUBLIC
- * endpoint — its only authentication is the per-route HMAC signature, so it
- * must be mounted OUTSIDE the session/registry gate.
- */
-export async function handleWebhook(req, res, deps = defaultWebhookProcessDeps()) {
-    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-    const routingKey = extractRoutingKey(url.pathname);
-    if (routingKey === null) {
-        sendText(res, 404, 'unknown webhook route');
-        return;
-    }
-    const { body, tooLarge } = await readBody(req, maxBodyBytes());
-    if (tooLarge) {
-        sendText(res, 413, 'payload too large');
-        return;
-    }
-    const result = await processWebhookDelivery({
-        routingKey,
-        rawBody: body,
-        signatureHeader: firstHeader(req, SIGNATURE_HEADERS),
-        deliveryIdHeader: firstHeader(req, DELIVERY_ID_HEADERS),
-        contentType: firstHeader(req, ['content-type']),
-    }, deps);
-    sendText(res, result.status, result.message, result.retryAfterMs);
-}

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

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