@tagma/trigger-webhook 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tagma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @tagma/trigger-webhook
+
+HTTP webhook trigger plugin for [@tagma/sdk](https://www.npmjs.com/package/@tagma/sdk).
+
+Pauses a task until a POST request arrives on a configured local HTTP listener. Optional HMAC-SHA256 signature validation protects against unauthenticated callers.
+
+## Install
+
+```bash
+bun add @tagma/trigger-webhook
+```
+
+## Usage
+
+```yaml
+pipeline:
+  name: deploy-on-demand
+  plugins:
+    - "@tagma/trigger-webhook"
+  tracks:
+    - id: deploy
+      name: Deploy
+      driver: claude-code
+      tasks:
+        - id: wait-signal
+          name: Wait for deploy signal
+          trigger:
+            type: webhook
+            port: 8787
+            path: /hooks/deploy
+            secret_env: TAGMA_WEBHOOK_SECRET
+            timeout: 30m
+          prompt: "Run the deploy playbook for the staging environment"
+```
+
+Then fire the webhook from anywhere (CI, Slack, cron, another pipeline):
+
+```bash
+BODY='{"env":"staging","sha":"abc123"}'
+SIG="sha256=$(printf %s "$BODY" | openssl dgst -sha256 -hmac "$TAGMA_WEBHOOK_SECRET" | awk '{print $2}')"
+curl -X POST http://localhost:8787/hooks/deploy \
+  -H "content-type: application/json" \
+  -H "x-tagma-signature: $SIG" \
+  -d "$BODY"
+```
+
+Or load it programmatically:
+
+```ts
+import { bootstrapBuiltins, loadPlugins } from '@tagma/sdk';
+
+bootstrapBuiltins();
+await loadPlugins(['@tagma/trigger-webhook']);
+```
+
+## Config
+
+| Field        | Type     | Default     | Notes                                                                                       |
+|--------------|----------|-------------|---------------------------------------------------------------------------------------------|
+| `port`       | number   | *(required)*| TCP port to listen on (1-65535)                                                             |
+| `path`       | string   | `/webhook`  | URL path to match; must start with `/`                                                      |
+| `secret_env` | string   | *(none)*    | Env var holding the HMAC-SHA256 secret. When set, requests must include `x-tagma-signature` |
+| `timeout`    | duration | *(forever)* | Max wait time; omit for unbounded wait                                                      |
+
+## Behavior
+
+- A single `Bun.serve` listener is created per unique `(port, path)` pair and shared across all tasks that watch it. Multiple tasks on the same endpoint form a FIFO waiter queue — the next POST wakes one waiter.
+- Signature header format: `x-tagma-signature: sha256=<hex>`, HMAC-SHA256 of the raw request body using the secret. Verification is constant-time.
+- JSON bodies (`content-type: application/json`) are parsed and handed to the task as the trigger payload; other bodies are passed through as raw strings.
+- A POST arriving while no task is waiting is rejected with `409 no waiting task` so the caller can retry once a pipeline is up.
+- The listener outlives the task — it's a per-process singleton, not cleaned up between pipeline runs. Restart the host to free the port.
+
+## Security
+
+Always set `secret_env` in production. Without it, anyone who can reach the port can fire the trigger. Bind the host to `127.0.0.1` at the OS level if you only need local callers.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { TriggerPlugin } from '@tagma/types';
+declare const WebhookTrigger: TriggerPlugin;
+export declare const pluginCategory = "triggers";
+export declare const pluginType = "webhook";
+export default WebhookTrigger;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,cAAc,CAAC;AAqHlE,QAAA,MAAM,cAAc,EAAE,aAsGrB,CAAC;AAGF,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,eAAO,MAAM,UAAU,YAAY,CAAC;AACpC,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,214 @@
+// ═══ Webhook Trigger Plugin ═══
+//
+// Spins up a Bun.serve HTTP listener and resolves the trigger when a POST
+// arrives on the configured path. Optional HMAC-SHA256 validation via the
+// `x-tagma-signature: sha256=<hex>` header protects against unauthenticated
+// callers when the secret env var is set.
+//
+// Multiple tasks sharing the same `(port, path)` pair hit the same listener
+// instance and are enqueued as waiters — the next inbound request wakes one
+// waiter (FIFO). This keeps the plugin lightweight even when a pipeline has
+// many webhook-triggered tasks.
+//
+// Usage in pipeline.yaml:
+//   plugins: ["@tagma/trigger-webhook"]
+//   tracks:
+//     - tasks:
+//         - id: deploy
+//           trigger:
+//             type: webhook
+//             port: 8787
+//             path: /hooks/deploy
+//             secret_env: TAGMA_WEBHOOK_SECRET
+//             timeout: 10m
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// Module-level so concurrent tasks on the same (port, path) share one
+// listener. Bun.serve refuses to bind a port twice, so this sharing is
+// required — not just an optimization.
+const servers = new Map();
+function serverKey(port, path) {
+    return `${port}::${path}`;
+}
+function parseDurationSafe(raw, fallback) {
+    if (raw == null)
+        return fallback;
+    const str = String(raw).trim();
+    const m = str.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+    if (!m)
+        return fallback;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case 'ms': return n;
+        case 'm': return n * 60_000;
+        case 'h': return n * 3_600_000;
+        case 's':
+        default: return n * 1000;
+    }
+}
+function verifySignature(rawBody, header, secret) {
+    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    const a = Buffer.from(header);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+function ensureServer(port, path, secretEnv) {
+    const key = serverKey(port, path);
+    const existing = servers.get(key);
+    if (existing)
+        return existing;
+    const state = {
+        port,
+        path,
+        secretEnv,
+        waiters: [],
+    };
+    Bun.serve({
+        port,
+        async fetch(req) {
+            const url = new URL(req.url);
+            if (url.pathname !== path) {
+                return new Response('not found', { status: 404 });
+            }
+            if (req.method !== 'POST') {
+                return new Response('method not allowed', { status: 405 });
+            }
+            const rawBody = await req.text();
+            // HMAC gate — bypassed when no secret env is configured, which is
+            // acceptable for loopback dev but should always be set in production.
+            const secret = state.secretEnv ? process.env[state.secretEnv] : undefined;
+            if (state.secretEnv) {
+                if (!secret) {
+                    return new Response(`env var ${state.secretEnv} not set`, { status: 500 });
+                }
+                const sigHeader = req.headers.get('x-tagma-signature') ?? '';
+                if (!verifySignature(rawBody, sigHeader, secret)) {
+                    return new Response('invalid signature', { status: 401 });
+                }
+            }
+            // Decode JSON if possible so downstream tasks get structured data.
+            // Falls back to the raw string body otherwise.
+            let payload = rawBody;
+            const contentType = req.headers.get('content-type') ?? '';
+            if (contentType.includes('application/json')) {
+                try {
+                    payload = JSON.parse(rawBody);
+                }
+                catch {
+                    /* keep raw body */
+                }
+            }
+            const waiter = state.waiters.shift();
+            if (waiter) {
+                waiter(payload);
+                return new Response('ok', { status: 202 });
+            }
+            // No task is currently waiting on this endpoint — reject loudly so
+            // callers know the webhook wasn't actually consumed by a pipeline.
+            return new Response('no waiting task', { status: 409 });
+        },
+        error(err) {
+            console.error(`[webhook] server error on :${port}${path}:`, err);
+            return new Response('internal error', { status: 500 });
+        },
+    });
+    servers.set(key, state);
+    return state;
+}
+const WebhookTrigger = {
+    name: 'webhook',
+    schema: {
+        description: 'Wait for an HTTP POST to arrive on a local listener before the task runs.',
+        fields: {
+            port: {
+                type: 'number',
+                required: true,
+                default: 8787,
+                min: 1,
+                max: 65535,
+                description: 'TCP port to listen on.',
+                placeholder: '8787',
+            },
+            path: {
+                type: 'string',
+                required: true,
+                default: '/webhook',
+                description: 'URL path to match (e.g. /hooks/deploy).',
+                placeholder: '/webhook',
+            },
+            secret_env: {
+                type: 'string',
+                description: 'Env var containing the HMAC-SHA256 secret. When set, POSTs must include an x-tagma-signature: sha256=<hex> header computed over the raw body.',
+                placeholder: 'TAGMA_WEBHOOK_SECRET',
+            },
+            timeout: {
+                type: 'duration',
+                description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
+                placeholder: '10m',
+            },
+        },
+    },
+    watch(config, ctx) {
+        const rawPort = config.port;
+        const port = typeof rawPort === 'number' ? rawPort : Number(rawPort);
+        if (!Number.isFinite(port) || port < 1 || port > 65535) {
+            throw new Error(`webhook trigger: "port" must be 1-65535, got ${String(rawPort)}`);
+        }
+        const path = config.path ?? '/webhook';
+        if (!path.startsWith('/')) {
+            throw new Error(`webhook trigger: "path" must start with "/", got ${path}`);
+        }
+        const secretEnv = config.secret_env;
+        const timeoutMs = config.timeout != null
+            ? parseDurationSafe(config.timeout, 0)
+            : 0;
+        const state = ensureServer(port, path, secretEnv);
+        return new Promise((resolvePromise, rejectPromise) => {
+            if (ctx.signal.aborted) {
+                rejectPromise(new Error('Pipeline aborted'));
+                return;
+            }
+            let settled = false;
+            let timer = null;
+            const onFire = (payload) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolvePromise(payload);
+            };
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                rejectPromise(new Error('Pipeline aborted'));
+            };
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                ctx.signal.removeEventListener('abort', onAbort);
+                const idx = state.waiters.indexOf(onFire);
+                if (idx !== -1)
+                    state.waiters.splice(idx, 1);
+            };
+            state.waiters.push(onFire);
+            ctx.signal.addEventListener('abort', onAbort, { once: true });
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    rejectPromise(new Error(`webhook trigger timeout: no POST on :${port}${path} within ${String(config.timeout)}`));
+                }, timeoutMs);
+            }
+        });
+    },
+};
+// ═══ Plugin self-description exports ═══
+export const pluginCategory = 'triggers';
+export const pluginType = 'webhook';
+export default WebhookTrigger;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tagma/trigger-webhook",
+  "version": "0.1.1",
+  "description": "HTTP webhook trigger plugin for tagma-sdk pipelines",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GoTagma/tagma-mono.git",
+    "directory": "packages/trigger-webhook"
+  },
+  "bugs": "https://github.com/GoTagma/tagma-mono/issues",
+  "homepage": "https://github.com/GoTagma/tagma-mono/tree/main/packages/trigger-webhook#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "tagma-plugin",
+    "tagma",
+    "trigger",
+    "webhook",
+    "http"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "tagmaPlugin": {
+    "category": "triggers",
+    "type": "webhook"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build"
+  },
+  "peerDependencies": {
+    "@tagma/types": "0.2.1"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.11",
+    "typescript": "^5.8.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,249 @@
+// ═══ Webhook Trigger Plugin ═══
+//
+// Spins up a Bun.serve HTTP listener and resolves the trigger when a POST
+// arrives on the configured path. Optional HMAC-SHA256 validation via the
+// `x-tagma-signature: sha256=<hex>` header protects against unauthenticated
+// callers when the secret env var is set.
+//
+// Multiple tasks sharing the same `(port, path)` pair hit the same listener
+// instance and are enqueued as waiters — the next inbound request wakes one
+// waiter (FIFO). This keeps the plugin lightweight even when a pipeline has
+// many webhook-triggered tasks.
+//
+// Usage in pipeline.yaml:
+//   plugins: ["@tagma/trigger-webhook"]
+//   tracks:
+//     - tasks:
+//         - id: deploy
+//           trigger:
+//             type: webhook
+//             port: 8787
+//             path: /hooks/deploy
+//             secret_env: TAGMA_WEBHOOK_SECRET
+//             timeout: 10m
+
+import type { TriggerPlugin, TriggerContext } from '@tagma/types';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+type Resolver = (payload: unknown) => void;
+
+interface WebhookServerState {
+  readonly port: number;
+  readonly path: string;
+  readonly secretEnv: string | undefined;
+  readonly waiters: Resolver[];
+}
+
+// Module-level so concurrent tasks on the same (port, path) share one
+// listener. Bun.serve refuses to bind a port twice, so this sharing is
+// required — not just an optimization.
+const servers = new Map<string, WebhookServerState>();
+
+function serverKey(port: number, path: string): string {
+  return `${port}::${path}`;
+}
+
+function parseDurationSafe(raw: unknown, fallback: number): number {
+  if (raw == null) return fallback;
+  const str = String(raw).trim();
+  const m = str.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  switch (m[2]) {
+    case 'ms': return n;
+    case 'm':  return n * 60_000;
+    case 'h':  return n * 3_600_000;
+    case 's':
+    default:   return n * 1000;
+  }
+}
+
+function verifySignature(rawBody: string, header: string, secret: string): boolean {
+  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+  const a = Buffer.from(header);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function ensureServer(
+  port: number,
+  path: string,
+  secretEnv: string | undefined,
+): WebhookServerState {
+  const key = serverKey(port, path);
+  const existing = servers.get(key);
+  if (existing) return existing;
+
+  const state: WebhookServerState = {
+    port,
+    path,
+    secretEnv,
+    waiters: [],
+  };
+
+  Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== path) {
+        return new Response('not found', { status: 404 });
+      }
+      if (req.method !== 'POST') {
+        return new Response('method not allowed', { status: 405 });
+      }
+
+      const rawBody = await req.text();
+
+      // HMAC gate — bypassed when no secret env is configured, which is
+      // acceptable for loopback dev but should always be set in production.
+      const secret = state.secretEnv ? process.env[state.secretEnv] : undefined;
+      if (state.secretEnv) {
+        if (!secret) {
+          return new Response(`env var ${state.secretEnv} not set`, { status: 500 });
+        }
+        const sigHeader = req.headers.get('x-tagma-signature') ?? '';
+        if (!verifySignature(rawBody, sigHeader, secret)) {
+          return new Response('invalid signature', { status: 401 });
+        }
+      }
+
+      // Decode JSON if possible so downstream tasks get structured data.
+      // Falls back to the raw string body otherwise.
+      let payload: unknown = rawBody;
+      const contentType = req.headers.get('content-type') ?? '';
+      if (contentType.includes('application/json')) {
+        try {
+          payload = JSON.parse(rawBody);
+        } catch {
+          /* keep raw body */
+        }
+      }
+
+      const waiter = state.waiters.shift();
+      if (waiter) {
+        waiter(payload);
+        return new Response('ok', { status: 202 });
+      }
+      // No task is currently waiting on this endpoint — reject loudly so
+      // callers know the webhook wasn't actually consumed by a pipeline.
+      return new Response('no waiting task', { status: 409 });
+    },
+    error(err) {
+      console.error(`[webhook] server error on :${port}${path}:`, err);
+      return new Response('internal error', { status: 500 });
+    },
+  });
+
+  servers.set(key, state);
+  return state;
+}
+
+const WebhookTrigger: TriggerPlugin = {
+  name: 'webhook',
+  schema: {
+    description:
+      'Wait for an HTTP POST to arrive on a local listener before the task runs.',
+    fields: {
+      port: {
+        type: 'number',
+        required: true,
+        default: 8787,
+        min: 1,
+        max: 65535,
+        description: 'TCP port to listen on.',
+        placeholder: '8787',
+      },
+      path: {
+        type: 'string',
+        required: true,
+        default: '/webhook',
+        description: 'URL path to match (e.g. /hooks/deploy).',
+        placeholder: '/webhook',
+      },
+      secret_env: {
+        type: 'string',
+        description:
+          'Env var containing the HMAC-SHA256 secret. When set, POSTs must include an x-tagma-signature: sha256=<hex> header computed over the raw body.',
+        placeholder: 'TAGMA_WEBHOOK_SECRET',
+      },
+      timeout: {
+        type: 'duration',
+        description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
+        placeholder: '10m',
+      },
+    },
+  },
+
+  watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
+    const rawPort = config.port;
+    const port = typeof rawPort === 'number' ? rawPort : Number(rawPort);
+    if (!Number.isFinite(port) || port < 1 || port > 65535) {
+      throw new Error(`webhook trigger: "port" must be 1-65535, got ${String(rawPort)}`);
+    }
+
+    const path = (config.path as string | undefined) ?? '/webhook';
+    if (!path.startsWith('/')) {
+      throw new Error(`webhook trigger: "path" must start with "/", got ${path}`);
+    }
+
+    const secretEnv = config.secret_env as string | undefined;
+    const timeoutMs = config.timeout != null
+      ? parseDurationSafe(config.timeout, 0)
+      : 0;
+
+    const state = ensureServer(port, path, secretEnv);
+
+    return new Promise<unknown>((resolvePromise, rejectPromise) => {
+      if (ctx.signal.aborted) {
+        rejectPromise(new Error('Pipeline aborted'));
+        return;
+      }
+
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+
+      const onFire: Resolver = (payload) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolvePromise(payload);
+      };
+
+      const onAbort = (): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        rejectPromise(new Error('Pipeline aborted'));
+      };
+
+      const cleanup = (): void => {
+        if (timer) clearTimeout(timer);
+        ctx.signal.removeEventListener('abort', onAbort);
+        const idx = state.waiters.indexOf(onFire);
+        if (idx !== -1) state.waiters.splice(idx, 1);
+      };
+
+      state.waiters.push(onFire);
+      ctx.signal.addEventListener('abort', onAbort, { once: true });
+
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          rejectPromise(
+            new Error(
+              `webhook trigger timeout: no POST on :${port}${path} within ${String(config.timeout)}`,
+            ),
+          );
+        }, timeoutMs);
+      }
+    });
+  },
+};
+
+// ═══ Plugin self-description exports ═══
+export const pluginCategory = 'triggers';
+export const pluginType = 'webhook';
+export default WebhookTrigger;