@phnx-labs/agents-cli 1.20.62 → 1.20.63

package/dist/lib/triggers/webhook.d.ts

@@ -1,29 +1,34 @@
 /**
- * GitHub webhook trigger receiver for routines.
+ * 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
- * an incoming GitHub webhook into the set of routines it should fire, and
- * dispatches those routines through the exact same path a cron fire uses
+ * 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 (`matchJobsToWebhook`) is a pure, side-effect-free
- * function so it can be unit-tested without a running daemon or http server.
- * The optional http listener (`startWebhookServer`) is a thin adapter over it.
+ * 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 http from 'http';
+import type { IncomingHttpHeaders } from 'http';
 import type { JobConfig, RunMeta } from '../routines.js';
-/**
- * A parsed GitHub webhook: the event name (from the `X-GitHub-Event` HTTP
- * header) plus the decoded JSON body. Kept deliberately loose (`payload` is an
- * arbitrary object) because callers may hand us any of GitHub's event shapes.
- */
-export interface GithubWebhook {
-    /** The GitHub event name, e.g. `pull_request`, `push`, `issue_comment`. */
+export type WebhookSource = 'github' | 'linear';
+export interface IncomingWebhook {
+    /** Delivery source, derived from `/hooks/<source>` or one-shot command flags. */
+    source: WebhookSource;
+    /** Source event name: GitHub header event or Linear payload `type`. */
     event: string;
-    /** The decoded JSON request body. */
+    /** Decoded JSON request body. */
     payload: Record<string, unknown>;
 }
+export type GithubWebhook = IncomingWebhook & {
+    source: 'github';
+};
+export type LinearWebhook = IncomingWebhook & {
+    source: 'linear';
+};
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export declare function webhookRepo(payload: Record<string, unknown>): string | null;
 /**
@@ -37,14 +42,13 @@ export declare function webhookRepo(payload: Record<string, unknown>): string |
  */
 export declare function webhookBranches(event: string, payload: Record<string, unknown>): string[];
 /** True when a single job's trigger matches the given webhook. Pure. */
-export declare function jobMatchesWebhook(job: JobConfig, webhook: GithubWebhook): boolean;
+export declare function jobMatchesWebhook(job: JobConfig, webhook: IncomingWebhook): boolean;
 /**
  * Pure matcher: given a set of jobs and an incoming webhook, return the jobs
- * whose `trigger` matches (event + optional repo + optional branch). Jobs
- * without a trigger (schedule-only routines) are never selected — proving
- * time-based jobs are unaffected by webhook delivery.
+ * whose `trigger` matches. Jobs without a trigger (schedule-only routines) are
+ * never selected — proving time-based jobs are unaffected by webhook delivery.
  */
-export declare function matchJobsToWebhook(jobs: JobConfig[], webhook: GithubWebhook): JobConfig[];
+export declare function matchJobsToWebhook(jobs: JobConfig[], webhook: IncomingWebhook): JobConfig[];
 /** Options for firing webhook-matched jobs (dispatch is injectable for tests). */
 export interface FireWebhookOptions {
     /** Job source. Defaults to all persisted routines (`listJobs()`). */
@@ -55,31 +59,70 @@ export interface FireWebhookOptions {
      * matching without spawning real agent processes.
      */
     dispatch?: (config: JobConfig) => Promise<RunMeta>;
+    /** Matched job names that already completed for this delivery. */
+    skipJobNames?: ReadonlySet<string>;
+    /** Called immediately after a single matched job dispatch succeeds. */
+    onJobFired?: (job: JobConfig, fired: FiredJob) => void;
 }
 /** Result of firing one matched job. */
 export interface FiredJob {
     jobName: string;
     runId: string;
 }
+export declare class WebhookDispatchError extends Error {
+    readonly fired: FiredJob[];
+    readonly failures: {
+        jobName: string;
+        error: Error;
+    }[];
+    constructor(message: string, fired: FiredJob[], failures: {
+        jobName: string;
+        error: Error;
+    }[]);
+}
 /**
  * Match an incoming webhook against the persisted routines and fire each match
  * through the cron dispatch path. Returns one entry per fired job.
  */
-export declare function fireWebhookJobs(webhook: GithubWebhook, options?: FireWebhookOptions): Promise<FiredJob[]>;
+export declare function fireWebhookJobs(webhook: IncomingWebhook, options?: FireWebhookOptions): Promise<FiredJob[]>;
+export declare function verifyGithubSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
+export declare function verifyLinearSignature(headers: IncomingHttpHeaders, rawBody: Buffer, secret: string): boolean;
+export declare function verifyLinearTimestamp(payload: Record<string, unknown>, now?: number, toleranceMs?: number): boolean;
+export interface WebhookSecrets {
+    github?: string;
+    linear?: string;
+}
+export interface DeliveryStore {
+    seen(id: string): boolean;
+    mark(id: string): void;
+    completedJobs(id: string): ReadonlySet<string>;
+    markJob(id: string, jobName: string): void;
+}
+export declare function createMemoryDeliveryStore(maxEntries?: number): DeliveryStore;
+export interface RateLimiter {
+    take(key: string): boolean;
+}
+export declare function createMemoryRateLimiter(limit: number, windowMs: number): RateLimiter;
 /** Options for the local webhook http listener. */
 export interface WebhookServerOptions {
     port?: number;
     host?: string;
+    /** HMAC signing secrets keyed by source. */
+    secrets: WebhookSecrets;
     /** Override the fire options (mainly for tests). */
     fire?: FireWebhookOptions;
     /** Called after each delivery is handled (mainly for tests/observability). */
-    onDelivery?: (event: string, fired: FiredJob[]) => void;
+    onDelivery?: (webhook: IncomingWebhook, fired: FiredJob[]) => void;
+    deliveryStore?: DeliveryStore;
+    rateLimiter?: RateLimiter;
+    rateLimitPerMinute?: number;
+    maxBodyBytes?: number;
 }
 /**
- * Start a minimal local webhook receiver. POSTs are read as JSON, the GitHub
- * event is taken from the `X-GitHub-Event` header, and matching routines are
- * fired via {@link fireWebhookJobs}. Returns the underlying server so callers
- * can `close()` it. The heavy lifting is the pure matcher above; this is only
- * the transport.
+ * Start a localhost-bound receiver. It accepts only:
+ *   POST /hooks/github  with X-Hub-Signature-256
+ *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
+ *
+ * Returns the underlying server so callers can `close()` it.
  */
-export declare function startWebhookServer(options?: WebhookServerOptions): http.Server;
+export declare function startWebhookServer(options: WebhookServerOptions): http.Server;

package/dist/lib/triggers/webhook.js

@@ -1,18 +1,19 @@
 /**
- * GitHub webhook trigger receiver for routines.
+ * 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
- * an incoming GitHub webhook into the set of routines it should fire, and
- * dispatches those routines through the exact same path a cron fire uses
+ * 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 (`matchJobsToWebhook`) is a pure, side-effect-free
- * function so it can be unit-tested without a running daemon or http server.
- * The optional http listener (`startWebhookServer`) is a thin adapter over it.
+ * 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 http from 'http';
-import { listJobs, jobRunsOnThisDevice } from '../routines.js';
+import { jobRunsOnThisDevice, listJobs } from '../routines.js';
 import { executeJobDetached } from '../runner.js';
 /** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
 export function webhookRepo(payload) {
@@ -59,10 +60,30 @@ export function webhookBranches(event, payload) {
     }
     return [...branches];
 }
-/** True when a single job's trigger matches the given webhook. Pure. */
-export function jobMatchesWebhook(job, webhook) {
-    const trigger = job.trigger;
-    if (!trigger || trigger.type !== 'github_event')
+function linearAction(payload) {
+    return typeof payload.action === 'string' ? payload.action : null;
+}
+function linearTeamKey(payload) {
+    const data = payload.data;
+    const identifier = data?.identifier;
+    if (typeof identifier === 'string') {
+        const match = /^([A-Z][A-Z0-9]*)-\d+$/.exec(identifier);
+        if (match)
+            return match[1];
+    }
+    const team = data?.team;
+    return typeof team?.key === 'string' ? team.key : null;
+}
+function linearLabels(payload) {
+    const data = payload.data;
+    const labels = data?.labels;
+    const nodes = Array.isArray(labels?.nodes) ? labels.nodes : [];
+    return nodes
+        .map((n) => n.name)
+        .filter((n) => typeof n === 'string' && n.length > 0);
+}
+function githubTriggerMatches(trigger, webhook) {
+    if (webhook.source !== 'github')
         return false;
     if (trigger.event !== webhook.event)
         return false;
@@ -78,15 +99,51 @@ export function jobMatchesWebhook(job, webhook) {
     }
     return true;
 }
+function linearTriggerMatches(trigger, webhook) {
+    if (webhook.source !== 'linear')
+        return false;
+    if (trigger.event !== webhook.event)
+        return false;
+    if (trigger.action && linearAction(webhook.payload) !== trigger.action)
+        return false;
+    if (trigger.teamKey && linearTeamKey(webhook.payload) !== trigger.teamKey)
+        return false;
+    if (trigger.label) {
+        const expected = trigger.label.toLowerCase();
+        if (!linearLabels(webhook.payload).some((name) => name.toLowerCase() === expected))
+            return false;
+    }
+    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)
+        return false;
+    if (trigger.type === 'github_event')
+        return githubTriggerMatches(trigger, webhook);
+    if (trigger.type === 'linear_event')
+        return linearTriggerMatches(trigger, webhook);
+    return false;
+}
 /**
  * Pure matcher: given a set of jobs and an incoming webhook, return the jobs
- * whose `trigger` matches (event + optional repo + optional branch). Jobs
- * without a trigger (schedule-only routines) are never selected — proving
- * time-based jobs are unaffected by webhook delivery.
+ * 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));
 }
+export class WebhookDispatchError extends Error {
+    fired;
+    failures;
+    constructor(message, fired, failures) {
+        super(message);
+        this.fired = fired;
+        this.failures = failures;
+        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.
@@ -94,47 +151,211 @@ export function matchJobsToWebhook(jobs, webhook) {
 export async function fireWebhookJobs(webhook, options = {}) {
     const jobs = options.jobs ?? listJobs();
     const dispatch = options.dispatch ?? executeJobDetached;
+    const skipJobNames = options.skipJobNames ?? new Set();
     const matched = matchJobsToWebhook(jobs, webhook);
     const fired = [];
+    const failures = [];
     for (const job of matched) {
-        const meta = await dispatch(job);
-        fired.push({ jobName: job.name, runId: meta.runId });
+        if (skipJobNames.has(job.name))
+            continue;
+        try {
+            const meta = await dispatch(job);
+            const firedJob = { jobName: job.name, runId: meta.runId };
+            fired.push(firedJob);
+            options.onJobFired?.(job, firedJob);
+        }
+        catch (err) {
+            failures.push({ jobName: job.name, error: err });
+        }
+    }
+    if (failures.length > 0) {
+        throw new WebhookDispatchError(`failed to dispatch ${failures.length} webhook routine(s): ${failures.map((f) => f.jobName).join(', ')}`, fired, failures);
     }
     return fired;
 }
+function header(headers, name) {
+    const value = headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+function timingSafeHexEqual(received, expected) {
+    if (!received || !/^[a-f0-9]+$/i.test(received))
+        return false;
+    const a = Buffer.from(received, 'hex');
+    const b = Buffer.from(expected, 'hex');
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+function hmacHex(secret, rawBody) {
+    return crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+}
+export function verifyGithubSignature(headers, rawBody, secret) {
+    const received = header(headers, 'x-hub-signature-256');
+    const signature = received?.startsWith('sha256=') ? received.slice('sha256='.length) : undefined;
+    return timingSafeHexEqual(signature, hmacHex(secret, rawBody));
+}
+export function verifyLinearSignature(headers, rawBody, secret) {
+    return timingSafeHexEqual(header(headers, 'linear-signature'), hmacHex(secret, rawBody));
+}
+export function verifyLinearTimestamp(payload, now = Date.now(), toleranceMs = 60_000) {
+    const ts = payload.webhookTimestamp;
+    return typeof ts === 'number' && Math.abs(now - ts) <= toleranceMs;
+}
+export function createMemoryDeliveryStore(maxEntries = 1000) {
+    const seen = new Map();
+    const touch = (id) => {
+        let current = seen.get(id);
+        if (!current) {
+            current = { complete: false, jobs: new Set(), updatedAt: Date.now() };
+            seen.set(id, current);
+        }
+        current.updatedAt = Date.now();
+        while (seen.size > maxEntries) {
+            let oldestId = null;
+            let oldestAt = Number.POSITIVE_INFINITY;
+            for (const [key, value] of seen) {
+                if (value.updatedAt < oldestAt) {
+                    oldestAt = value.updatedAt;
+                    oldestId = key;
+                }
+            }
+            if (!oldestId)
+                break;
+            seen.delete(oldestId);
+        }
+        return current;
+    };
+    return {
+        seen: (id) => seen.get(id)?.complete === true,
+        mark: (id) => {
+            touch(id).complete = true;
+        },
+        completedJobs: (id) => new Set(seen.get(id)?.jobs ?? []),
+        markJob: (id, jobName) => {
+            touch(id).jobs.add(jobName);
+        },
+    };
+}
+export function createMemoryRateLimiter(limit, windowMs) {
+    const buckets = new Map();
+    return {
+        take: (key) => {
+            const now = Date.now();
+            const current = buckets.get(key);
+            if (!current || now >= current.resetAt) {
+                buckets.set(key, { resetAt: now + windowMs, count: 1 });
+                return true;
+            }
+            if (current.count >= limit)
+                return false;
+            current.count += 1;
+            return true;
+        },
+    };
+}
+function deliveryId(source, headers, rawBody) {
+    const named = source === 'github'
+        ? header(headers, 'x-github-delivery')
+        : header(headers, 'linear-delivery');
+    return `${source}:${named ?? crypto.createHash('sha256').update(rawBody).digest('hex')}`;
+}
+function sourceFromPath(pathname) {
+    const match = /^\/hooks\/(github|linear)\/?$/.exec(pathname ?? '');
+    return match ? match[1] : null;
+}
+async function readRawBody(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes)
+            throw new Error(`payload exceeds ${maxBytes} bytes`);
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
 /**
- * Start a minimal local webhook receiver. POSTs are read as JSON, the GitHub
- * event is taken from the `X-GitHub-Event` header, and matching routines are
- * fired via {@link fireWebhookJobs}. Returns the underlying server so callers
- * can `close()` it. The heavy lifting is the pure matcher above; this is only
- * the transport.
+ * Start a localhost-bound receiver. It accepts only:
+ *   POST /hooks/github  with X-Hub-Signature-256
+ *   POST /hooks/linear  with Linear-Signature + fresh webhookTimestamp
+ *
+ * Returns the underlying server so callers can `close()` it.
  */
-export function startWebhookServer(options = {}) {
+export function startWebhookServer(options) {
+    const deliveryStore = options.deliveryStore ?? createMemoryDeliveryStore();
+    const rateLimiter = options.rateLimiter ?? createMemoryRateLimiter(options.rateLimitPerMinute ?? 60, 60_000);
+    const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
     const server = http.createServer((req, res) => {
-        if (req.method !== 'POST') {
-            res.writeHead(405, { 'content-type': 'text/plain' });
-            res.end('method not allowed');
-            return;
-        }
-        const event = req.headers['x-github-event'] ?? '';
-        const chunks = [];
-        req.on('data', (c) => chunks.push(c));
-        req.on('end', () => {
-            void (async () => {
-                try {
-                    const raw = Buffer.concat(chunks).toString('utf-8');
-                    const payload = raw ? JSON.parse(raw) : {};
-                    const fired = await fireWebhookJobs({ event, payload }, options.fire);
-                    options.onDelivery?.(event, fired);
+        void (async () => {
+            if (req.method !== 'POST') {
+                res.writeHead(405, { 'content-type': 'text/plain' });
+                res.end('method not allowed');
+                return;
+            }
+            const source = sourceFromPath(req.url?.split('?')[0]);
+            if (!source) {
+                res.writeHead(404, { 'content-type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            const secret = options.secrets[source];
+            if (!secret) {
+                res.writeHead(503, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: `missing ${source} webhook secret` }));
+                return;
+            }
+            try {
+                const rawBody = await readRawBody(req, maxBodyBytes);
+                const valid = source === 'github'
+                    ? verifyGithubSignature(req.headers, rawBody, secret)
+                    : verifyLinearSignature(req.headers, rawBody, secret);
+                if (!valid) {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'invalid signature' }));
+                    return;
+                }
+                const id = deliveryId(source, req.headers, rawBody);
+                if (deliveryStore.seen(id)) {
                     res.writeHead(200, { 'content-type': 'application/json' });
-                    res.end(JSON.stringify({ ok: true, fired: fired.map((f) => f.jobName) }));
+                    res.end(JSON.stringify({ ok: true, duplicate: true, fired: [] }));
+                    return;
+                }
+                const payload = rawBody.length > 0 ? JSON.parse(rawBody.toString('utf-8')) : {};
+                if (source === 'linear' && !verifyLinearTimestamp(payload)) {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'stale linear webhook timestamp' }));
+                    return;
                 }
-                catch (err) {
-                    res.writeHead(400, { 'content-type': 'application/json' });
-                    res.end(JSON.stringify({ ok: false, error: err.message }));
+                if (!rateLimiter.take(source)) {
+                    res.writeHead(429, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'rate limit exceeded' }));
+                    return;
                 }
-            })();
-        });
+                const webhook = {
+                    source,
+                    event: source === 'github' ? (header(req.headers, 'x-github-event') ?? '') : String(payload.type ?? ''),
+                    payload,
+                };
+                const fireOptions = options.fire ?? {};
+                const fired = await fireWebhookJobs(webhook, {
+                    ...fireOptions,
+                    skipJobNames: deliveryStore.completedJobs(id),
+                    onJobFired: (job, firedJob) => {
+                        deliveryStore.markJob(id, job.name);
+                        fireOptions.onJobFired?.(job, firedJob);
+                    },
+                });
+                deliveryStore.mark(id);
+                options.onDelivery?.(webhook, fired);
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, fired: fired.map((f) => f.jobName), runs: fired }));
+            }
+            catch (err) {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: err.message }));
+            }
+        })();
     });
     server.listen(options.port ?? 0, options.host ?? '127.0.0.1');
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.62",
+  "version": "1.20.63",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",