@blokjs/trigger-webhook 0.2.1 → 0.6.1

package/dist/index.d.ts

@@ -1,70 +1,41 @@
 /**
- * @blok/trigger-webhook
- *
- * Webhook trigger for Blok workflows.
- * Handle webhook events from external services.
- *
- * Supported Services:
- * - GitHub (push, pull_request, issues, releases, etc.)
- * - Stripe (payment_intent, checkout.session, customer, etc.)
- * - Shopify (orders, products, customers, etc.)
- * - Custom webhooks (any service with signature verification)
- *
- * Features:
- * - Signature verification (HMAC-SHA256)
- * - Event type filtering
- * - Source-specific handlers
- * - Custom source registration
- *
- * @example
- * ```typescript
- * import { WebhookTrigger } from "@blok/trigger-webhook";
- *
- * class MyWebhookTrigger extends WebhookTrigger {
- *   protected nodes = myNodes;
- *   protected workflows = myWorkflows;
+ * @blokjs/trigger-webhook
+ *
+ * Inbound webhook trigger for Blok workflows. Mounts verified POST
+ * routes on the shared Hono server alongside HTTP, WebSocket, and
+ * SSE routes — same port, same middleware chain, same Studio
+ * tracing. Verifies provider signatures (GitHub, Stripe, Slack,
+ * Shopify, Svix/Standard Webhooks) or a custom HMAC scheme, applies
+ * replay protection via the idempotency cache, and dispatches the
+ * workflow.
+ *
+ * v0.7+ usage (just add the trigger to your workflow):
+ *
+ * ```json
+ * {
+ *   "name": "stripe-events",
+ *   "trigger": {
+ *     "webhook": {
+ *       "provider": "stripe",
+ *       "path": "/webhooks/stripe",
+ *       "secretEnv": "STRIPE_WEBHOOK_SECRET",
+ *       "namespace": "stripe",
+ *       "idempotencyKey": "js/ctx.request.body.id"
+ *     }
+ *   },
+ *   "steps": [
+ *     { "id": "dispatch", "subworkflow": "js/ctx.request.body.type", "inputs": { "stripeEvent": "js/ctx.request.body" } }
+ *   ]
  * }
- *
- * const trigger = new MyWebhookTrigger();
- * await trigger.listen();
- *
- * // In your HTTP endpoint handler:
- * app.post("/webhooks/:source", async (req, res) => {
- *   const rawBody = JSON.stringify(req.body);
- *   const result = await trigger.handleWebhook(
- *     req.params.source,
- *     rawBody,
- *     req.headers as Record<string, string>
- *   );
- *   res.status(200).json({ received: true });
- * });
- * ```
- *
- * Workflow Definition:
- * ```typescript
- * Workflow({ name: "github-push", version: "1.0.0" })
- *   .addTrigger("webhook", {
- *     source: "github",
- *     events: ["push", "pull_request.*"],
- *     secret: process.env.GITHUB_WEBHOOK_SECRET,
- *   })
- *   .addStep({ ... });
  * ```
  *
- * Custom Source Handler:
- * ```typescript
- * import { WebhookTrigger } from "@blok/trigger-webhook";
- *
- * WebhookTrigger.registerSourceHandler("my-service", {
- *   getEventType: (headers, body) => body.event_type,
- *   getSignature: (headers) => headers["x-my-signature"],
- *   verifySignature: (rawBody, signature, secret) => {
- *     // Your verification logic
- *     return { valid: true };
- *   },
- *   getEventId: (headers, body) => body.id,
- * });
- * ```
+ * See [additional-triggers-plan.mdx](../../../docs/c/devtools/additional-triggers-plan.mdx#webhook-trigger)
+ * for the full design.
  */
-export { WebhookTrigger, sourceHandlers, type WebhookEvent, type VerificationResult, type WebhookSourceHandler, } from "./WebhookTrigger";
-export type { WebhookTriggerOpts } from "@blok/helper";
+import WebhookTrigger, { _getActiveWebhookTrigger, _setActiveWebhookTrigger } from "./WebhookTrigger";
+export default WebhookTrigger;
+export { WebhookTrigger, _getActiveWebhookTrigger, _setActiveWebhookTrigger };
+export type { WebhookTriggerConfig } from "./WebhookTrigger";
+export type { WebhookTriggerOpts } from "@blokjs/helper";
+export { BUILTIN_VERIFIERS, buildCustomVerifier, githubVerifier, shopifyVerifier, slackVerifier, stripeVerifier, svixVerifier, } from "./verifiers";
+export type { CustomSignatureConfig, VerifyError, VerifyInput, VerifyOk, VerifyResult, Verifier } from "./verifiers";

