@voltro/plugin-webhooks 0.1.0

package/dist/mixin.d.ts

@@ -0,0 +1,51 @@
+import { TableLike } from '@voltro/database';
+
+/**
+ * One row per delivery attempt — NOT per emit. An emit fans out to
+ * N targets; each target then runs ≤ `maxAttempts` deliveries. The
+ * primary key is `(deliveryId, attempt)`; `deliveryId` is shared
+ * across retries of the SAME (event, payload, target) tuple so the
+ * dashboard groups them.
+ *
+ * Status lifecycle: `pending` (queued — the target was paused at emit
+ * time, or the attempt is rate-deferred to the next window) →
+ * `inFlight` → `succeeded` | `failed` | `retryScheduled`. On retry the
+ * workflow creates a new `(deliveryId, attempt+1)` row; on
+ * resume/deferral the SAME attempt-1 row transitions out of `pending`.
+ */
+export declare const _voltroWebhookDeliveriesTable: TableLike;
+
+/**
+ * Fixed-window rate-limit counters — one row per (scope, minute
+ * bucket), where scope is `target:<targetId>` (per-target
+ * `rateLimitPerMinute`) or `event:<eventId>` (an outgoing event's
+ * `globalRateLimit`). The delivery workflow claims a slot via a CAS
+ * loop over `count` (see `rateLimit.ts`) BEFORE every wire POST, so
+ * the cap holds across replicas — the counter lives here, never in
+ * process memory.
+ *
+ * Deliberately NOT tenant-scoped: rows carry only a scope key + an
+ * integer count (no payload, no secret, no tenant data), and the
+ * background delivery workflow that writes them has no request
+ * subject. The deterministic PK `<scope>@<bucket>` is the
+ * `insertIgnore` conflict target for the first-in-window create race.
+ */
+export declare const _voltroWebhookRateWindowsTable: TableLike;
+
+/**
+ * One row per subscribed delivery target. Created via
+ * `webhooks.subscribe(...)`. Read-only from app code; mutate via
+ * the `webhooks` service so the framework can run validation +
+ * generate secrets + invalidate caches.
+ */
+export declare const _voltroWebhookTargetsTable: TableLike;
+
+/**
+ * Return the framework-managed tables the webhooks plugin adds.
+ * Consumed by the plugin entry's `registerSchema` hook so the
+ * bootstrap migration creates the tables BEFORE any user
+ * migration runs.
+ */
+export declare const webhookTables: () => ReadonlyArray<TableLike>;
+
+export { }

package/dist/mixin.js

@@ -0,0 +1,68 @@
+import { boolean as e, id as t, integer as n, json as r, registerRetention as i, retentionTtlMsFromEnv as a, table as o, text as s, timestamp as c } from "@voltro/database";
+import { tenant as l } from "@voltro/plugin-multitenancy/mixin";
+//#region src/mixin.ts
+var u = o("_voltro_webhook_targets", {
+	id: t({ prefix: "whtarget" }),
+	event: s(),
+	url: s(),
+	secret: s(),
+	signing: r(),
+	retry: r(),
+	filter: r().nullable(),
+	headers: r().nullable(),
+	rateLimitPerMinute: n().nullable(),
+	active: e().default(!0),
+	format: s().oneOf([
+		"json",
+		"form",
+		"xml"
+	]).default("json"),
+	autoDisableAfter: n().nullable(),
+	consecutiveFailures: n().default(0),
+	autoDisabledAt: c().nullable(),
+	autoDisableReason: s().nullable(),
+	payloadVersion: n().default(1),
+	description: s().nullable()
+}).with(l()), d = o("_voltro_webhook_deliveries", {
+	id: t({ prefix: "whdeliv" }),
+	deliveryId: s(),
+	targetId: s(),
+	event: s(),
+	eventId: s().nullable(),
+	attempt: n(),
+	status: s().oneOf([
+		"pending",
+		"inFlight",
+		"succeeded",
+		"failed",
+		"retryScheduled"
+	]),
+	payload: r(),
+	responseStatus: n().nullable(),
+	responseBody: s().nullable(),
+	errorMessage: s().nullable(),
+	latencyMs: n().nullable(),
+	scheduledAt: c(),
+	nextAttemptAt: c().nullable()
+}).with(l()), f = o("_voltro_webhook_rate_windows", {
+	id: t({ prefix: "whrate" }),
+	scope: s().maxLength(191),
+	bucket: n(),
+	count: n().default(0),
+	createdAt: c(),
+	updatedAt: c()
+}), p = () => (i({
+	table: "_voltro_webhook_deliveries",
+	timeColumn: "createdAt",
+	ttlMs: a(process.env.VOLTRO_WEBHOOK_DELIVERIES_TTL_HOURS, 2160)
+}), i({
+	table: "_voltro_webhook_rate_windows",
+	timeColumn: "createdAt",
+	ttlMs: 24 * 36e5
+}), [
+	u,
+	d,
+	f
+]);
+//#endregion
+export { d as _voltroWebhookDeliveriesTable, f as _voltroWebhookRateWindowsTable, u as _voltroWebhookTargetsTable, p as webhookTables };

