opensquid 0.5.395

package/dist/runtime/versioning.js

@@ -0,0 +1,189 @@
+/**
+ * LP.2 — 3-way merge for vanilla pack upgrades.
+ *
+ * Compares 3 snapshots (base / personal / vanilla) → MergeResult with 4
+ * dispositions (unchanged / auto-merged-personal / auto-merged-vanilla /
+ * conflict). Emits `lesson_<n>.conflict.yaml` sidecars with YAML-comment-safe
+ * git-style markers on overlap. Updates `last_merged_vanilla` on success.
+ * Idempotent (same vanilla → noop). Throws on downgrade or missing
+ * version.json.
+ *
+ * Per [[feedback_stop_haiku_drift]] L4: text/YAML compare only; no LLM.
+ * Per [[feedback_simplest_granular_form]]: substring-based
+ * lessonReferencesSkill heuristic; semantic awareness deferred post-v1.
+ *
+ * Imports: src/packs/personal_revision.ts (LP.1), node:fs/promises, node:path.
+ * Imported by: LP.5 discovery upgrade detector, LP.4 CLI manual trigger.
+ */
+import { mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readLessonFiles, readVersionJson, writeVersionJson, } from '../packs/personal_revision.js';
+const SKIP_DIRS = new Set(['node_modules', '.git', '.opensquid', 'personal_revision']);
+const EXT_RE = /\.(yaml|yml|md)$/i;
+export async function runThreeWayMerge(input) {
+    const current = await readVersionJson(input.personalStateDir);
+    if (current === null) {
+        throw new Error(`runThreeWayMerge: ${input.packId} has no version.json — install pack first`);
+    }
+    if (semverCompare(input.vanillaVersion, current.base_version) < 0) {
+        throw new Error(`runThreeWayMerge: ${input.packId} — vanilla version ${input.vanillaVersion} must be >= base ${current.base_version}`);
+    }
+    if (current.last_merged_vanilla === input.vanillaVersion) {
+        return {
+            packId: input.packId,
+            baseVersion: current.base_version,
+            vanillaVersion: input.vanillaVersion,
+            personalRevisionId: current.personal_revision_id,
+            dispositions: [],
+            conflictCount: 0,
+            ok: true,
+            noop: true,
+        };
+    }
+    const baseFiles = await readPackTextFiles(input.baseDir);
+    const vanillaFiles = await readPackTextFiles(input.vanillaDir);
+    const personalLessons = await readLessonFiles(input.personalStateDir);
+    const dispositions = [];
+    const allSkillPaths = new Set([...Object.keys(baseFiles), ...Object.keys(vanillaFiles)]);
+    for (const path of allSkillPaths) {
+        const baseContent = baseFiles[path] ?? null;
+        const vanillaContent = vanillaFiles[path] ?? null;
+        if (baseContent === vanillaContent) {
+            dispositions.push({ kind: 'unchanged', path });
+            continue;
+        }
+        const personalTouch = personalLessons.find((l) => !l.hasConflict && lessonReferencesSkill(l, path));
+        if (personalTouch === undefined) {
+            dispositions.push({
+                kind: 'auto-merged-vanilla',
+                path,
+                reason: 'vanilla-only-edit',
+            });
+            continue;
+        }
+        const conflictSidecar = await emitConflictSidecar(personalTouch, baseContent ?? '', vanillaContent ?? '', input.vanillaVersion);
+        dispositions.push({
+            kind: 'conflict',
+            path,
+            conflictSidecarPath: conflictSidecar,
+        });
+    }
+    // Personal-only lessons (touch files vanilla didn't change) → preserve.
+    for (const lesson of personalLessons) {
+        if (lesson.hasConflict)
+            continue;
+        const alreadyDisposed = dispositions.some((d) => d.kind === 'conflict' && d.conflictSidecarPath.includes(`lesson_${String(lesson.id)}.`));
+        if (alreadyDisposed)
+            continue;
+        dispositions.push({
+            kind: 'auto-merged-personal',
+            path: lesson.path,
+            reason: 'personal-only-edit',
+        });
+    }
+    await writeVersionJson(input.personalStateDir, {
+        ...current,
+        last_merged_vanilla: input.vanillaVersion,
+    });
+    return {
+        packId: input.packId,
+        baseVersion: current.base_version,
+        vanillaVersion: input.vanillaVersion,
+        personalRevisionId: current.personal_revision_id,
+        dispositions,
+        conflictCount: dispositions.filter((d) => d.kind === 'conflict').length,
+        ok: true,
+        noop: false,
+    };
+}
+/**
+ * Recursively read all .yaml/.yml/.md text files in a pack directory into a
+ * map of (relative-path → file content). Skips node_modules/.git/.opensquid/
+ * personal_revision. Returns empty map if dir is missing. Path-traversal
+ * defense: relative() output starting with '..' is rejected.
+ */
+async function readPackTextFiles(dir) {
+    const out = {};
+    await walk(dir, dir, out);
+    return out;
+}
+async function walk(root, current, out) {
+    let entries;
+    try {
+        entries = await readdir(current);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const full = join(current, name);
+        let s;
+        try {
+            s = await stat(full);
+        }
+        catch {
+            continue;
+        }
+        if (s.isDirectory()) {
+            await walk(root, full, out);
+            continue;
+        }
+        if (!EXT_RE.test(name))
+            continue;
+        const rel = relative(root, full);
+        if (rel.startsWith('..'))
+            continue;
+        out[rel] = await readFile(full, 'utf8');
+    }
+}
+function lessonReferencesSkill(lesson, skillPath) {
+    const skillField = lesson.body.skill;
+    if (typeof skillField === 'string' && skillField === skillPath)
+        return true;
+    return JSON.stringify(lesson.body).includes(skillPath);
+}
+async function emitConflictSidecar(lesson, baseContent, vanillaContent, vanillaVersion) {
+    const sidecarPath = lesson.path.replace(/\.yaml$/, '.conflict.yaml');
+    const baseLines = baseContent.split('\n').map((l) => `# ${l}`);
+    const vanillaLines = vanillaContent.split('\n').map((l) => `# ${l}`);
+    const header = [
+        '# CONFLICT: vanilla bump overlaps with personal_revision edit.',
+        '# Resolve by removing marker lines + keeping desired content,',
+        '# then rename this file back to lesson_<n>.yaml.',
+        '#',
+        '# <<<<<<< base',
+        ...baseLines,
+        '# =======',
+        ...vanillaLines,
+        `# >>>>>>> vanilla ${vanillaVersion}`,
+        '',
+    ].join('\n');
+    const originalBody = await readFile(lesson.path, 'utf8');
+    await mkdir(join(sidecarPath, '..'), { recursive: true }).catch(() => undefined);
+    const tmp = `${sidecarPath}.tmp.${String(process.pid)}.${randSuffix()}`;
+    await writeFile(tmp, header + originalBody, 'utf8');
+    await rename(tmp, sidecarPath);
+    return sidecarPath;
+}
+/** Naive semver comparator — sufficient for v1 (BaseVersion regex constrains shape). */
+function semverCompare(a, b) {
+    const parsePart = (s) => s
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10));
+    const av = parsePart(a);
+    const bv = parsePart(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (av[i] ?? 0) - (bv[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+function randSuffix() {
+    const t = process.hrtime.bigint();
+    return (t & 0xffffffffn).toString(16).padStart(8, '0');
+}
+//# sourceMappingURL=versioning.js.map

package/dist/runtime/versioning.js.map

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

package/dist/runtime/webhook_server.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Webhook intake — single-route http.Server that verifies HMAC, dedups via
+ * an in-memory idempotency cache, and hands a `WebhookEvent` to the daemon
+ * dispatcher. Source: SCHED.1.
+ *
+ * Route: `POST /webhook/<subscription_id>` only — multiplexing live trigger
+ * sources (schedule, file_changed, inbound_channel) belongs to the daemon,
+ * not the HTTP layer.
+ *
+ * HMAC: header `X-OpenSquid-Signature: sha256=<lowercase-hex>`, body is the
+ * raw request bytes (never re-JSON-serialized — that would re-key the
+ * payload and invalidate any external signature). Compare via
+ * `crypto.timingSafeEqual` on equal-length buffers; even on length mismatch
+ * we still exercise the constant-time path to deny header-length probing.
+ * No fallback header name — provider-specific signatures (Stripe etc.) land
+ * as future adapter tasks.
+ *
+ * Idempotency: `Map<key, ts>` keyed `subscription_id:sha256(body)`. Duplicate
+ * POSTs within `idempotencyTtlMs` (default 24h) return 200 + `idempotent:
+ * true` and skip dispatch. A `setInterval` evicts stale entries hourly and
+ * is `.unref()`'d so it never holds the process open. In-memory only —
+ * restart loses the dedup window. DURABLE.4 may migrate to libsql later.
+ *
+ * Rate-limit: when `subscription.rateLimit` is set, the server consults the
+ * daemon-provided `RateLimiter` under trigger kind `'webhook'`. Denied
+ * webhooks return 429 + `Retry-After` (seconds). Never silently drop;
+ * never silently allow.
+ *
+ * Logging discipline: the server NEVER logs `signingSecret` (audits carry
+ * subscription id only) and NEVER logs request bodies (PII / bearer
+ * tokens / carrier creds).
+ */
+import type { WebhookEvent } from './event.js';
+import type { RateLimiter } from './rate_limit.js';
+import type { Subscription } from './webhook_subscriptions.js';
+/** Audit sink — caller plugs in a libsql writer / stderr / NotificationRouter. */
+export type WebhookAuditEntry = {
+    event: 'received';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'rejected_hmac';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'rejected_unknown';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'rejected_method';
+    method: string;
+    receivedAt: string;
+} | {
+    event: 'rejected_rate_limit';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'idempotent';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'dispatched';
+    subscriptionId: string;
+    receivedAt: string;
+} | {
+    event: 'deliver_only';
+    subscriptionId: string;
+    receivedAt: string;
+    rendered: boolean;
+    reason?: 'empty_template' | 'multicast_error' | 'misconfigured';
+    emptyFieldCount?: number;
+    redactedSecrets?: number;
+    multicastSent?: number;
+    multicastFailed?: number;
+} | {
+    event: 'error';
+    reason: string;
+    receivedAt: string;
+};
+export type WebhookAuditSink = (entry: WebhookAuditEntry) => void;
+/** What the daemon hands the server for an authenticated webhook. */
+export type WebhookDispatcher = (event: WebhookEvent) => Promise<void>;
+/**
+ * SCHED.2 zero-LLM handler. Caller supplies a closure that wires the
+ * NotificationRouter + RoutingConfig; the server invokes it for any
+ * subscription with `deliverOnly: true`. Returning a result lets the
+ * server audit the outcome without coupling to mustache or channels.
+ */
+export type DeliverOnlyHandler = (sub: Subscription, body: unknown) => Promise<{
+    rendered: boolean;
+    reason?: 'empty_template' | 'multicast_error' | 'misconfigured';
+    emptyFieldCount?: number;
+    redactedSecrets?: number;
+    multicast?: {
+        sent: number;
+        failed: number;
+    };
+}>;
+export interface WebhookServerOpts {
+    port: number;
+    /** `'127.0.0.1'` (default) keeps the server unreachable from LAN. */
+    host?: string;
+    subscriptions: readonly Subscription[];
+    dispatch: WebhookDispatcher;
+    /** SCHED.2 — invoked for subscriptions with `deliverOnly: true`. When
+     *  unset, deliver-only subscriptions audit as `misconfigured` and the
+     *  request still returns 200 (never break on missing handler). */
+    deliverOnly?: DeliverOnlyHandler;
+    rateLimiter?: RateLimiter;
+    auditLog?: WebhookAuditSink;
+    /** Injected clock for tests. */
+    now?: () => number;
+    /** Idempotency window. Default 24h. */
+    idempotencyTtlMs?: number;
+}
+/**
+ * `http.Server` wrapper. Caller `start()`s once; `close()` waits for the
+ * connection drain + clears the eviction timer. Restart = new instance.
+ */
+export declare class WebhookServer {
+    private readonly opts;
+    private readonly server;
+    private readonly subscriptions;
+    private readonly dispatch;
+    private readonly deliverOnly;
+    private readonly rateLimiter;
+    private readonly auditLog;
+    private readonly nowFn;
+    private readonly idempotencyTtlMs;
+    private readonly idempotencyCache;
+    private evictTimer;
+    private listening;
+    constructor(opts: WebhookServerOpts);
+    /** Bind to the configured port + start the eviction timer. */
+    start(): Promise<void>;
+    /** Stop accepting new connections, drain in-flight, clear the timer. */
+    close(): Promise<void>;
+    /** `Server.address()` resolves to a port number after `listen()` returns. */
+    address(): {
+        port: number;
+        host: string;
+    } | null;
+    private handle;
+    private evictIdempotencyCache;
+}
+//# sourceMappingURL=webhook_server.d.ts.map

package/dist/runtime/webhook_server.d.ts.map

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

package/dist/runtime/webhook_server.js

@@ -0,0 +1,301 @@
+/**
+ * Webhook intake — single-route http.Server that verifies HMAC, dedups via
+ * an in-memory idempotency cache, and hands a `WebhookEvent` to the daemon
+ * dispatcher. Source: SCHED.1.
+ *
+ * Route: `POST /webhook/<subscription_id>` only — multiplexing live trigger
+ * sources (schedule, file_changed, inbound_channel) belongs to the daemon,
+ * not the HTTP layer.
+ *
+ * HMAC: header `X-OpenSquid-Signature: sha256=<lowercase-hex>`, body is the
+ * raw request bytes (never re-JSON-serialized — that would re-key the
+ * payload and invalidate any external signature). Compare via
+ * `crypto.timingSafeEqual` on equal-length buffers; even on length mismatch
+ * we still exercise the constant-time path to deny header-length probing.
+ * No fallback header name — provider-specific signatures (Stripe etc.) land
+ * as future adapter tasks.
+ *
+ * Idempotency: `Map<key, ts>` keyed `subscription_id:sha256(body)`. Duplicate
+ * POSTs within `idempotencyTtlMs` (default 24h) return 200 + `idempotent:
+ * true` and skip dispatch. A `setInterval` evicts stale entries hourly and
+ * is `.unref()`'d so it never holds the process open. In-memory only —
+ * restart loses the dedup window. DURABLE.4 may migrate to libsql later.
+ *
+ * Rate-limit: when `subscription.rateLimit` is set, the server consults the
+ * daemon-provided `RateLimiter` under trigger kind `'webhook'`. Denied
+ * webhooks return 429 + `Retry-After` (seconds). Never silently drop;
+ * never silently allow.
+ *
+ * Logging discipline: the server NEVER logs `signingSecret` (audits carry
+ * subscription id only) and NEVER logs request bodies (PII / bearer
+ * tokens / carrier creds).
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+/** 24h in ms — locked per spec. */
+const DEFAULT_IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+const IDEMPOTENCY_EVICT_INTERVAL_MS = 60 * 60 * 1000;
+const MAX_BODY_BYTES = 5 * 1024 * 1024; // 5MB — bound memory; configurable later.
+const noopAudit = () => {
+    /* default audit sink (named to satisfy eslint no-empty-function) */
+};
+/**
+ * `http.Server` wrapper. Caller `start()`s once; `close()` waits for the
+ * connection drain + clears the eviction timer. Restart = new instance.
+ */
+export class WebhookServer {
+    opts;
+    server;
+    subscriptions;
+    dispatch;
+    deliverOnly;
+    rateLimiter;
+    auditLog;
+    nowFn;
+    idempotencyTtlMs;
+    idempotencyCache = new Map();
+    evictTimer = null;
+    listening = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.subscriptions = new Map(opts.subscriptions.map((s) => [s.id, s]));
+        this.dispatch = opts.dispatch;
+        this.deliverOnly = opts.deliverOnly;
+        this.rateLimiter = opts.rateLimiter;
+        this.auditLog = opts.auditLog ?? noopAudit;
+        this.nowFn = opts.now ?? Date.now;
+        this.idempotencyTtlMs = opts.idempotencyTtlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+        this.server = createServer((req, res) => {
+            this.handle(req, res).catch((err) => {
+                this.auditLog({
+                    event: 'error',
+                    reason: err instanceof Error ? err.message : String(err),
+                    receivedAt: new Date(this.nowFn()).toISOString(),
+                });
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'internal_error' }));
+                }
+            });
+        });
+    }
+    /** Bind to the configured port + start the eviction timer. */
+    start() {
+        if (this.listening)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const host = this.opts.host ?? '127.0.0.1';
+            const onError = (err) => reject(err);
+            this.server.once('error', onError);
+            this.server.listen(this.opts.port, host, () => {
+                this.server.off('error', onError);
+                this.listening = true;
+                this.evictTimer = setInterval(() => this.evictIdempotencyCache(), IDEMPOTENCY_EVICT_INTERVAL_MS);
+                this.evictTimer.unref();
+                resolve();
+            });
+        });
+    }
+    /** Stop accepting new connections, drain in-flight, clear the timer. */
+    async close() {
+        if (!this.listening)
+            return;
+        if (this.evictTimer) {
+            clearInterval(this.evictTimer);
+            this.evictTimer = null;
+        }
+        await new Promise((resolve, reject) => {
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+        this.listening = false;
+    }
+    /** `Server.address()` resolves to a port number after `listen()` returns. */
+    address() {
+        const addr = this.server.address();
+        if (addr === null || typeof addr === 'string')
+            return null;
+        return { port: addr.port, host: addr.address };
+    }
+    async handle(req, res) {
+        const receivedAt = new Date(this.nowFn()).toISOString();
+        if (req.method !== 'POST') {
+            this.auditLog({ event: 'rejected_method', method: req.method ?? '<unknown>', receivedAt });
+            return sendJson(res, 405, { error: 'method_not_allowed' }, { allow: 'POST' });
+        }
+        const match = /^\/webhook\/([A-Za-z0-9._-]+)\/?$/.exec((req.url ?? '').split('?')[0] ?? '');
+        if (!match)
+            return sendJson(res, 404, { error: 'not_found' });
+        const subscriptionId = match[1] ?? '';
+        const sub = this.subscriptions.get(subscriptionId);
+        if (!sub) {
+            this.auditLog({ event: 'rejected_unknown', subscriptionId, receivedAt });
+            return sendJson(res, 404, { error: 'unknown_subscription' });
+        }
+        const body = await readBody(req);
+        if (body === null)
+            return sendJson(res, 413, { error: 'body_too_large' });
+        const sigHeader = req.headers['x-opensquid-signature'] ?? req.headers['X-OpenSquid-Signature'];
+        const provided = typeof sigHeader === 'string' ? sigHeader : '';
+        if (!verifyHmac(sub.signingSecret, body, provided)) {
+            this.auditLog({ event: 'rejected_hmac', subscriptionId, receivedAt });
+            return sendJson(res, 401, { error: 'invalid_signature' });
+        }
+        if (sub.rateLimit && this.rateLimiter) {
+            const decision = await this.rateLimiter.check(sub.pack, 'webhook', sub.id);
+            if (!decision.allowed) {
+                const retrySec = String(Math.max(1, Math.ceil((decision.retryAfterMs ?? 1000) / 1000)));
+                this.auditLog({ event: 'rejected_rate_limit', subscriptionId, receivedAt });
+                return sendJson(res, 429, { error: 'rate_limit_exceeded', reason: decision.reason }, { 'retry-after': retrySec });
+            }
+        }
+        const dedupKey = `${sub.id}:${createHash('sha256').update(body).digest('hex')}`;
+        const now = this.nowFn();
+        const seenAt = this.idempotencyCache.get(dedupKey);
+        if (seenAt !== undefined && now - seenAt < this.idempotencyTtlMs) {
+            this.auditLog({ event: 'idempotent', subscriptionId, receivedAt });
+            return sendJson(res, 200, { idempotent: true, subscriptionId: sub.id });
+        }
+        this.idempotencyCache.set(dedupKey, now);
+        this.auditLog({ event: 'received', subscriptionId, receivedAt });
+        // SCHED.2: deliver-only subscriptions skip the runtime evaluator
+        // entirely. Mustache-render the body straight into the
+        // NotificationRouter — zero LLM invocation, sub-second response.
+        if (sub.deliverOnly) {
+            const event = buildWebhookEvent(sub.id, req, body, receivedAt);
+            if (this.deliverOnly) {
+                const result = await this.deliverOnly(sub, event.body);
+                this.auditLog({
+                    event: 'deliver_only',
+                    subscriptionId,
+                    receivedAt,
+                    rendered: result.rendered,
+                    ...(result.reason ? { reason: result.reason } : {}),
+                    ...(result.emptyFieldCount !== undefined
+                        ? { emptyFieldCount: result.emptyFieldCount }
+                        : {}),
+                    ...(result.redactedSecrets !== undefined
+                        ? { redactedSecrets: result.redactedSecrets }
+                        : {}),
+                    ...(result.multicast
+                        ? {
+                            multicastSent: result.multicast.sent,
+                            multicastFailed: result.multicast.failed,
+                        }
+                        : {}),
+                });
+                return sendJson(res, 200, {
+                    accepted: true,
+                    subscriptionId: sub.id,
+                    delivered: result.rendered,
+                    ...(result.reason ? { reason: result.reason } : {}),
+                });
+            }
+            // Handler unset — audit + return 200 (don't break the integration).
+            this.auditLog({
+                event: 'deliver_only',
+                subscriptionId,
+                receivedAt,
+                rendered: false,
+                reason: 'misconfigured',
+            });
+            return sendJson(res, 200, {
+                accepted: true,
+                subscriptionId: sub.id,
+                delivered: false,
+                reason: 'misconfigured',
+            });
+        }
+        await this.dispatch(buildWebhookEvent(sub.id, req, body, receivedAt));
+        this.auditLog({ event: 'dispatched', subscriptionId, receivedAt });
+        return sendJson(res, 200, { accepted: true, subscriptionId: sub.id });
+    }
+    evictIdempotencyCache() {
+        const cutoff = this.nowFn() - this.idempotencyTtlMs;
+        for (const [k, ts] of this.idempotencyCache) {
+            if (ts < cutoff)
+                this.idempotencyCache.delete(k);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Response + HMAC + body helpers — module-local so they're testable in
+// isolation but not part of the WebhookServer's public surface.
+function sendJson(res, status, body, extraHeaders = {}) {
+    res.writeHead(status, { 'content-type': 'application/json', ...extraHeaders });
+    res.end(JSON.stringify(body));
+}
+/** Constant-time HMAC compare. Returns false on any malformed header. */
+function verifyHmac(secret, body, header) {
+    if (!header)
+        return false;
+    const match = /^sha256=([0-9a-fA-F]+)$/.exec(header.trim());
+    if (!match)
+        return false;
+    const providedHex = (match[1] ?? '').toLowerCase();
+    const expectedHex = createHmac('sha256', secret).update(body).digest('hex');
+    const providedBuf = Buffer.from(providedHex, 'hex');
+    const expectedBuf = Buffer.from(expectedHex, 'hex');
+    // Always run timingSafeEqual against equal-length buffers to keep the
+    // compare constant-time regardless of header length.
+    if (providedBuf.length !== expectedBuf.length) {
+        timingSafeEqual(expectedBuf, expectedBuf); // exercise the path
+        return false;
+    }
+    return timingSafeEqual(providedBuf, expectedBuf);
+}
+/** Read up to `MAX_BODY_BYTES`. Returns `null` if cap exceeded. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let received = 0;
+        req.on('data', (chunk) => {
+            received += chunk.length;
+            if (received > MAX_BODY_BYTES) {
+                req.destroy();
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', (err) => reject(err));
+    });
+}
+/** Build the `WebhookEvent` payload the runtime evaluator consumes. */
+function buildWebhookEvent(subscriptionId, req, body, receivedAt) {
+    // Headers in node:http arrive as `string | string[] | undefined`. The
+    // Event schema requires `Record<string, string>`; flatten arrays to a
+    // comma-joined string so downstream rules see a stable shape.
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined)
+            continue;
+        headers[k] = Array.isArray(v) ? v.join(',') : v;
+    }
+    // Body parse: best-effort JSON, fall back to raw text. Anything binary
+    // becomes a base64 string under `__binary` — pack rules that care can
+    // decode it explicitly via `from_base64`.
+    let parsedBody;
+    try {
+        parsedBody = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        const text = body.toString('utf8');
+        // Detect non-UTF8 body: a round-trip through UTF-8 lossily replaces
+        // non-decodable bytes with U+FFFD. If the byte counts differ, treat
+        // as binary.
+        parsedBody =
+            Buffer.byteLength(text, 'utf8') === body.length
+                ? text
+                : { __binary: body.toString('base64') };
+    }
+    return {
+        kind: 'webhook',
+        subscriptionId,
+        method: (req.method ?? 'POST'),
+        headers,
+        body: parsedBody,
+        receivedAt,
+    };
+}
+//# sourceMappingURL=webhook_server.js.map