package/dist/index.js

@@ -1,76 +1,39 @@
-"use strict";
 /**
- * @blok/trigger-webhook
- *
- * Webhook trigger for Blok workflows.
- * Handle webhook events from external services.
- *
- * Supported Services:
- * - GitHub (push, pull_request, issues, releases, etc.)
- * - Stripe (payment_intent, checkout.session, customer, etc.)
- * - Shopify (orders, products, customers, etc.)
- * - Custom webhooks (any service with signature verification)
- *
- * Features:
- * - Signature verification (HMAC-SHA256)
- * - Event type filtering
- * - Source-specific handlers
- * - Custom source registration
- *
- * @example
- * ```typescript
- * import { WebhookTrigger } from "@blok/trigger-webhook";
- *
- * class MyWebhookTrigger extends WebhookTrigger {
- *   protected nodes = myNodes;
- *   protected workflows = myWorkflows;
+ * @blokjs/trigger-webhook
+ *
+ * Inbound webhook trigger for Blok workflows. Mounts verified POST
+ * routes on the shared Hono server alongside HTTP, WebSocket, and
+ * SSE routes — same port, same middleware chain, same Studio
+ * tracing. Verifies provider signatures (GitHub, Stripe, Slack,
+ * Shopify, Svix/Standard Webhooks) or a custom HMAC scheme, applies
+ * replay protection via the idempotency cache, and dispatches the
+ * workflow.
+ *
+ * v0.7+ usage (just add the trigger to your workflow):
+ *
+ * ```json
+ * {
+ *   "name": "stripe-events",
+ *   "trigger": {
+ *     "webhook": {
+ *       "provider": "stripe",
+ *       "path": "/webhooks/stripe",
+ *       "secretEnv": "STRIPE_WEBHOOK_SECRET",
+ *       "namespace": "stripe",
+ *       "idempotencyKey": "js/ctx.request.body.id"
+ *     }
+ *   },
+ *   "steps": [
+ *     { "id": "dispatch", "subworkflow": "js/ctx.request.body.type", "inputs": { "stripeEvent": "js/ctx.request.body" } }
+ *   ]
  * }
- *
- * const trigger = new MyWebhookTrigger();
- * await trigger.listen();
- *
- * // In your HTTP endpoint handler:
- * app.post("/webhooks/:source", async (req, res) => {
- *   const rawBody = JSON.stringify(req.body);
- *   const result = await trigger.handleWebhook(
- *     req.params.source,
- *     rawBody,
- *     req.headers as Record<string, string>
- *   );
- *   res.status(200).json({ received: true });
- * });
- * ```
- *
- * Workflow Definition:
- * ```typescript
- * Workflow({ name: "github-push", version: "1.0.0" })
- *   .addTrigger("webhook", {
- *     source: "github",
- *     events: ["push", "pull_request.*"],
- *     secret: process.env.GITHUB_WEBHOOK_SECRET,
- *   })
- *   .addStep({ ... });
  * ```
  *
- * Custom Source Handler:
- * ```typescript
- * import { WebhookTrigger } from "@blok/trigger-webhook";
- *
- * WebhookTrigger.registerSourceHandler("my-service", {
- *   getEventType: (headers, body) => body.event_type,
- *   getSignature: (headers) => headers["x-my-signature"],
- *   verifySignature: (rawBody, signature, secret) => {
- *     // Your verification logic
- *     return { valid: true };
- *   },
- *   getEventId: (headers, body) => body.id,
- * });
- * ```
+ * See [additional-triggers-plan.mdx](../../../docs/c/devtools/additional-triggers-plan.mdx#webhook-trigger)
+ * for the full design.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sourceHandlers = exports.WebhookTrigger = void 0;
-// Core exports
-var WebhookTrigger_1 = require("./WebhookTrigger");
-Object.defineProperty(exports, "WebhookTrigger", { enumerable: true, get: function () { return WebhookTrigger_1.WebhookTrigger; } });
-Object.defineProperty(exports, "sourceHandlers", { enumerable: true, get: function () { return WebhookTrigger_1.sourceHandlers; } });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBbUVHOzs7QUFFSCxlQUFlO0FBQ2YsbURBTTBCO0FBTHpCLGdIQUFBLGNBQWMsT0FBQTtBQUNkLGdIQUFBLGNBQWMsT0FBQSIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQGJsb2svdHJpZ2dlci13ZWJob29rXG4gKlxuICogV2ViaG9vayB0cmlnZ2VyIGZvciBCbG9rIHdvcmtmbG93cy5cbiAqIEhhbmRsZSB3ZWJob29rIGV2ZW50cyBmcm9tIGV4dGVybmFsIHNlcnZpY2VzLlxuICpcbiAqIFN1cHBvcnRlZCBTZXJ2aWNlczpcbiAqIC0gR2l0SHViIChwdXNoLCBwdWxsX3JlcXVlc3QsIGlzc3VlcywgcmVsZWFzZXMsIGV0Yy4pXG4gKiAtIFN0cmlwZSAocGF5bWVudF9pbnRlbnQsIGNoZWNrb3V0LnNlc3Npb24sIGN1c3RvbWVyLCBldGMuKVxuICogLSBTaG9waWZ5IChvcmRlcnMsIHByb2R1Y3RzLCBjdXN0b21lcnMsIGV0Yy4pXG4gKiAtIEN1c3RvbSB3ZWJob29rcyAoYW55IHNlcnZpY2Ugd2l0aCBzaWduYXR1cmUgdmVyaWZpY2F0aW9uKVxuICpcbiAqIEZlYXR1cmVzOlxuICogLSBTaWduYXR1cmUgdmVyaWZpY2F0aW9uIChITUFDLVNIQTI1NilcbiAqIC0gRXZlbnQgdHlwZSBmaWx0ZXJpbmdcbiAqIC0gU291cmNlLXNwZWNpZmljIGhhbmRsZXJzXG4gKiAtIEN1c3RvbSBzb3VyY2UgcmVnaXN0cmF0aW9uXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IFdlYmhvb2tUcmlnZ2VyIH0gZnJvbSBcIkBibG9rL3RyaWdnZXItd2ViaG9va1wiO1xuICpcbiAqIGNsYXNzIE15V2ViaG9va1RyaWdnZXIgZXh0ZW5kcyBXZWJob29rVHJpZ2dlciB7XG4gKiAgIHByb3RlY3RlZCBub2RlcyA9IG15Tm9kZXM7XG4gKiAgIHByb3RlY3RlZCB3b3JrZmxvd3MgPSBteVdvcmtmbG93cztcbiAqIH1cbiAqXG4gKiBjb25zdCB0cmlnZ2VyID0gbmV3IE15V2ViaG9va1RyaWdnZXIoKTtcbiAqIGF3YWl0IHRyaWdnZXIubGlzdGVuKCk7XG4gKlxuICogLy8gSW4geW91ciBIVFRQIGVuZHBvaW50IGhhbmRsZXI6XG4gKiBhcHAucG9zdChcIi93ZWJob29rcy86c291cmNlXCIsIGFzeW5jIChyZXEsIHJlcykgPT4ge1xuICogICBjb25zdCByYXdCb2R5ID0gSlNPTi5zdHJpbmdpZnkocmVxLmJvZHkpO1xuICogICBjb25zdCByZXN1bHQgPSBhd2FpdCB0cmlnZ2VyLmhhbmRsZVdlYmhvb2soXG4gKiAgICAgcmVxLnBhcmFtcy5zb3VyY2UsXG4gKiAgICAgcmF3Qm9keSxcbiAqICAgICByZXEuaGVhZGVycyBhcyBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+XG4gKiAgICk7XG4gKiAgIHJlcy5zdGF0dXMoMjAwKS5qc29uKHsgcmVjZWl2ZWQ6IHRydWUgfSk7XG4gKiB9KTtcbiAqIGBgYFxuICpcbiAqIFdvcmtmbG93IERlZmluaXRpb246XG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBXb3JrZmxvdyh7IG5hbWU6IFwiZ2l0aHViLXB1c2hcIiwgdmVyc2lvbjogXCIxLjAuMFwiIH0pXG4gKiAgIC5hZGRUcmlnZ2VyKFwid2ViaG9va1wiLCB7XG4gKiAgICAgc291cmNlOiBcImdpdGh1YlwiLFxuICogICAgIGV2ZW50czogW1wicHVzaFwiLCBcInB1bGxfcmVxdWVzdC4qXCJdLFxuICogICAgIHNlY3JldDogcHJvY2Vzcy5lbnYuR0lUSFVCX1dFQkhPT0tfU0VDUkVULFxuICogICB9KVxuICogICAuYWRkU3RlcCh7IC4uLiB9KTtcbiAqIGBgYFxuICpcbiAqIEN1c3RvbSBTb3VyY2UgSGFuZGxlcjpcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IFdlYmhvb2tUcmlnZ2VyIH0gZnJvbSBcIkBibG9rL3RyaWdnZXItd2ViaG9va1wiO1xuICpcbiAqIFdlYmhvb2tUcmlnZ2VyLnJlZ2lzdGVyU291cmNlSGFuZGxlcihcIm15LXNlcnZpY2VcIiwge1xuICogICBnZXRFdmVudFR5cGU6IChoZWFkZXJzLCBib2R5KSA9PiBib2R5LmV2ZW50X3R5cGUsXG4gKiAgIGdldFNpZ25hdHVyZTogKGhlYWRlcnMpID0+IGhlYWRlcnNbXCJ4LW15LXNpZ25hdHVyZVwiXSxcbiAqICAgdmVyaWZ5U2lnbmF0dXJlOiAocmF3Qm9keSwgc2lnbmF0dXJlLCBzZWNyZXQpID0+IHtcbiAqICAgICAvLyBZb3VyIHZlcmlmaWNhdGlvbiBsb2dpY1xuICogICAgIHJldHVybiB7IHZhbGlkOiB0cnVlIH07XG4gKiAgIH0sXG4gKiAgIGdldEV2ZW50SWQ6IChoZWFkZXJzLCBib2R5KSA9PiBib2R5LmlkLFxuICogfSk7XG4gKiBgYGBcbiAqL1xuXG4vLyBDb3JlIGV4cG9ydHNcbmV4cG9ydCB7XG5cdFdlYmhvb2tUcmlnZ2VyLFxuXHRzb3VyY2VIYW5kbGVycyxcblx0dHlwZSBXZWJob29rRXZlbnQsXG5cdHR5cGUgVmVyaWZpY2F0aW9uUmVzdWx0LFxuXHR0eXBlIFdlYmhvb2tTb3VyY2VIYW5kbGVyLFxufSBmcm9tIFwiLi9XZWJob29rVHJpZ2dlclwiO1xuXG4vLyBSZS1leHBvcnQgdHlwZXMgZnJvbSBoZWxwZXIgZm9yIGNvbnZlbmllbmNlXG5leHBvcnQgdHlwZSB7IFdlYmhvb2tUcmlnZ2VyT3B0cyB9IGZyb20gXCJAYmxvay9oZWxwZXJcIjtcbiJdfQ==
+import WebhookTrigger, { _getActiveWebhookTrigger, _setActiveWebhookTrigger } from "./WebhookTrigger";
+export default WebhookTrigger;
+export { WebhookTrigger, _getActiveWebhookTrigger, _setActiveWebhookTrigger };
+export { BUILTIN_VERIFIERS, buildCustomVerifier, githubVerifier, shopifyVerifier, slackVerifier, stripeVerifier, svixVerifier, } from "./verifiers";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWlDRztBQUVILE9BQU8sY0FBYyxFQUFFLEVBQUUsd0JBQXdCLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUV0RyxlQUFlLGNBQWMsQ0FBQztBQUM5QixPQUFPLEVBQUUsY0FBYyxFQUFFLHdCQUF3QixFQUFFLHdCQUF3QixFQUFFLENBQUM7QUFHOUUsT0FBTyxFQUNOLGlCQUFpQixFQUNqQixtQkFBbUIsRUFDbkIsY0FBYyxFQUNkLGVBQWUsRUFDZixhQUFhLEVBQ2IsY0FBYyxFQUNkLFlBQVksR0FDWixNQUFNLGFBQWEsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQGJsb2tqcy90cmlnZ2VyLXdlYmhvb2tcbiAqXG4gKiBJbmJvdW5kIHdlYmhvb2sgdHJpZ2dlciBmb3IgQmxvayB3b3JrZmxvd3MuIE1vdW50cyB2ZXJpZmllZCBQT1NUXG4gKiByb3V0ZXMgb24gdGhlIHNoYXJlZCBIb25vIHNlcnZlciBhbG9uZ3NpZGUgSFRUUCwgV2ViU29ja2V0LCBhbmRcbiAqIFNTRSByb3V0ZXMg4oCUIHNhbWUgcG9ydCwgc2FtZSBtaWRkbGV3YXJlIGNoYWluLCBzYW1lIFN0dWRpb1xuICogdHJhY2luZy4gVmVyaWZpZXMgcHJvdmlkZXIgc2lnbmF0dXJlcyAoR2l0SHViLCBTdHJpcGUsIFNsYWNrLFxuICogU2hvcGlmeSwgU3ZpeC9TdGFuZGFyZCBXZWJob29rcykgb3IgYSBjdXN0b20gSE1BQyBzY2hlbWUsIGFwcGxpZXNcbiAqIHJlcGxheSBwcm90ZWN0aW9uIHZpYSB0aGUgaWRlbXBvdGVuY3kgY2FjaGUsIGFuZCBkaXNwYXRjaGVzIHRoZVxuICogd29ya2Zsb3cuXG4gKlxuICogdjAuNysgdXNhZ2UgKGp1c3QgYWRkIHRoZSB0cmlnZ2VyIHRvIHlvdXIgd29ya2Zsb3cpOlxuICpcbiAqIGBgYGpzb25cbiAqIHtcbiAqICAgXCJuYW1lXCI6IFwic3RyaXBlLWV2ZW50c1wiLFxuICogICBcInRyaWdnZXJcIjoge1xuICogICAgIFwid2ViaG9va1wiOiB7XG4gKiAgICAgICBcInByb3ZpZGVyXCI6IFwic3RyaXBlXCIsXG4gKiAgICAgICBcInBhdGhcIjogXCIvd2ViaG9va3Mvc3RyaXBlXCIsXG4gKiAgICAgICBcInNlY3JldEVudlwiOiBcIlNUUklQRV9XRUJIT09LX1NFQ1JFVFwiLFxuICogICAgICAgXCJuYW1lc3BhY2VcIjogXCJzdHJpcGVcIixcbiAqICAgICAgIFwiaWRlbXBvdGVuY3lLZXlcIjogXCJqcy9jdHgucmVxdWVzdC5ib2R5LmlkXCJcbiAqICAgICB9XG4gKiAgIH0sXG4gKiAgIFwic3RlcHNcIjogW1xuICogICAgIHsgXCJpZFwiOiBcImRpc3BhdGNoXCIsIFwic3Vid29ya2Zsb3dcIjogXCJqcy9jdHgucmVxdWVzdC5ib2R5LnR5cGVcIiwgXCJpbnB1dHNcIjogeyBcInN0cmlwZUV2ZW50XCI6IFwianMvY3R4LnJlcXVlc3QuYm9keVwiIH0gfVxuICogICBdXG4gKiB9XG4gKiBgYGBcbiAqXG4gKiBTZWUgW2FkZGl0aW9uYWwtdHJpZ2dlcnMtcGxhbi5tZHhdKC4uLy4uLy4uL2RvY3MvYy9kZXZ0b29scy9hZGRpdGlvbmFsLXRyaWdnZXJzLXBsYW4ubWR4I3dlYmhvb2stdHJpZ2dlcilcbiAqIGZvciB0aGUgZnVsbCBkZXNpZ24uXG4gKi9cblxuaW1wb3J0IFdlYmhvb2tUcmlnZ2VyLCB7IF9nZXRBY3RpdmVXZWJob29rVHJpZ2dlciwgX3NldEFjdGl2ZVdlYmhvb2tUcmlnZ2VyIH0gZnJvbSBcIi4vV2ViaG9va1RyaWdnZXJcIjtcblxuZXhwb3J0IGRlZmF1bHQgV2ViaG9va1RyaWdnZXI7XG5leHBvcnQgeyBXZWJob29rVHJpZ2dlciwgX2dldEFjdGl2ZVdlYmhvb2tUcmlnZ2VyLCBfc2V0QWN0aXZlV2ViaG9va1RyaWdnZXIgfTtcbmV4cG9ydCB0eXBlIHsgV2ViaG9va1RyaWdnZXJDb25maWcgfSBmcm9tIFwiLi9XZWJob29rVHJpZ2dlclwiO1xuZXhwb3J0IHR5cGUgeyBXZWJob29rVHJpZ2dlck9wdHMgfSBmcm9tIFwiQGJsb2tqcy9oZWxwZXJcIjtcbmV4cG9ydCB7XG5cdEJVSUxUSU5fVkVSSUZJRVJTLFxuXHRidWlsZEN1c3RvbVZlcmlmaWVyLFxuXHRnaXRodWJWZXJpZmllcixcblx0c2hvcGlmeVZlcmlmaWVyLFxuXHRzbGFja1ZlcmlmaWVyLFxuXHRzdHJpcGVWZXJpZmllcixcblx0c3ZpeFZlcmlmaWVyLFxufSBmcm9tIFwiLi92ZXJpZmllcnNcIjtcbmV4cG9ydCB0eXBlIHsgQ3VzdG9tU2lnbmF0dXJlQ29uZmlnLCBWZXJpZnlFcnJvciwgVmVyaWZ5SW5wdXQsIFZlcmlmeU9rLCBWZXJpZnlSZXN1bHQsIFZlcmlmaWVyIH0gZnJvbSBcIi4vdmVyaWZpZXJzXCI7XG4iXX0=

package/dist/verifiers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Webhook signature verifiers — one strategy per supported provider.
+ *
+ * Each verifier reads the raw request bytes (NOT the JSON-parsed body)
+ * and the provider-specific signature header, computes the expected
+ * HMAC against a shared secret, and constant-time compares. On match,
+ * returns `{ ok: true, eventId, eventType }`. On mismatch / missing
+ * header / drift, returns `{ ok: false, reason, message }`.
+ *
+ * Constant-time comparison via `crypto.timingSafeEqual` is mandatory —
+ * a naive `===` compare leaks the expected HMAC byte by byte through
+ * timing variance and a network-adjacent attacker can recover the
+ * secret in ~256 requests per byte.
+ *
+ * Built-in providers + their signature shapes:
+ *
+ *   - **github**:    `X-Hub-Signature-256: sha256=<hex>` over rawBody.
+ *                    Event id from `X-GitHub-Delivery`; event type
+ *                    from `X-GitHub-Event` header.
+ *   - **stripe**:    `Stripe-Signature: t=<ts>,v1=<hex>` over
+ *                    `<ts>.<rawBody>` with a 5-minute drift window.
+ *                    Event id + type from body.id / body.type.
+ *   - **slack**:     `X-Slack-Signature: v0=<hex>` over
+ *                    `v0:<X-Slack-Request-Timestamp>:<rawBody>` with a
+ *                    5-minute drift window. Event type from
+ *                    body.event.type; event id from body.event_id.
+ *   - **shopify**:   `X-Shopify-Hmac-Sha256: <base64>` over rawBody.
+ *                    Event type from `X-Shopify-Topic`; event id from
+ *                    `X-Shopify-Webhook-Id`.
+ *   - **svix**:      Standard Webhooks. `webhook-signature:
+ *                    v1,<base64>` over `<webhook-id>.<webhook-timestamp>.<rawBody>`
+ *                    with a 5-minute drift window. Event id from
+ *                    `webhook-id`; event type from body.type.
+ *
+ * Custom (unknown provider) verifier is built dynamically by
+ * `buildCustomVerifier()` from the workflow's `signature` config.
+ */
+/** Successful verification result — workflow may proceed. */
+export interface VerifyOk {
+    ok: true;
+    /** Provider-specific event id (used for replay-protection cache key). */
+    eventId: string;
+    /** Provider-specific event type (used for the allowlist check). */
+    eventType: string;
+}
+/** Verification failure — trigger returns 401 with structured reason. */
+export interface VerifyError {
+    ok: false;
+    /** Stable discriminator — log/alert dashboards branch on this. */
+    reason: "missing_signature" | "missing_timestamp" | "missing_secret" | "bad_format" | "timestamp_drift" | "signature_mismatch";
+    /** Human-readable error message. Safe to surface to the sender. */
+    message: string;
+}
+export type VerifyResult = VerifyOk | VerifyError;
+/** Inputs every verifier receives. */
+export interface VerifyInput {
+    headers: Record<string, string>;
+    rawBody: string;
+    parsedBody: unknown;
+    secret: string;
+    toleranceSec: number;
+}
+export interface Verifier {
+    verify(input: VerifyInput): VerifyResult;
+}
+export declare const githubVerifier: Verifier;
+export declare const stripeVerifier: Verifier;
+export declare const slackVerifier: Verifier;
+export declare const shopifyVerifier: Verifier;
+export declare const svixVerifier: Verifier;
+export interface CustomSignatureConfig {
+    scheme: "hmac-sha256" | "hmac-sha1" | "hmac-sha512";
+    header: string;
+    format: string;
+    secretEnv: string;
+    tolerance: number;
+    timestampHeader?: string;
+}
+export declare function buildCustomVerifier(config: CustomSignatureConfig): Verifier;
+export declare const BUILTIN_VERIFIERS: Record<string, Verifier>;