package/dist/providers/index.d.ts

@@ -0,0 +1,166 @@
+import { Schema } from 'effect';
+
+declare interface CustomSignatureScheme {
+    readonly _tag: 'custom';
+    readonly header: string;
+    readonly sign: (rawBody: Uint8Array, secret: string) => string;
+    readonly verify: (rawBody: Uint8Array, secret: string, signatureHeader: string) => boolean;
+}
+
+export declare const genericProvider: (options?: {
+    readonly signatureHeader?: string;
+    readonly replayWindowSeconds?: number;
+}) => WebhookProviderDescriptor;
+
+export declare const githubProvider: () => WebhookProviderDescriptor;
+
+declare type HmacAlgorithm = 'hmacSha256' | 'hmacSha1';
+
+declare interface HmacSignatureScheme {
+    readonly _tag: 'hmac';
+    readonly algorithm: HmacAlgorithm;
+    /** Header the signature is written to / read from. Stripe uses
+     *  `Stripe-Signature`, GitHub uses `X-Hub-Signature-256`, generic
+     *  apps use `X-Webhook-Signature`. */
+    readonly header: string;
+    /** When `true`, the signed payload is `<timestamp>.<rawBody>` and
+     *  the header carries both (`t=...,v1=...`). Recipients reject
+     *  signatures whose `t` is older than `replayWindowSeconds`. */
+    readonly includeTimestamp: boolean;
+    /** Window during which a signed payload is replay-safe. Older
+     *  signatures get rejected. Default 5 minutes. Only relevant when
+     *  `includeTimestamp: true`. */
+    readonly replayWindowSeconds?: number;
+    /** Encoding the signature is rendered in. `hex` is most common;
+     *  Slack uses `hex` prefixed with `v0=`. */
+    readonly encoding?: 'hex' | 'base64';
+    /** Prefix written before the hex/base64 signature in the header
+     *  value. Slack: `v0=`. GitHub: `sha256=`. Default empty. */
+    readonly versionPrefix?: string;
+    /** Optional secret-rotation hint: a SECOND secret accepted during
+     *  verification but never used for outgoing signing. Lets you
+     *  rotate the primary secret without breaking in-flight inbound
+     *  deliveries. */
+    readonly previousSecret?: string;
+}
+
+declare interface IncomingWebhookContext<Body> {
+    /** The fully-decoded body, validated against `payload`. */
+    readonly body: Body;
+    /** Raw bytes — needed to recompute signatures. Already used by
+     *  the framework's middleware to verify the inbound signature
+     *  before this handler runs; passed along in case the user wants
+     *  to compute additional MAC's for downstream relays. */
+    readonly rawBody: Uint8Array;
+    /** Request headers (lowercased keys). The middleware has already
+     *  consumed signature / idempotency headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Idempotency key extracted by the middleware (provider-specific
+     *  extraction — Stripe uses `Stripe-Signature`'s `t=`, GitHub uses
+     *  `X-GitHub-Delivery`, generic uses `Idempotency-Key`). */
+    readonly idempotencyKey: string;
+    /** Workflow facade supplied by the framework runtime. Use this for
+     *  verified external incoming calls that should start or signal
+     *  durable workflows after signature + idempotency checks pass. */
+    readonly workflows?: IncomingWorkflowFacade;
+}
+
+declare interface IncomingWebhookDescriptor<Body> {
+    readonly _tag: 'incomingWebhook';
+    readonly id: WebhookId;
+    /** URL path the framework mounts the route on. Defaults to
+     *  `/webhooks/<id>` if absent. Use a custom path for legacy
+     *  integrations (`/integrations/stripe/v1`). */
+    readonly path?: `/${string}`;
+    /** Signature scheme used to authenticate inbound requests. Reject
+     *  on mismatch with a 401. `undefined` (the default) means NO
+     *  verification — only acceptable when behind a separate trust
+     *  boundary (gateway + IP allow-list). The dashboard surfaces a
+     *  warning for unsigned incoming webhooks. */
+    readonly signature?: SignatureScheme;
+    /** Idempotency key extraction. Default `'Idempotency-Key'` header.
+     *  Provider-templates override this to match the provider's wire
+     *  format. */
+    readonly idempotency?: {
+        /** Header name OR a function that reads from headers/body. */
+        readonly from: string | ((headers: Readonly<Record<string, string>>, rawBody: Uint8Array) => string | undefined);
+        /** TTL the framework retains the key for de-dup. Default 7 days. */
+        readonly ttl?: '5m' | '1h' | '6h' | '1d' | '7d' | '30d';
+    };
+    /** Validated body schema. The framework decodes the request body
+     *  AFTER signature verification, BEFORE the handler runs. */
+    readonly payload: Schema.Schema<Body>;
+    /** Body parser — JSON by default. Stripe / GitHub send `application/json`
+     *  but other providers use `application/x-www-form-urlencoded`. */
+    readonly bodyType?: 'json' | 'form' | 'raw';
+    /** Provider preset — when set, the framework fills `signature` +
+     *  `idempotency` + `bodyType` from the provider's known shape.
+     *  Explicit fields above always win. */
+    readonly provider?: WebhookProviderDescriptor;
+    /** Typed handler. Returns void on success, throws to reject. The
+     *  HTTP status is 2xx for success, 4xx for typed validation
+     *  errors, 5xx for handler exceptions. The framework retries
+     *  5xx-classified failures via the provider's expected behavior
+     *  (most providers retry their own POST on 5xx). */
+    readonly handler: (context: IncomingWebhookContext<Body>) => Promise<void> | void;
+}
+
+declare interface IncomingWorkflowFacade {
+    start<Payload = unknown>(workflowName: string, payload: Payload): Promise<{
+        readonly id: string;
+        readonly workflowName: string;
+        readonly executionId: string;
+        readonly status: 'running';
+    }>;
+    signal(target: {
+        readonly id?: string;
+        readonly executionId?: string;
+        readonly workflowName?: string;
+    }, signalName: string, payload?: unknown): Promise<{
+        readonly eventId: string;
+    }>;
+    update(target: {
+        readonly id?: string;
+        readonly executionId?: string;
+        readonly workflowName?: string;
+    }, updateName: string, payload?: unknown, options?: {
+        readonly timeoutMs?: number;
+        readonly pollIntervalMs?: number;
+    }): Promise<{
+        readonly eventId: string;
+        readonly updateId: string;
+        readonly completedEventId: string;
+        readonly result: unknown;
+    }>;
+}
+
+declare type SignatureScheme = HmacSignatureScheme | CustomSignatureScheme;
+
+export declare const slackProvider: () => WebhookProviderDescriptor;
+
+export declare const stripeProvider: (options?: {
+    /** Override the replay window. Stripe's default is 5 min;
+     *  callers running tests sometimes want a wider window. */
+    readonly replayWindowSeconds?: number;
+}) => WebhookProviderDescriptor;
+
+/** Stable identifier for an event or webhook. Drives the database
+ *  primary key, the inspect endpoint URL, the dashboard listing. Use
+ *  dotted-camelCase (`order.completed`, `user.signedUp`). */
+declare type WebhookId = string;
+
+declare interface WebhookProviderDescriptor {
+    readonly _tag: 'webhookProvider';
+    readonly id: string;
+    /** Display name for the dashboard. */
+    readonly name: string;
+    readonly signature: SignatureScheme;
+    readonly idempotency: NonNullable<IncomingWebhookDescriptor<unknown>['idempotency']>;
+    readonly bodyType: 'json' | 'form' | 'raw';
+    /** Optional discriminator: provider-specific event-type extraction
+     *  (e.g. Stripe's top-level `type` field). Used by typed handlers
+     *  to narrow on payload variant. */
+    readonly eventTypeFrom?: (body: unknown) => string | undefined;
+}
+
+export { }

