@desplega.ai/agent-swarm 1.80.1 → 1.80.3

package/src/tests/workflow-triggers-v2.test.ts

@@ -2,7 +2,14 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import crypto from "node:crypto";
 import { unlink } from "node:fs/promises";
 import { z } from "zod";
-import { closeDb, createWorkflow, getWorkflowRun, initDb, updateWorkflow } from "../be/db";
+import {
+  closeDb,
+  createWorkflow,
+  getWorkflowRun,
+  initDb,
+  updateWorkflow,
+  upsertSwarmConfig,
+} from "../be/db";
 import type { Workflow } from "../types";
 import { startWorkflowExecution } from "../workflows/engine";
 import { BaseExecutor, type ExecutorResult } from "../workflows/executors/base";
@@ -118,7 +125,12 @@ describe("handleWebhookTrigger", () => {
     hmac.update(body);
     const sig = `sha256=${hmac.digest("hex")}`;
 
-    const result = await handleWebhookTrigger(workflow.id, body, sig, sig, registry);
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-hub-signature-256": sig },
+      registry,
+    );
 
     expect(result.runId).toBeDefined();
     expect(typeof result.runId).toBe("string");
@@ -138,8 +150,7 @@ describe("handleWebhookTrigger", () => {
       await handleWebhookTrigger(
         workflow.id,
         '{"test":true}',
-        "sha256=invalid",
-        "sha256=invalid",
+        { "x-hub-signature-256": "sha256=invalid" },
         registry,
       );
       expect(true).toBe(false); // Should not reach here
@@ -155,7 +166,7 @@ describe("handleWebhookTrigger", () => {
     });
 
     try {
-      await handleWebhookTrigger(workflow.id, '{"test":true}', undefined, undefined, registry);
+      await handleWebhookTrigger(workflow.id, '{"test":true}', {}, registry);
       expect(true).toBe(false);
     } catch (err) {
       expect(err).toBeInstanceOf(WebhookError);
@@ -168,13 +179,7 @@ describe("handleWebhookTrigger", () => {
       triggers: [{ type: "webhook" }],
     });
 
-    const result = await handleWebhookTrigger(
-      workflow.id,
-      '{"data":"hello"}',
-      undefined,
-      undefined,
-      registry,
-    );
+    const result = await handleWebhookTrigger(workflow.id, '{"data":"hello"}', {}, registry);
 
     expect(result.runId).toBeDefined();
     const run = getWorkflowRun(result.runId);
@@ -183,13 +188,7 @@ describe("handleWebhookTrigger", () => {
 
   test("workflow not found returns 404", async () => {
     try {
-      await handleWebhookTrigger(
-        "00000000-0000-0000-0000-000000000000",
-        "{}",
-        undefined,
-        undefined,
-        registry,
-      );
+      await handleWebhookTrigger("00000000-0000-0000-0000-000000000000", "{}", {}, registry);
       expect(true).toBe(false);
     } catch (err) {
       expect(err).toBeInstanceOf(WebhookError);
@@ -205,7 +204,7 @@ describe("handleWebhookTrigger", () => {
     updateWorkflow(workflow.id, { enabled: false });
 
     try {
-      await handleWebhookTrigger(workflow.id, "{}", undefined, undefined, registry);
+      await handleWebhookTrigger(workflow.id, "{}", {}, registry);
       expect(true).toBe(false);
     } catch (err) {
       expect(err).toBeInstanceOf(WebhookError);
@@ -214,6 +213,248 @@ describe("handleWebhookTrigger", () => {
   });
 });
 
+// ─── Custom HMAC header + secret refs ───────────────────────
+
+describe("handleWebhookTrigger — custom hmacHeader", () => {
+  function signRaw(secret: string, body: string): string {
+    return crypto.createHmac("sha256", secret).update(body).digest("hex");
+  }
+
+  test("custom hmacHeader (X-Webhook-Signature) is picked up and verified", async () => {
+    const secret = "kapso-secret";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret, hmacHeader: "X-Webhook-Signature" }],
+    });
+
+    const body = '{"event":"message"}';
+    // Kapso-style: raw hex, no `sha256=` prefix.
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-webhook-signature": signRaw(secret, body) },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+    expect(getWorkflowRun(result.runId)).not.toBeNull();
+  });
+
+  test("custom hmacHeader lookup is case-insensitive", async () => {
+    const secret = "kapso-secret-ci";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret, hmacHeader: "X-Webhook-Signature" }],
+    });
+
+    const body = '{"event":"ci"}';
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "X-Webhook-Signature": signRaw(secret, body) },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+  });
+
+  test("signature on a non-configured header is rejected as missing", async () => {
+    const secret = "kapso-secret-2";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret, hmacHeader: "X-Webhook-Signature" }],
+    });
+
+    const body = '{"event":"x"}';
+    // Use a header that is neither the configured one nor a known fallback.
+    try {
+      await handleWebhookTrigger(
+        workflow.id,
+        body,
+        { "x-some-other-header": signRaw(secret, body) },
+        registry,
+      );
+      expect(true).toBe(false);
+    } catch (err) {
+      expect(err).toBeInstanceOf(WebhookError);
+      expect((err as WebhookError).statusCode).toBe(401);
+    }
+  });
+
+  test("fallback header (x-signature) still works without explicit hmacHeader", async () => {
+    const secret = "fallback-secret";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret }],
+    });
+
+    const body = '{"event":"fallback"}';
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-signature": signRaw(secret, body) },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+  });
+
+  test("default X-Hub-Signature-256 path still works (no regression)", async () => {
+    const secret = "default-header-secret";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret }],
+    });
+
+    const body = '{"event":"default"}';
+    const sig = `sha256=${signRaw(secret, body)}`;
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-hub-signature-256": sig },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+  });
+});
+
+describe("handleWebhookTrigger — hmacSecret references", () => {
+  function signRaw(secret: string, body: string): string {
+    return crypto.createHmac("sha256", secret).update(body).digest("hex");
+  }
+
+  test("hmacSecret as secret.NAME ref resolves and verifies", async () => {
+    const SECRET_VALUE = "resolved-kapso-hmac-value";
+    upsertSwarmConfig({
+      scope: "global",
+      key: "TEST_KAPSO_WEBHOOK_HMAC_SECRET",
+      value: SECRET_VALUE,
+      isSecret: true,
+    });
+
+    const workflow = makeWorkflow({
+      triggers: [
+        {
+          type: "webhook",
+          hmacSecret: "secret.TEST_KAPSO_WEBHOOK_HMAC_SECRET",
+          hmacHeader: "X-Webhook-Signature",
+        },
+      ],
+    });
+
+    const body = '{"event":"secret-ref"}';
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-webhook-signature": signRaw(SECRET_VALUE, body) },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+    expect(getWorkflowRun(result.runId)).not.toBeNull();
+  });
+
+  test("unresolvable secret.NAME ref fails cleanly with a WebhookError", async () => {
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: "secret.NONEXISTENT_HMAC_SECRET_12345" }],
+    });
+
+    const body = '{"event":"missing-secret"}';
+    try {
+      await handleWebhookTrigger(
+        workflow.id,
+        body,
+        { "x-hub-signature-256": "deadbeef" },
+        registry,
+      );
+      expect(true).toBe(false);
+    } catch (err) {
+      expect(err).toBeInstanceOf(WebhookError);
+      expect((err as WebhookError).statusCode).toBe(500);
+    }
+  });
+
+  test("a literal hmacSecret is not treated as a reference", async () => {
+    const secret = "plain.literal-not-a-ref";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret }],
+    });
+
+    const body = '{"event":"literal"}';
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-hub-signature-256": signRaw(secret, body) },
+      registry,
+    );
+
+    expect(result.runId).toBeDefined();
+  });
+});
+
+// ─── Trigger payload JSON parsing ───────────────────────────
+
+describe("handleWebhookTrigger — triggerData JSON parsing", () => {
+  function signRaw(secret: string, body: string): string {
+    return crypto.createHmac("sha256", secret).update(body).digest("hex");
+  }
+
+  test("JSON body is parsed and run.triggerData is a deep-equal object", async () => {
+    const workflow = makeWorkflow({ triggers: [{ type: "webhook" }] });
+    const payload = {
+      message: { from: "+34000111222", text: "hi" },
+      conversation: { id: "conv-abc-123" },
+    };
+    const body = JSON.stringify(payload);
+
+    const result = await handleWebhookTrigger(workflow.id, body, {}, registry);
+
+    const run = getWorkflowRun(result.runId);
+    expect(run).not.toBeNull();
+    expect(run!.triggerData).toEqual(payload);
+    // Deep paths must be reachable (this is what `{{trigger.message.from}}` needs).
+    expect((run!.triggerData as { message: { from: string } }).message.from).toBe("+34000111222");
+  });
+
+  test("signed JSON body: HMAC verified against raw bytes, triggerData parsed to object", async () => {
+    const secret = "kapso-deep-secret";
+    const workflow = makeWorkflow({
+      triggers: [{ type: "webhook", hmacSecret: secret, hmacHeader: "X-Webhook-Signature" }],
+    });
+    // Use whitespace + unsorted keys so any re-serialization would change the bytes.
+    const body = '{ "message": {"from":"+1","text":"hi"},  "id":"x" }';
+    const sig = signRaw(secret, body);
+
+    const result = await handleWebhookTrigger(
+      workflow.id,
+      body,
+      { "x-webhook-signature": sig },
+      registry,
+    );
+
+    const run = getWorkflowRun(result.runId);
+    expect(run).not.toBeNull();
+    expect(run!.triggerData).toEqual({ message: { from: "+1", text: "hi" }, id: "x" });
+  });
+
+  test("non-JSON body falls back to the raw string and does not throw", async () => {
+    const workflow = makeWorkflow({ triggers: [{ type: "webhook" }] });
+    const body = "this is not json at all";
+
+    const result = await handleWebhookTrigger(workflow.id, body, {}, registry);
+
+    const run = getWorkflowRun(result.runId);
+    expect(run).not.toBeNull();
+    expect(run!.triggerData).toBe(body);
+  });
+
+  test("empty body produces a run without throwing", async () => {
+    const workflow = makeWorkflow({ triggers: [{ type: "webhook" }] });
+
+    const result = await handleWebhookTrigger(workflow.id, "", {}, registry);
+
+    expect(result.runId).toBeDefined();
+    const run = getWorkflowRun(result.runId);
+    expect(run).not.toBeNull();
+  });
+});
+
 // ─── Manual Trigger ─────────────────────────────────────────
 
 describe("manual trigger (startWorkflowExecution)", () => {

package/src/types.ts

@@ -1320,6 +1320,7 @@ export const ScriptRecordSchema = z.object({
   description: z.string(),
   intent: z.string(),
   signatureJson: z.string(),
+  argsJsonSchema: z.string().nullable(),
   contentHash: z.string(),
   version: z.number(),
   isScratch: z.boolean(),

package/src/utils/error-tracker.ts

@@ -10,8 +10,21 @@ export interface ErrorSignal {
   timestamp: string;
 }
 
+/**
+ * Clamps a candidate reset timestamp (ms) to [now+60s, now+6h].
+ * Protects against past timestamps (clock skew) and absurdly far future values (malformed).
+ */
+function clampRateLimitResetMs(candidateMs: number): number {
+  const nowMs = Date.now();
+  const minMs = nowMs + 60_000;
+  const maxMs = nowMs + 6 * 60 * 60 * 1000;
+  return Math.min(Math.max(candidateMs, minMs), maxMs);
+}
+
 export class SessionErrorTracker {
   private errors: ErrorSignal[] = [];
+  /** Stashed reset time (ms) from the last rejected rate_limit_event in this session. */
+  private rateLimitResetAtMs: number | undefined;
 
   /** Record an error from an assistant message with message.error field */
   addApiError(errorCategory: string, message: string): void {
@@ -53,6 +66,45 @@ export class SessionErrorTracker {
     });
   }
 
+  /**
+   * Process a parsed rate_limit_event JSON object from the Claude CLI stream.
+   * Only stashes the reset time when status === "rejected"; ignores all others.
+   * Last call wins — if the CLI emits multiple events, the final rejected one is used.
+   *
+   * `resetsAt` is **seconds** since epoch (empirically verified; Linear description is wrong).
+   * Conversion to ms happens here at this single well-named boundary.
+   */
+  processRateLimitEvent(json: Record<string, unknown>): void {
+    try {
+      const info = json.rate_limit_info as Record<string, unknown> | undefined;
+      if (!info) return;
+
+      if (info.status !== "rejected") return;
+
+      const resetsAtSec = info.resetsAt;
+      if (typeof resetsAtSec !== "number" || !Number.isFinite(resetsAtSec) || resetsAtSec <= 0) {
+        console.warn(
+          `[rate_limit_event] Malformed resetsAt value: ${JSON.stringify(resetsAtSec)} — ignoring`,
+        );
+        return;
+      }
+
+      const resetsAtMs = resetsAtSec * 1000;
+      this.rateLimitResetAtMs = clampRateLimitResetMs(resetsAtMs);
+    } catch (err) {
+      console.warn(`[rate_limit_event] Failed to process event: ${err}`);
+    }
+  }
+
+  /**
+   * Returns the stashed rate limit reset time as an ISO string, or undefined
+   * if no rejected rate_limit_event was seen in this session.
+   */
+  getRateLimitResetAt(): string | undefined {
+    if (this.rateLimitResetAtMs === undefined) return undefined;
+    return new Date(this.rateLimitResetAtMs).toISOString();
+  }
+
   hasErrors(): boolean {
     return this.errors.length > 0;
   }
@@ -137,6 +189,12 @@ export function trackErrorFromJson(
   json: Record<string, unknown>,
   tracker: SessionErrorTracker,
 ): void {
+  // 0. Structured rate limit event — stash resetsAt for the three-tier resolver in runner.ts
+  if (json.type === "rate_limit_event") {
+    tracker.processRateLimitEvent(json);
+    return;
+  }
+
   // 1. Assistant messages with API errors (rate_limit, auth, billing, etc.)
   if (json.type === "assistant") {
     const message = json.message as Record<string, unknown> | undefined;

package/src/workflows/input.ts

@@ -13,13 +13,18 @@ export function resolveInputs(input: Record<string, string>): Record<string, str
   const resolved: Record<string, string> = {};
 
   for (const [key, value] of Object.entries(input)) {
-    resolved[key] = resolveValue(value);
+    resolved[key] = resolveInputValue(value);
   }
 
   return resolved;
 }
 
-function resolveValue(value: string): string {
+/**
+ * Resolve a single input value, supporting `${ENV_VAR}` and `secret.NAME`
+ * references. A plain string is returned unchanged. Throws if a referenced
+ * env var or swarm secret cannot be found.
+ */
+export function resolveInputValue(value: string): string {
   // Env var reference: ${MY_VAR}
   const envMatch = /^\$\{(.+)\}$/.exec(value);
   if (envMatch?.[1]) {

package/src/workflows/triggers.ts

@@ -3,19 +3,75 @@ import { getWorkflow, getWorkflowsByScheduleId } from "../be/db";
 import type { ScheduledTask, TriggerConfig } from "../types";
 import { startWorkflowExecution } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
+import { resolveInputValue } from "./input";
+
+/** Header name used to look up an HMAC signature when the trigger configures none. */
+const DEFAULT_HMAC_HEADER = "X-Hub-Signature-256";
+
+/** Fallback header names checked (case-insensitive) after the trigger's configured header. */
+const FALLBACK_HMAC_HEADERS = ["x-hub-signature-256", "x-signature", "x-webhook-signature"];
+
+/** A bag of HTTP headers — values may be a string, a string array, or absent. */
+export type HeaderBag = Record<string, string | string[] | undefined>;
+
+/** Case-insensitive header lookup; returns the first value when an array is given. */
+function getHeader(headers: HeaderBag, name: string): string | undefined {
+  const target = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === target) {
+      return Array.isArray(value) ? value[0] : value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the HMAC signature from request headers. Checks the trigger's
+ * configured `hmacHeader` first, then well-known fallback header names.
+ */
+function resolveSignature(headers: HeaderBag, hmacHeader: string): string | undefined {
+  for (const name of [hmacHeader, ...FALLBACK_HMAC_HEADERS]) {
+    const value = getHeader(headers, name);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the configured `hmacSecret`. Supports `secret.NAME` swarm-secret refs
+ * and `${ENV_VAR}` env refs (reusing the workflow input resolver); a plain
+ * string is treated as a literal. Resolved per request, never at create time.
+ */
+function resolveHmacSecret(raw: string): string {
+  if (/^secret\..+$/.test(raw) || /^\$\{.+\}$/.test(raw)) {
+    try {
+      return resolveInputValue(raw);
+    } catch (err) {
+      throw new WebhookError(
+        `Failed to resolve webhook HMAC secret: ${err instanceof Error ? err.message : String(err)}`,
+        500,
+      );
+    }
+  }
+  return raw;
+}
 
 /**
  * Handle an incoming webhook trigger for a workflow.
  *
  * 1. Loads the workflow and finds a webhook trigger in `triggers[]`
- * 2. If `hmacSecret` is set, verifies HMAC-SHA256 signature
- * 3. Starts the workflow execution with the webhook payload
+ * 2. If `hmacSecret` is set, resolves the signature header + secret and
+ *    verifies the HMAC-SHA256 signature against the raw body bytes
+ * 3. Parses the raw body as JSON (falling back to the raw string when the
+ *    body is non-JSON) so downstream `{{trigger.deep.path}}` interpolation
+ *    can traverse the object — matches the shape produced by the
+ *    `trigger-workflow` MCP tool.
+ * 4. Starts the workflow execution with the parsed payload
  */
 export async function handleWebhookTrigger(
   workflowId: string,
   payload: unknown,
-  signature: string | undefined,
-  signatureHeader: string | undefined,
+  headers: HeaderBag,
   registry: ExecutorRegistry,
 ): Promise<{ runId: string }> {
   const workflow = getWorkflow(workflowId);
@@ -31,16 +87,20 @@ export async function handleWebhookTrigger(
   const webhookTrigger = workflow.triggers.find((t: TriggerConfig) => t.type === "webhook");
 
   // If the workflow has a webhook trigger with an hmacSecret, verify the signature
+  // against the RAW body bytes — re-serializing would change whitespace / key order
+  // and break the HMAC.
   if (webhookTrigger && webhookTrigger.type === "webhook" && webhookTrigger.hmacSecret) {
-    if (!signature && !signatureHeader) {
+    const hmacHeader = webhookTrigger.hmacHeader || DEFAULT_HMAC_HEADER;
+    const signature = resolveSignature(headers, hmacHeader);
+    if (!signature) {
       throw new WebhookError("Missing signature", 401);
     }
 
-    const rawSignature = signatureHeader || signature || "";
+    const secret = resolveHmacSecret(webhookTrigger.hmacSecret);
     const isValid = verifyHmacSignature(
-      webhookTrigger.hmacSecret,
+      secret,
       typeof payload === "string" ? payload : JSON.stringify(payload),
-      rawSignature,
+      signature,
     );
 
     if (!isValid) {
@@ -48,10 +108,30 @@ export async function handleWebhookTrigger(
     }
   }
 
-  const runId = await startWorkflowExecution(workflow, payload, registry);
+  // Parse the raw body so downstream nodes can interpolate deep paths
+  // (e.g. `{{trigger.message.from}}`). A non-JSON body falls back to the raw
+  // string so non-JSON webhooks don't break.
+  const triggerData = parseTriggerPayload(payload);
+
+  const runId = await startWorkflowExecution(workflow, triggerData, registry);
   return { runId };
 }
 
+/**
+ * If `payload` is a JSON string, parse and return the resulting value;
+ * otherwise return it as-is. Empty / non-JSON strings fall back to the raw
+ * value so non-JSON webhooks (text/plain, form-encoded, etc.) still produce
+ * a usable workflow run.
+ */
+function parseTriggerPayload(payload: unknown): unknown {
+  if (typeof payload !== "string" || payload.length === 0) return payload;
+  try {
+    return JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+}
+
 /**
  * Handle a schedule trigger: find workflows linked to this schedule and execute them.
  * Returns an array of workflow run IDs. Empty array means no workflows matched