@uptimizr/collector-server 2.1.0 → 2.2.0

package/dist/subscriptions/scheduler.js

@@ -0,0 +1,332 @@
+import { isBusBackedPredicate, parseDurationMs } from "@uptimizr/schema";
+import { getMetric } from "@uptimizr/metrics";
+import { evaluateSubscription, summaryFor, toFiring } from "./evaluate.js";
+import { deliver } from "./delivery.js";
+/**
+ * **The subscription scheduler** (#311, ADR 0051 §6 / sketch §F.2).
+ *
+ * One in-process scheduler for the whole collector. Its job is small and its
+ * constraints are the interesting part:
+ *
+ * - **Every subscription owns one timer**, firing on its own `evaluate.every`.
+ *   Even the bus-backed predicates have one: `presence <= 0` ("nobody is in the
+ *   scene") can only become true when events *stop* arriving, so a scheduler
+ *   that only woke on bus traffic could never report it.
+ * - **The bus is an accelerator, not the clock.** `presence` and `new_value`
+ *   additionally watch `LiveBus.subscribe` so they react in seconds rather than
+ *   at the next tick. The state each one keeps is bounded
+ *   ({@link NEW_VALUE_MAX_TRIGGERS}) and the trigger is rate-limited
+ *   ({@link BUS_MIN_INTERVAL_MS}), so a firehose cannot turn into a query storm.
+ *   The *answer* still comes from the store evaluation, so the bus can only
+ *   change when a subscription is checked, never what it concludes.
+ * - **At most {@link CollectorConfig.subscriptionsMaxConcurrent} evaluations run
+ *   at once**, and at most one per subscription. A tick that arrives while the
+ *   previous one is still in flight is dropped, not queued — a subscription that
+ *   cannot keep up with its own interval must not grow a backlog.
+ * - **Cooldown is enforced before delivery, not before evaluation.** The
+ *   evaluation is cheap and its result is what `POST …/test` and the dashboard
+ *   read; the *firing* is what costs a webhook.
+ * - **Every timer is `unref`'d and cleared by {@link SubscriptionScheduler.stop}.**
+ *   A test that starts the scheduler and closes the app leaves nothing behind.
+ */
+/** Smallest gap between two bus-triggered evaluations of one subscription. */
+export const BUS_MIN_INTERVAL_MS = 5_000;
+/**
+ * Distinct dimension values one `new_value` watcher remembers having triggered
+ * on. Past this the set is cleared and the watcher falls back to its timer — the
+ * predicate is for low-cardinality dimensions ("a new scene", "a new custom
+ * event"), and an unbounded set on a hot bus is exactly the kind of state
+ * ADR 0032 §6 exists to prevent.
+ */
+export const NEW_VALUE_MAX_TRIGGERS = 256;
+/** How often the scheduler re-reads the store to pick up external changes. */
+export const RELOAD_INTERVAL_MS = 60_000;
+/** Promoted event fields a `new_value` dimension maps to on a live event. */
+const EVENT_FIELD = {
+    scene: "sceneId",
+    name: "name",
+    mesh: "mesh",
+    source: "source",
+};
+/** Read one promoted dimension value off a live event. */
+function dimensionValueOf(event, dimension) {
+    const field = EVENT_FIELD[dimension];
+    if (field == null)
+        return null;
+    const value = event[field];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Create the scheduler. It does nothing until {@link SubscriptionScheduler.reload}
+ * is called, which `app.ts` does once at startup and every CRUD write does after
+ * it changes something.
+ */
+export function createSubscriptionScheduler(deps) {
+    const now = deps.now ?? Date.now;
+    const maxConcurrent = Math.max(1, deps.config.subscriptionsMaxConcurrent);
+    const slots = new Map();
+    const watchers = new Map();
+    let inFlight = 0;
+    let stopped = false;
+    let reloadTimer = null;
+    /** The registry entry a subscription watches, or `null` if it went away. */
+    function metricOf(sub) {
+        return getMetric(sub.metric) ?? null;
+    }
+    /**
+     * Run one evaluation, respecting the global concurrency cap and the
+     * one-per-subscription rule.
+     *
+     * Returns `null` when the slot was busy or the cap was full — a dropped tick,
+     * which is the correct answer for a periodic check whose previous run has not
+     * finished. Queueing them would build exactly the backlog the cap exists to
+     * prevent.
+     */
+    async function tick(slot, options = {}) {
+        if (stopped || slot.running || inFlight >= maxConcurrent)
+            return null;
+        slot.running = true;
+        inFlight += 1;
+        try {
+            return await evaluateAndDeliver(slot.sub, options);
+        }
+        catch (err) {
+            deps.log.warn({ err, subscription: slot.sub.id }, "subscription evaluation failed");
+            return null;
+        }
+        finally {
+            inFlight -= 1;
+            slot.running = false;
+        }
+    }
+    /** Evaluate, then record + deliver when it fired and is out of cooldown. */
+    async function evaluateAndDeliver(sub, options) {
+        const metric = metricOf(sub);
+        if (metric == null) {
+            throw new Error(`subscription ${sub.id} names unknown metric ${JSON.stringify(sub.metric)}`);
+        }
+        const result = await evaluateSubscription({
+            readBuckets: (opts) => deps.store.metricBuckets(sub.projectId, opts),
+            activeSessions: () => deps.liveBus.presence(sub.projectId).activeSessions,
+            now,
+        }, sub, metric);
+        if (!result.fired || options.deliver === false)
+            return result;
+        const at = now();
+        const cooldownMs = parseDurationMs(sub.cooldown) ?? 0;
+        if (sub.lastFiredAt != null && at - sub.lastFiredAt.getTime() < cooldownMs)
+            return result;
+        const firing = toFiring(sub, result, at);
+        const summary = summaryFor(sub, result);
+        // The firing is recorded before it is delivered: a webhook that times out
+        // must still leave evidence that the condition was met.
+        await deps.store.recordSubscriptionEvent({
+            subscriptionId: sub.id,
+            projectId: sub.projectId,
+            at: new Date(at),
+            payload: { ...firing, summary },
+        });
+        let outcome;
+        try {
+            outcome = await deliver(sub, firing, summary, {
+                broadcast: (f, s) => deps.stream.publish(sub.projectId, { firing: f, summary: s }),
+                secret: await deps.store.getWebhookSecret(sub.projectId, sub.id),
+                allowedHosts: deps.config.webhookAllowedHosts,
+                fetchImpl: deps.fetchImpl,
+                sleep: deps.sleep,
+            });
+        }
+        catch (err) {
+            outcome = {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                attempts: 0,
+                egress: false,
+            };
+        }
+        // `lastFiredAt` is stamped whether or not delivery succeeded: the condition
+        // fired, and a receiver that is down must not turn the cooldown off and let
+        // the subscription re-fire on every tick.
+        const failures = outcome.ok ? 0 : sub.failures + 1;
+        await deps.store.recordSubscriptionOutcome(sub.projectId, sub.id, {
+            firedAt: new Date(at),
+            lastError: outcome.error,
+            failures,
+        });
+        // Keep the in-memory slot in step so the cooldown holds until the next
+        // reload, rather than only in the row.
+        sub.lastFiredAt = new Date(at);
+        sub.failures = failures;
+        sub.lastError = outcome.error;
+        return result;
+    }
+    /** Attach the per-project bus watcher, creating it on first use. */
+    function ensureWatcher(projectId) {
+        if (watchers.has(projectId))
+            return;
+        const subscriber = deps.liveBus.subscribe({ projectId });
+        const watcher = { subscriber, stopped: false };
+        watchers.set(projectId, watcher);
+        const pump = async () => {
+            for await (const event of subscriber) {
+                if (watcher.stopped || stopped)
+                    break;
+                onEvent(projectId, event);
+            }
+        };
+        void pump();
+    }
+    /** Dispatch one arriving event to this project's bus-backed slots. */
+    function onEvent(projectId, event) {
+        const at = now();
+        for (const slot of slots.values()) {
+            if (slot.sub.projectId !== projectId)
+                continue;
+            if (!isBusBackedPredicate(slot.sub.predicate.kind))
+                continue;
+            if (at - slot.lastBusRun < BUS_MIN_INTERVAL_MS)
+                continue;
+            if (slot.sub.predicate.kind === "new_value") {
+                const value = dimensionValueOf(event, slot.sub.predicate.dimension);
+                // Only an unseen value is worth waking the store for. The set is this
+                // watcher's whole memory, and it is bounded.
+                if (value == null || slot.triggered.has(value))
+                    continue;
+                if (slot.triggered.size >= NEW_VALUE_MAX_TRIGGERS)
+                    slot.triggered.clear();
+                slot.triggered.add(value);
+            }
+            slot.lastBusRun = at;
+            void tick(slot);
+        }
+    }
+    /**
+     * Start one subscription's timer.
+     *
+     * The first evaluation is delayed by a jittered fraction of the interval, so
+     * a hundred subscriptions restored from the store on one boot spread their
+     * first reads across the interval instead of hitting the store together. From
+     * then on it is a plain interval — the phase set by the jitter persists,
+     * because `reload` deliberately does not restart a timer whose cadence is
+     * unchanged.
+     */
+    function schedule(sub) {
+        const everyMs = Math.max(parseDurationMs(sub.evaluate.every) ?? 60_000, 60_000);
+        const jitter = Math.floor(Math.min(Math.max(deps.jitter?.() ?? Math.random(), 0), 0.999) * everyMs);
+        const slot = {
+            sub,
+            start: null,
+            timer: null,
+            running: false,
+            lastBusRun: 0,
+            triggered: new Set(),
+        };
+        slot.start = setTimeout(() => {
+            slot.start = null;
+            void tick(slot);
+            slot.timer = setInterval(() => void tick(slot), everyMs);
+            slot.timer.unref?.();
+        }, jitter);
+        slot.start.unref?.();
+        slots.set(sub.id, slot);
+        if (isBusBackedPredicate(sub.predicate.kind))
+            ensureWatcher(sub.projectId);
+    }
+    function unschedule(id) {
+        const slot = slots.get(id);
+        if (slot == null)
+            return;
+        if (slot.start != null)
+            clearTimeout(slot.start);
+        if (slot.timer != null)
+            clearInterval(slot.timer);
+        slots.delete(id);
+    }
+    /**
+     * Reconcile timers and bus watchers against the store.
+     *
+     * A named function rather than only a method, because the periodic reconcile
+     * below schedules it: an arrow calling `this.reload()` would break the moment
+     * anyone destructured the scheduler.
+     */
+    async function reloadNow() {
+        if (stopped)
+            return;
+        let enabled;
+        try {
+            enabled = await deps.store.listEnabledSubscriptions();
+        }
+        catch (err) {
+            deps.log.warn({ err }, "failed to read subscriptions; keeping the current schedule");
+            return;
+        }
+        const wanted = new Map(enabled.map((sub) => [sub.id, sub]));
+        for (const id of [...slots.keys()])
+            if (!wanted.has(id))
+                unschedule(id);
+        for (const [id, sub] of wanted) {
+            const slot = slots.get(id);
+            if (slot == null) {
+                schedule(sub);
+                continue;
+            }
+            // Reschedule only when the cadence changed; otherwise keep the timer
+            // (and its phase) and just refresh the declaration, so a reload does not
+            // silently re-align every subscription to the same instant.
+            if (slot.sub.evaluate.every !== sub.evaluate.every) {
+                unschedule(id);
+                schedule(sub);
+            }
+            else {
+                slot.sub = sub;
+            }
+        }
+        if (reloadTimer == null) {
+            // Another instance sharing a Postgres/SQL Server database can change the
+            // set without going through this process's routes.
+            reloadTimer = setInterval(() => void reloadNow(), RELOAD_INTERVAL_MS);
+            reloadTimer.unref?.();
+        }
+    }
+    return {
+        reload: reloadNow,
+        async runOnce(sub, options = {}) {
+            // An out-of-band run of a *scheduled* subscription takes the slot's
+            // one-in-flight guard, so `POST …/test` cannot race its own timer. A
+            // disabled (therefore unscheduled) subscription gets a fresh slot-less
+            // run, still under the global cap.
+            const slot = slots.get(sub.id);
+            if (slot != null)
+                return tick(slot, options);
+            if (stopped || inFlight >= maxConcurrent)
+                return null;
+            inFlight += 1;
+            try {
+                return await evaluateAndDeliver(sub, options);
+            }
+            finally {
+                inFlight -= 1;
+            }
+        },
+        get scheduledCount() {
+            return slots.size;
+        },
+        get inFlight() {
+            return inFlight;
+        },
+        stop() {
+            stopped = true;
+            if (reloadTimer != null)
+                clearInterval(reloadTimer);
+            reloadTimer = null;
+            for (const id of [...slots.keys()])
+                unschedule(id);
+            for (const watcher of watchers.values()) {
+                watcher.stopped = true;
+                watcher.subscriber.close();
+            }
+            watchers.clear();
+        },
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/subscriptions/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/subscriptions/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/subscriptions/stream.d.ts

@@ -0,0 +1,40 @@
+import type { SubscriptionFiring } from "@uptimizr/schema";
+/**
+ * **In-process fan-out for subscription firings** (#311, sketch §F.3).
+ *
+ * The SSE half of delivery. It is deliberately *not* the live bus: the live bus
+ * carries every ingested event and is hot, whereas this carries at most one
+ * message per subscription per cooldown and exists only so
+ * `GET /api/v1/subscriptions/stream` has something to read from. Keeping them
+ * apart means a firing can never be dropped by a slow live consumer's queue, and
+ * a subscription listener can never back-pressure ingest.
+ *
+ * Listeners are plain callbacks rather than async iterators because the SSE
+ * route writes synchronously to a socket; there is nothing to buffer, and
+ * nothing to bound beyond the connection cap the route already enforces.
+ */
+/** What an SSE listener receives. */
+export interface SubscriptionStreamMessage {
+    firing: SubscriptionFiring;
+    /** The same bounded `format=summary` block a webhook would carry. */
+    summary: Record<string, unknown> | null;
+}
+export type SubscriptionStreamListener = (message: SubscriptionStreamMessage) => void;
+export interface SubscriptionStreamOptions {
+    projectId: string;
+    /** Deliver only this subscription's firings; omit for the whole project. */
+    subscriptionId?: string;
+}
+export interface SubscriptionStream {
+    /** Register a listener. Returns an idempotent unsubscribe. */
+    subscribe(options: SubscriptionStreamOptions, listener: SubscriptionStreamListener): () => void;
+    /** Fan a firing out to matching listeners. */
+    publish(projectId: string, message: SubscriptionStreamMessage): void;
+    /** Open listener count (for tests and the connection accounting). */
+    readonly listenerCount: number;
+    /** Drop every listener. */
+    stop(): void;
+}
+/** Create the default in-process subscription stream. */
+export declare function createSubscriptionStream(): SubscriptionStream;
+//# sourceMappingURL=stream.d.ts.map

package/dist/subscriptions/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/subscriptions/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AAEH,qCAAqC;AACrC,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;AAEtF,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,QAAQ,EAAE,0BAA0B,GAAG,MAAM,IAAI,CAAC;IAChG,8CAA8C;IAC9C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACrE,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2BAA2B;IAC3B,IAAI,IAAI,IAAI,CAAC;CACd;AAOD,yDAAyD;AACzD,wBAAgB,wBAAwB,IAAI,kBAAkB,CAuC7D"}

package/dist/subscriptions/stream.js

@@ -0,0 +1,38 @@
+/** Create the default in-process subscription stream. */
+export function createSubscriptionStream() {
+    const entries = new Set();
+    return {
+        subscribe(options, listener) {
+            const entry = { options, listener };
+            entries.add(entry);
+            return () => {
+                entries.delete(entry);
+            };
+        },
+        publish(projectId, message) {
+            for (const entry of entries) {
+                if (entry.options.projectId !== projectId)
+                    continue;
+                if (entry.options.subscriptionId != null &&
+                    entry.options.subscriptionId !== message.firing.subscriptionId) {
+                    continue;
+                }
+                // A throwing listener is a broken socket, not a reason to abandon the
+                // rest of the fan-out.
+                try {
+                    entry.listener(message);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        },
+        get listenerCount() {
+            return entries.size;
+        },
+        stop() {
+            entries.clear();
+        },
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/subscriptions/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/subscriptions/stream.ts"],"names":[],"mappings":"AAgDA,yDAAyD;AACzD,MAAM,UAAU,wBAAwB;IACtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAS,CAAC;IAEjC,OAAO;QACL,SAAS,CAAC,OAAO,EAAE,QAAQ;YACzB,MAAM,KAAK,GAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,GAAG,EAAE;gBACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,SAAS,EAAE,OAAO;YACxB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;oBAAE,SAAS;gBACpD,IACE,KAAK,CAAC,OAAO,CAAC,cAAc,IAAI,IAAI;oBACpC,KAAK,CAAC,OAAO,CAAC,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,cAAc,EAC9D,CAAC;oBACD,SAAS;gBACX,CAAC;gBACD,sEAAsE;gBACtE,uBAAuB;gBACvB,IAAI,CAAC;oBACH,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAC1B,CAAC;gBAAC,MAAM,CAAC;oBACP,YAAY;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,aAAa;YACf,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;QAED,IAAI;YACF,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Semver of the running `@uptimizr/collector-server`, or `"unknown"`. */
+export declare const COLLECTOR_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAuBA,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,MAAsB,CAAC"}

package/dist/version.js

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+/**
+ * The running collector's package version, reported in the project context
+ * document (`GET /api/v1/context`, ADR 0051 §5) so an agent can tell an old
+ * self-hosted collector from a current one before it blames the data.
+ *
+ * Read from the package's own `package.json` at load time rather than hard-coded,
+ * so a Changesets release bump cannot drift from what the server reports. The
+ * lookup resolves relative to this module, which sits one directory below the
+ * package root both in `src/` (under Vitest) and in `dist/` (built). Any failure
+ * degrades to `"unknown"`: the version is descriptive metadata, and a collector
+ * that cannot read its own manifest must still serve.
+ */
+function readVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)("../package.json");
+        return typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Semver of the running `@uptimizr/collector-server`, or `"unknown"`. */
+export const COLLECTOR_VERSION = readVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAA0B,CAAC;QAC5F,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAW,WAAW,EAAE,CAAC"}

package/dist/webhookSignature.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Signing an outbound webhook body (ADR 0051 §6, design sketch §F.3/§F.4).
+ *
+ * Everything Uptimizr pushes out of a self-hoster's process — the scheduled
+ * agent report today, conditional-subscription deliveries next — is POSTed with
+ * an HMAC-SHA-256 of the **exact bytes sent**, so a receiver (Slack relay, a
+ * GitHub Action, the operator's own agent) can prove the payload came from their
+ * collector and was not modified in transit.
+ *
+ * The scheme, deliberately boring and identical to what every webhook consumer
+ * already knows how to verify:
+ *
+ * ```
+ * X-Uptimizr-Signature: sha256=<lowercase hex HMAC-SHA-256(secret, rawBody)>
+ * X-Uptimizr-Delivery:  <random id, unique per delivery attempt>
+ * ```
+ *
+ * Verification MUST be done over the raw request body **before** JSON parsing
+ * (re-serialising changes bytes) and MUST use a constant-time comparison —
+ * {@link verifyWebhookSignature} does both.
+ *
+ * No secret is ever logged, persisted or echoed: it is read from
+ * `UPTIMIZR_WEBHOOK_SECRET` at the point of use and passed straight to the HMAC.
+ */
+/** Header carrying `sha256=<hex>` over the raw body. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Uptimizr-Signature";
+/** Header carrying a unique id per delivery attempt (for receiver-side dedupe). */
+export declare const WEBHOOK_DELIVERY_HEADER = "X-Uptimizr-Delivery";
+/**
+ * Sign a raw body with the shared secret.
+ *
+ * @param secret The shared secret (`UPTIMIZR_WEBHOOK_SECRET`).
+ * @param body The exact bytes that will be sent as the request body.
+ * @returns The value for {@link WEBHOOK_SIGNATURE_HEADER} (`sha256=<hex>`).
+ */
+export declare function signWebhookBody(secret: string, body: string): string;
+/**
+ * Verify a received signature header against the raw body, in constant time.
+ *
+ * Returns `false` — never throws — for a missing header, the wrong prefix, a
+ * wrong-length digest or a mismatch, so a receiver can reject uniformly without
+ * leaking which check failed.
+ */
+export declare function verifyWebhookSignature(secret: string, body: string, header: string): boolean;
+/** A fresh delivery id for {@link WEBHOOK_DELIVERY_HEADER}. */
+export declare function newDeliveryId(): string;
+/**
+ * Validate an operator-supplied webhook URL.
+ *
+ * The URL comes from the command line (or, later, a stored subscription), so it
+ * is request-controlled input to an outbound request: only `http:` and `https:`
+ * are accepted, which rules out `file:`, `data:` and any other scheme a fetch
+ * implementation might honour. Host reachability is deliberately **not**
+ * restricted — a self-hoster posting to `http://localhost:3000/hook` or to an
+ * internal Slack relay is the normal case, and the collector is not a
+ * multi-tenant proxy — so the SSRF boundary here is the operator's own shell.
+ * Anything that later accepts a webhook URL over HTTP must add its own
+ * allow-list on top of this check.
+ *
+ * @returns The parsed URL.
+ * @throws If the value is not a syntactically valid `http(s)` URL.
+ */
+export declare function parseWebhookUrl(value: string): URL;
+//# sourceMappingURL=webhookSignature.d.ts.map

package/dist/webhookSignature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookSignature.d.ts","sourceRoot":"","sources":["../src/webhookSignature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAK7D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAO5F;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAalD"}

package/dist/webhookSignature.js

@@ -0,0 +1,91 @@
+/**
+ * Signing an outbound webhook body (ADR 0051 §6, design sketch §F.3/§F.4).
+ *
+ * Everything Uptimizr pushes out of a self-hoster's process — the scheduled
+ * agent report today, conditional-subscription deliveries next — is POSTed with
+ * an HMAC-SHA-256 of the **exact bytes sent**, so a receiver (Slack relay, a
+ * GitHub Action, the operator's own agent) can prove the payload came from their
+ * collector and was not modified in transit.
+ *
+ * The scheme, deliberately boring and identical to what every webhook consumer
+ * already knows how to verify:
+ *
+ * ```
+ * X-Uptimizr-Signature: sha256=<lowercase hex HMAC-SHA-256(secret, rawBody)>
+ * X-Uptimizr-Delivery:  <random id, unique per delivery attempt>
+ * ```
+ *
+ * Verification MUST be done over the raw request body **before** JSON parsing
+ * (re-serialising changes bytes) and MUST use a constant-time comparison —
+ * {@link verifyWebhookSignature} does both.
+ *
+ * No secret is ever logged, persisted or echoed: it is read from
+ * `UPTIMIZR_WEBHOOK_SECRET` at the point of use and passed straight to the HMAC.
+ */
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+/** Header carrying `sha256=<hex>` over the raw body. */
+export const WEBHOOK_SIGNATURE_HEADER = "X-Uptimizr-Signature";
+/** Header carrying a unique id per delivery attempt (for receiver-side dedupe). */
+export const WEBHOOK_DELIVERY_HEADER = "X-Uptimizr-Delivery";
+/** The algorithm prefix the signature header always carries. */
+const PREFIX = "sha256=";
+/**
+ * Sign a raw body with the shared secret.
+ *
+ * @param secret The shared secret (`UPTIMIZR_WEBHOOK_SECRET`).
+ * @param body The exact bytes that will be sent as the request body.
+ * @returns The value for {@link WEBHOOK_SIGNATURE_HEADER} (`sha256=<hex>`).
+ */
+export function signWebhookBody(secret, body) {
+    return `${PREFIX}${createHmac("sha256", secret).update(body, "utf8").digest("hex")}`;
+}
+/**
+ * Verify a received signature header against the raw body, in constant time.
+ *
+ * Returns `false` — never throws — for a missing header, the wrong prefix, a
+ * wrong-length digest or a mismatch, so a receiver can reject uniformly without
+ * leaking which check failed.
+ */
+export function verifyWebhookSignature(secret, body, header) {
+    if (!header.startsWith(PREFIX))
+        return false;
+    const expected = Buffer.from(signWebhookBody(secret, body), "utf8");
+    const received = Buffer.from(header, "utf8");
+    // `timingSafeEqual` throws on a length mismatch, which is not secret (the
+    // digest length is fixed and public), so compare lengths first.
+    return expected.length === received.length && timingSafeEqual(expected, received);
+}
+/** A fresh delivery id for {@link WEBHOOK_DELIVERY_HEADER}. */
+export function newDeliveryId() {
+    return randomUUID();
+}
+/**
+ * Validate an operator-supplied webhook URL.
+ *
+ * The URL comes from the command line (or, later, a stored subscription), so it
+ * is request-controlled input to an outbound request: only `http:` and `https:`
+ * are accepted, which rules out `file:`, `data:` and any other scheme a fetch
+ * implementation might honour. Host reachability is deliberately **not**
+ * restricted — a self-hoster posting to `http://localhost:3000/hook` or to an
+ * internal Slack relay is the normal case, and the collector is not a
+ * multi-tenant proxy — so the SSRF boundary here is the operator's own shell.
+ * Anything that later accepts a webhook URL over HTTP must add its own
+ * allow-list on top of this check.
+ *
+ * @returns The parsed URL.
+ * @throws If the value is not a syntactically valid `http(s)` URL.
+ */
+export function parseWebhookUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`--webhook must be an absolute http(s) URL (got ${JSON.stringify(value)}).`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`--webhook must use http or https (got ${JSON.stringify(url.protocol.replace(":", ""))}).`);
+    }
+    return url;
+}
+//# sourceMappingURL=webhookSignature.js.map

package/dist/webhookSignature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookSignature.js","sourceRoot":"","sources":["../src/webhookSignature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,wDAAwD;AACxD,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D,gEAAgE;AAChE,MAAM,MAAM,GAAG,SAAS,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IAC1D,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,IAAY,EAAE,MAAc;IACjF,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,gEAAgE;IAChE,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACpF,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,kDAAkD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,yCAAyC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}