package/dist/providers/index.js

@@ -0,0 +1,88 @@
+import { a as e, l as t, n, t as r } from "../signing-BOUxHdAo.js";
+import { createHmac as i, timingSafeEqual as a } from "node:crypto";
+//#region src/providers/stripe.ts
+var o = (n) => t({
+	id: "stripe",
+	name: "Stripe",
+	signature: {
+		...e(),
+		...n?.replayWindowSeconds === void 0 ? {} : { replayWindowSeconds: n.replayWindowSeconds }
+	},
+	idempotency: {
+		from: (e, t) => {
+			try {
+				return JSON.parse(new TextDecoder().decode(t)).id;
+			} catch {
+				return;
+			}
+		},
+		ttl: "30d"
+	},
+	bodyType: "json",
+	eventTypeFrom: (e) => {
+		if (typeof e == "object" && e && "type" in e) {
+			let t = e.type;
+			return typeof t == "string" ? t : void 0;
+		}
+	}
+}), s = () => t({
+	id: "github",
+	name: "GitHub",
+	signature: n(),
+	idempotency: {
+		from: "x-github-delivery",
+		ttl: "7d"
+	},
+	bodyType: "json",
+	eventTypeFrom: (e) => {}
+}), c = () => ({
+	_tag: "custom",
+	header: "X-Slack-Signature",
+	sign: (e, t) => {
+		let n = `v0:${Math.floor(Date.now() / 1e3)}:${new TextDecoder().decode(e)}`;
+		return `v0=${i("sha256", t).update(n).digest("hex")}`;
+	},
+	verify: (e, t, n) => {
+		let r = n.indexOf("|");
+		if (r === -1) return !1;
+		let o = n.slice(0, r), s = n.slice(r + 1);
+		if (!/^\d+$/.test(o)) return !1;
+		let c = Math.floor(Date.now() / 1e3);
+		if (Math.abs(c - Number(o)) > 300) return !1;
+		let l = `v0:${o}:${new TextDecoder().decode(e)}`, u = `v0=${i("sha256", t).update(l).digest("hex")}`, d = Buffer.from(u, "utf8"), f = Buffer.from(s, "utf8");
+		return d.length === f.length ? a(d, f) : (a(d, Buffer.alloc(d.length)), !1);
+	}
+}), l = () => t({
+	id: "slack",
+	name: "Slack",
+	signature: c(),
+	idempotency: {
+		from: "x-slack-request-timestamp",
+		ttl: "5m"
+	},
+	bodyType: "json",
+	eventTypeFrom: (e) => {
+		if (typeof e == "object" && e && "event" in e) {
+			let t = e.event;
+			if (typeof t == "object" && t && "type" in t) {
+				let e = t.type;
+				return typeof e == "string" ? e : void 0;
+			}
+		}
+	}
+}), u = (e) => t({
+	id: "generic",
+	name: "Generic",
+	signature: {
+		...r(),
+		...e?.signatureHeader === void 0 ? {} : { header: e.signatureHeader },
+		...e?.replayWindowSeconds === void 0 ? {} : { replayWindowSeconds: e.replayWindowSeconds }
+	},
+	idempotency: {
+		from: "idempotency-key",
+		ttl: "7d"
+	},
+	bodyType: "json"
+});
+//#endregion
+export { u as genericProvider, s as githubProvider, l as slackProvider, o as stripeProvider };

