@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/triggers/webhook.js

@@ -1,16 +1,3 @@
-/**
- * Public webhook trigger receiver for routines.
- *
- * A routine may declare a `trigger` block instead of (or alongside) a cron
- * `schedule` (see `JobConfig.trigger` in `../routines.ts`). This module turns
- * incoming GitHub or Linear webhooks into the set of routines they should fire,
- * and dispatches those routines through the exact same path a cron fire uses
- * (`executeJobDetached`).
- *
- * The matching logic is pure, so it can be unit-tested without a daemon or HTTP
- * server. The listener adds the public-ingress requirements: raw-body HMAC
- * verification, idempotency, source allow-listing, and rate limiting.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as http from 'http';
@@ -19,25 +6,14 @@ import { jobRunsOnThisDevice, listJobs, substituteWebhookPrompt } from '../sched
 import { executeJobDetached } from '../daemon/runner.js';
 import { emit } from '../feed/events.js';
 import { listHandlers, handlerMatchesWebhook, executeHandler, buildWebhookContext, } from './handlers.js';
-/** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export function webhookRepo(payload) {
     const repo = payload?.repository;
     const fullName = repo?.full_name;
     return typeof fullName === 'string' && fullName.length > 0 ? fullName : null;
 }
-/** Strip a `refs/heads/` (or `refs/tags/`) prefix to the short branch/tag name. */
 function shortRef(ref) {
     return ref.replace(/^refs\/(heads|tags)\//, '');
 }
-/**
- * Extract every candidate branch a webhook payload references, per event type.
- * A trigger's `branch` matches if it equals any of these. Different events
- * carry the branch in different places:
- *   - push:          `ref` (refs/heads/<b>)
- *   - pull_request:  base + head refs of the PR
- *   - workflow_run:  `workflow_run.head_branch`
- *   - issue_comment: no branch (comments aren't branch-scoped)
- */
 export function webhookBranches(event, payload) {
     const branches = new Set();
     const add = (v) => {
@@ -79,10 +55,6 @@ export function linearTeamKey(payload) {
     return typeof team?.key === 'string' ? team.key : null;
 }
 export function linearLabels(payload) {
-    // Linear webhook bodies flatten list relations: an Issue event carries
-    // `data.labels` as a flat array of label objects (`[{ id, name, color }]`),
-    // NOT the `{ nodes: [...] }` connection shape returned by the GraphQL API.
-    // Reading `.nodes` here made every `--label` filter match nothing.
     const data = payload.data;
     const labels = Array.isArray(data?.labels) ? data?.labels : [];
     return labels
@@ -155,13 +127,6 @@ function linearTriggerMatches(trigger, webhook) {
         const current = data?.state?.name;
         if (current !== trigger.stateTo)
             return false;
-        // RUSH-2539: `stateTo` is a TRANSITION predicate, not a current-state one.
-        // Linear carries the prior value of each changed field in `updatedFrom`, so a
-        // real state change has `updatedFrom.state` (this codebase's shape) or
-        // `updatedFrom.stateId` (Linear's scalar). With neither, this Issue/update
-        // touched something else while the issue merely still sits in `stateTo` —
-        // matching there re-fires on every later edit (RUSH-1459 got 11 duplicate
-        // plan comments).
         const updatedTo = webhook.payload.updatedFrom;
         if (!updatedTo || (updatedTo.state === undefined && updatedTo.stateId === undefined))
             return false;
@@ -174,7 +139,6 @@ function linearTriggerMatches(trigger, webhook) {
     }
     return true;
 }
-/** True when a single job's trigger matches the given webhook. Pure. */
 export function jobMatchesWebhook(job, webhook) {
     const trigger = job.trigger;
     if (!trigger)
@@ -185,11 +149,6 @@ export function jobMatchesWebhook(job, webhook) {
         return linearTriggerMatches(trigger, webhook);
     return false;
 }
-/**
- * Pure matcher: given a set of jobs and an incoming webhook, return the jobs
- * whose `trigger` matches. Jobs without a trigger (schedule-only routines) are
- * never selected — proving time-based jobs are unaffected by webhook delivery.
- */
 export function matchJobsToWebhook(jobs, webhook) {
     return jobs.filter((job) => job.enabled !== false && jobRunsOnThisDevice(job) && jobMatchesWebhook(job, webhook));
 }
@@ -203,10 +162,6 @@ class WebhookDispatchError extends Error {
         this.name = 'WebhookDispatchError';
     }
 }
-/**
- * Match an incoming webhook against the persisted routines and fire each match
- * through the cron dispatch path. Returns one entry per fired job.
- */
 export async function fireWebhookJobs(webhook, options = {}) {
     const jobs = options.jobs ?? listJobs();
     const dispatch = options.dispatch ?? executeJobDetached;
@@ -264,15 +219,6 @@ function verifyLinearTimestamp(payload, now = Date.now(), toleranceMs = 60_000)
     const ts = payload.webhookTimestamp;
     return typeof ts === 'number' && Math.abs(now - ts) <= toleranceMs;
 }
-/**
- * Verify a Slack request signature (the `v0` scheme). Slack signs the base
- * string `v0:${timestamp}:${rawBody}` with the app's signing secret and sends
- * the hex digest as `X-Slack-Signature: v0=<hex>`, alongside the unix
- * `X-Slack-Request-Timestamp`. The timestamp is BOTH part of the signed base
- * string AND checked for freshness here — a request older than `toleranceSec`
- * (default 5 min) is rejected, so a captured, correctly-signed body cannot be
- * replayed later. Fails closed on any missing/malformed header.
- */
 export function verifySlackSignature(headers, rawBody, secret, now = Date.now(), toleranceSec = 300) {
     const ts = header(headers, 'x-slack-request-timestamp');
     if (!ts || !/^\d+$/.test(ts))
@@ -281,22 +227,13 @@ export function verifySlackSignature(headers, rawBody, secret, now = Date.now(),
         return false;
     const received = header(headers, 'x-slack-signature');
     const signature = received?.startsWith('v0=') ? received.slice('v0='.length) : undefined;
-    // Concatenate the base-string prefix with the raw body bytes so a non-ASCII
-    // payload hashes identically to Slack's own `v0:${ts}:${body}` string.
     const base = Buffer.concat([Buffer.from(`v0:${ts}:`, 'utf-8'), rawBody]);
     const expected = crypto.createHmac('sha256', secret).update(base).digest('hex');
     return timingSafeHexEqual(signature, expected);
 }
-/**
- * Parse a Slack delivery body into a normalized {@link SlackPayload}. Slack
- * sends slash commands as `application/x-www-form-urlencoded` and Events API
- * deliveries (including the `url_verification` handshake) as
- * `application/json` — this is the one place that content-type branch lives.
- */
 export function parseSlackBody(contentType, rawBody) {
     if ((contentType ?? '').includes('application/x-www-form-urlencoded')) {
         const form = new URLSearchParams(rawBody.toString('utf-8'));
-        // A slash command carries no thread; its reply posts to the channel.
         return {
             type: 'slash_command',
             command: form.get('command') ?? undefined,
@@ -328,7 +265,6 @@ export function parseSlackBody(contentType, rawBody) {
         team: typeof json.team_id === 'string' ? json.team_id : undefined,
     };
 }
-/** The `event` name a Slack delivery fires under: the slash command, or the event subtype. */
 export function slackEventName(payload) {
     if (payload.type === 'slash_command')
         return payload.command ?? 'slash_command';
@@ -369,20 +305,8 @@ function createMemoryDeliveryStore(maxEntries = 1000) {
         },
     };
 }
-/**
- * A durable, disk-backed delivery store. Unlike `createMemoryDeliveryStore`,
- * seen delivery ids survive a process restart and are bounded by AGE, not by a
- * fixed entry count — so a captured valid delivery cannot re-fire after a
- * restart or after count-based LRU eviction would have dropped it.
- *
- * `retentionMs` doubles as the replay-acceptance window: a delivery whose id is
- * still on record (younger than the window) is rejected as a duplicate; entries
- * older than the window are pruned (keeping the file bounded) since a webhook
- * source will not legitimately retry a delivery that old.
- */
 export function createFileDeliveryStore(filePath, retentionMs = 14 * 24 * 60 * 60 * 1000) {
     const seen = new Map();
-    // Load persisted state (best-effort: a corrupt/missing file starts empty).
     try {
         const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
         const loadedAt = Date.now();
@@ -397,7 +321,6 @@ export function createFileDeliveryStore(filePath, retentionMs = 14 * 24 * 60 * 6
         }
     }
     catch {
-        // no prior file / unreadable — start empty
     }
     const persist = () => {
         const snapshot = {};
@@ -411,7 +334,6 @@ export function createFileDeliveryStore(filePath, retentionMs = 14 * 24 * 60 * 6
             fs.renameSync(tmp, filePath);
         }
         catch {
-            // best-effort durability; an unwritable dir must not crash ingress
         }
     };
     const prune = (now) => {
@@ -490,14 +412,6 @@ async function readRawBody(req, maxBytes) {
     }
     return Buffer.concat(chunks);
 }
-/**
- * Resolve once a receiver is actually accepting connections, REJECT if the bind
- * failed. `server.listen()` reports a bind failure (EADDRINUSE, EACCES) as an
- * asynchronous `'error'` event, never a throw — so a `try/catch` around
- * `startWebhookServer` cannot see it, and without this the event reaches Node's
- * default handler and takes the whole process down. Every caller that hosts a
- * receiver MUST await this rather than assuming the return means "bound".
- */
 export function waitForListening(server) {
     if (server.listening)
         return Promise.resolve();
@@ -512,57 +426,17 @@ export function waitForListening(server) {
         server.once('error', onError);
     });
 }
-/**
- * Start a localhost-bound receiver. It accepts only:
- *   POST /hooks/github  with X-Hub-Signature-256
- *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
- *   POST /hooks/slack   with X-Slack-Signature + fresh X-Slack-Request-Timestamp
- *
- * **The ack is asynchronous (RUSH-2548).** Once a delivery has passed signature
- * verification, freshness, dedup, and rate limiting, the receiver writes
- * `202 {ok:true, accepted:true}` IMMEDIATELY and dispatches the matched routines
- * and handlers afterwards. Dispatch starts an agent run and takes 15-20s, which
- * exceeds Linear's delivery timeout — holding the socket open across it made
- * every real delivery log a timeout + retry on Linear's side. Nothing about the
- * dedup ledger changes: the `<source>:<delivery-id>` key is still what makes a
- * retry a no-op, per-job `markJob` still lets a retry finish only the matches
- * that failed, and the delivery is marked complete only after it settles.
- *
- * A retry that lands WHILE the first is still settling is answered as a
- * duplicate from an in-flight set, since `deliveryStore.seen` only reports
- * completed deliveries and would otherwise let a mid-flight retry double-fire.
- *
- * `onMatch` fires as soon as matching is known, before any dispatch; `onDelivery`
- * fires only once every matched routine/handler has settled — see their docs on
- * `WebhookServerOptions`. A caller that wants a prompt "this fired" log uses
- * `onMatch`, not `onDelivery` (RUSH-2722).
- *
- * Returns the underlying server so callers can `close()` it.
- */
 export function startWebhookServer(options) {
     const deliveryStore = options.deliveryStore ?? createMemoryDeliveryStore();
-    /** Delivery ids acked but not yet settled — dedup across the async window. */
     const inFlight = new Set();
     const rateLimiter = options.rateLimiter ?? createMemoryRateLimiter(options.rateLimitPerMinute ?? 60, 60_000);
     const ipRateLimiter = options.ipRateLimiter ?? createMemoryRateLimiter(options.ipRateLimitPerMinute ?? 120, 60_000);
     const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
-    /**
-     * Dispatch an already-acked delivery: matched routines first, then matched
-     * handlers, then mark the delivery complete. A failure leaves the delivery
-     * UNMARKED (its per-job `markJob` entries survive), so a later retry of the
-     * same delivery id re-runs only what did not complete — the same partial-retry
-     * ledger the synchronous receiver had, minus the 4xx that used to request it.
-     */
     async function settleDelivery(webhook, id) {
         const { source, event: webhookEvent } = webhook;
         try {
             const context = buildWebhookContext(webhook);
             const fireOptions = options.fire ?? {};
-            // Match FIRST, before any dispatch — matching is a pure in-memory lookup,
-            // so this is the earliest point the receiver knows what fired, and the
-            // right time to log it (RUSH-2722). Dispatching a `run.command` handler
-            // can then block on the shelled-out process for minutes; that must never
-            // hold the "fired" log back with it.
             const matchedJobs = matchJobsToWebhook(fireOptions.jobs ?? listJobs(), webhook);
             const matchedHandlers = listHandlers().filter((handler) => handlerMatchesWebhook(handler, webhook));
             options.onMatch?.(webhook, matchedJobs.map((job) => job.name), matchedHandlers.map((handler) => handler.name));
@@ -624,11 +498,6 @@ export function startWebhookServer(options) {
                 res.end(JSON.stringify({ ok: false, error: `missing ${source} webhook secret` }));
                 return;
             }
-            // Per-IP throttle + declared-size cap BEFORE the (expensive) body read +
-            // HMAC. A bad-signature flood of 1 MiB POSTs must be rejected without
-            // forcing a full body read and an HMAC per request — the signed-delivery
-            // rate limit further down runs only after a signature passes, so it can't
-            // shed this load on its own.
             const ip = req.socket.remoteAddress ?? 'unknown';
             if (!ipRateLimiter.take(ip)) {
                 emit('webhook.rejected', { source, reason: 'ip rate limit exceeded' });
@@ -656,19 +525,14 @@ export function startWebhookServer(options) {
                     res.end(JSON.stringify({ ok: false, error: 'invalid signature' }));
                     return;
                 }
-                // Slack diverges from the GitHub/Linear JSON path: two content-types
-                // (slash = form, events = JSON), a one-time url_verification handshake,
-                // a body-carried event id, and a 200 ack Slack shows to the caller.
                 if (source === 'slack') {
                     const slack = parseSlackBody(header(req.headers, 'content-type'), rawBody);
-                    // One-time Events API URL handshake: echo the challenge, dispatch nothing.
                     if (slack.type === 'url_verification') {
                         res.writeHead(200, { 'content-type': 'application/json' });
                         res.end(JSON.stringify({ challenge: slack.challenge ?? '' }));
                         return;
                     }
                     const slackEvent = slackEventName(slack);
-                    // Slash commands carry no event_id, so fall back to a body hash for dedup.
                     const slackId = `slack:${slack.event_id ?? crypto.createHash('sha256').update(rawBody).digest('hex')}`;
                     emit('webhook.received', { source, event: slackEvent, deliveryId: slackId });
                     if (deliveryStore.seen(slackId) || inFlight.has(slackId)) {
@@ -684,9 +548,6 @@ export function startWebhookServer(options) {
                     }
                     const slackWebhook = { source, event: slackEvent, payload: slack };
                     emit('webhook.authorized', { source, event: slackEvent, deliveryId: slackId });
-                    // ACK FIRST (RUSH-2548): a 200 inside Slack's 3s window. A slash
-                    // command renders the ack text to the caller; an event delivery
-                    // ignores the body. Dispatch outlives the ack, same as GitHub/Linear.
                     inFlight.add(slackId);
                     res.writeHead(200, { 'content-type': 'application/json' });
                     res.end(slack.type === 'slash_command'
@@ -723,8 +584,6 @@ export function startWebhookServer(options) {
                     payload,
                 };
                 emit('webhook.authorized', { source, event: webhookEvent, deliveryId: id });
-                // ACK FIRST (RUSH-2548). Everything that could reject this delivery has
-                // run; what remains starts agent runs and outlives any sender timeout.
                 inFlight.add(id);
                 res.writeHead(202, { 'content-type': 'application/json' });
                 res.end(JSON.stringify({ ok: true, accepted: true, deliveryId: id }));
@@ -736,8 +595,6 @@ export function startWebhookServer(options) {
             }
         })();
     });
-    // Connection cap: bound how many concurrent TCP connections the receiver
-    // will hold open, so a flood cannot exhaust file descriptors / memory.
     server.maxConnections = options.maxConnections ?? 256;
     server.listen(options.port ?? 0, options.host ?? '127.0.0.1');
     return server;