package/dist/signing-BOUxHdAo.js

@@ -0,0 +1,120 @@
+import { createHmac as e, timingSafeEqual as t } from "node:crypto";
+//#region src/dsl.ts
+var n = (e) => ({
+	_tag: "outgoingEvent",
+	...e
+}), r = (e) => ({
+	_tag: "incomingWebhook",
+	...e
+}), i = (e) => ({
+	_tag: "webhookProvider",
+	...e
+}), a = (e) => {
+	if (typeof e != "object" || !e) return !1;
+	let t = e._tag;
+	return t === "outgoingEvent" || t === "incomingWebhook" || t === "webhookProvider";
+}, o = (e) => e === "hmacSha256" ? "sha256" : "sha1", s = (t, n, r, i = "hex") => {
+	let a = e(o(t), n);
+	return a.update(r), a.digest(i);
+}, c = (e, t, n) => {
+	if (e._tag === "custom") return {
+		headerName: e.header,
+		headerValue: e.sign(t, n)
+	};
+	let r = e.encoding ?? "hex", i = e.versionPrefix ?? "";
+	if (e.includeTimestamp) {
+		let a = Math.floor(Date.now() / 1e3), o = Buffer.concat([Buffer.from(`${a}.`, "utf8"), Buffer.from(t)]), c = s(e.algorithm, n, o, r);
+		return {
+			headerName: e.header,
+			headerValue: `t=${a},${i}${c}`,
+			timestamp: a
+		};
+	}
+	let a = s(e.algorithm, n, t, r);
+	return {
+		headerName: e.header,
+		headerValue: `${i}${a}`
+	};
+}, l = (e, t, n, r) => {
+	if (!r) return {
+		ok: !1,
+		reason: "missing signature header"
+	};
+	if (e._tag === "custom") return e.verify(t, n, r) ? { ok: !0 } : {
+		ok: !1,
+		reason: "custom verifier rejected"
+	};
+	let i = e.encoding ?? "hex", a = e.versionPrefix ?? "", o = (n) => {
+		if (e.includeTimestamp) {
+			let o = r.split(",").map((e) => e.trim()), c = o.find((e) => e.startsWith("t="));
+			if (!c) return {
+				ok: !1,
+				reason: "no timestamp in signature header"
+			};
+			let l = Number(c.slice(2));
+			if (!Number.isFinite(l)) return {
+				ok: !1,
+				reason: "invalid timestamp"
+			};
+			let d = e.replayWindowSeconds ?? 300, f = Math.floor(Date.now() / 1e3);
+			if (Math.abs(f - l) > d) return {
+				ok: !1,
+				reason: `replay window exceeded (${Math.abs(f - l)}s > ${d}s)`
+			};
+			let p = a.length > 0 ? o.find((e) => e.startsWith(a))?.slice(a.length) : o.find((e) => !e.startsWith("t="));
+			if (!p) return {
+				ok: !1,
+				reason: "no signature in header"
+			};
+			let m = Buffer.concat([Buffer.from(`${l}.`, "utf8"), Buffer.from(t)]);
+			return u(s(e.algorithm, n, m, i), p) ? { ok: !0 } : {
+				ok: !1,
+				reason: "signature mismatch"
+			};
+		}
+		let o = a.length > 0 && r.startsWith(a) ? r.slice(a.length) : r;
+		return u(s(e.algorithm, n, t, i), o) ? { ok: !0 } : {
+			ok: !1,
+			reason: "signature mismatch"
+		};
+	}, c = o(n);
+	if (c.ok) return c;
+	if (e.previousSecret !== void 0) {
+		let t = o(e.previousSecret);
+		if (t.ok) return t;
+	}
+	return c;
+}, u = (e, n) => {
+	let r = Buffer.from(e, "utf8"), i = Buffer.from(n, "utf8");
+	return r.length === i.length ? t(r, i) : (t(r, Buffer.alloc(r.length)), !1);
+}, d = (e = "Stripe-Signature") => ({
+	_tag: "hmac",
+	algorithm: "hmacSha256",
+	header: e,
+	includeTimestamp: !0,
+	replayWindowSeconds: 300,
+	encoding: "hex",
+	versionPrefix: "v1="
+}), f = () => ({
+	_tag: "hmac",
+	algorithm: "hmacSha256",
+	header: "X-Hub-Signature-256",
+	includeTimestamp: !1,
+	encoding: "hex",
+	versionPrefix: "sha256="
+}), p = () => ({
+	_tag: "custom",
+	header: "X-Slack-Signature",
+	sign: (e, t) => `v0=${s("hmacSha256", t, `v0:${Math.floor(Date.now() / 1e3)}:${Buffer.from(e).toString("utf8")}`)}`,
+	verify: (e, t, n) => !1
+}), m = () => ({
+	_tag: "hmac",
+	algorithm: "hmacSha256",
+	header: "X-Webhook-Signature",
+	includeTimestamp: !0,
+	replayWindowSeconds: 300,
+	encoding: "hex",
+	versionPrefix: "v1="
+});
+//#endregion
+export { d as a, n as c, p as i, i as l, f as n, l as o, c as r, r as s, m as t, a as u };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@voltro/plugin-webhooks",
+  "version": "0.1.0",
+  "description": "Webhooks plugin — first-class outgoing (multi-target, durable-workflow delivery, HMAC signing, retry policies, rate limits) + incoming (signature verification, idempotency, provider templates for Stripe / GitHub / Slack / generic).",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./mixin": {
+      "types": "./dist/mixin.d.ts",
+      "import": "./dist/mixin.js",
+      "default": "./dist/mixin.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js",
+      "default": "./dist/providers/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@effect/workflow": "^0.18.2",
+    "@voltro/database": "0.1.0",
+    "@voltro/integration-http": "0.1.0",
+    "@voltro/logger": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}