@voltro/plugin-webhooks 0.85.0 → 0.87.0

package/dist/mixin.d.ts

@@ -32,7 +32,7 @@ export declare const _voltroWebhookDeliveriesTable: Table<"_voltro_webhook_deliv
     readonly eventId: ColumnBuilder<string | null, "text", boolean>;
     /** Attempt counter (1-indexed). */
     readonly attempt: ColumnBuilder<number, "integer", boolean>;
-    readonly status: ColumnBuilder<"failed" | "pending" | "succeeded" | "inFlight" | "retryScheduled", "text", boolean>;
+    readonly status: ColumnBuilder<"failed" | "succeeded" | "pending" | "inFlight" | "retryScheduled", "text", boolean>;
     /** Payload as sent over the wire. Stored verbatim — re-rendering
      *  from a referenced event row would lose the snapshot if the
      *  source event was deleted. */
@@ -171,6 +171,13 @@ export declare const _voltroWebhookTargetsTable: Table<"_voltro_webhook_targets"
      *  (a non-ciphertext value passes through); `voltro db encrypt-column
      *  _voltro_webhook_targets.secret` converts them in place. */
     readonly secret: ColumnBuilder<string, "text", boolean>;
+    /** During a rotation (`rotateSecret`): the secret the receiver may still
+     *  verify with. Every delivery until {@link previousSecretUntil} carries a
+     *  signature under it beside the new one (Standard Webhooks' signature list),
+     *  so the receiver switches when it is ready. Encrypted like `secret`. */
+    readonly previousSecret: ColumnBuilder<string | null, "text", boolean>;
+    /** When deliveries stop signing under `previousSecret`. */
+    readonly previousSecretUntil: ColumnBuilder<Date | null, "timestamp", boolean>;
     /** Serialised `SignatureScheme` discriminated union — see `signing.ts`.
      *  Stored as JSON so future schemes don't require a schema migration. */
     readonly signing: ColumnBuilder<unknown, "json", boolean>;
@@ -287,6 +294,13 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
      *  (a non-ciphertext value passes through); `voltro db encrypt-column
      *  _voltro_webhook_targets.secret` converts them in place. */
     readonly secret: ColumnBuilder<string, "text", boolean>;
+    /** During a rotation (`rotateSecret`): the secret the receiver may still
+     *  verify with. Every delivery until {@link previousSecretUntil} carries a
+     *  signature under it beside the new one (Standard Webhooks' signature list),
+     *  so the receiver switches when it is ready. Encrypted like `secret`. */
+    readonly previousSecret: ColumnBuilder<string | null, "text", boolean>;
+    /** When deliveries stop signing under `previousSecret`. */
+    readonly previousSecretUntil: ColumnBuilder<Date | null, "timestamp", boolean>;
     /** Serialised `SignatureScheme` discriminated union — see `signing.ts`.
      *  Stored as JSON so future schemes don't require a schema migration. */
     readonly signing: ColumnBuilder<unknown, "json", boolean>;
@@ -392,7 +406,7 @@ export declare const webhookTables: () => readonly [ Table<"_voltro_webhook_targ
     readonly eventId: ColumnBuilder<string | null, "text", boolean>;
     /** Attempt counter (1-indexed). */
     readonly attempt: ColumnBuilder<number, "integer", boolean>;
-    readonly status: ColumnBuilder<"failed" | "pending" | "succeeded" | "inFlight" | "retryScheduled", "text", boolean>;
+    readonly status: ColumnBuilder<"failed" | "succeeded" | "pending" | "inFlight" | "retryScheduled", "text", boolean>;
     /** Payload as sent over the wire. Stored verbatim — re-rendering
      *  from a referenced event row would lose the snapshot if the
      *  source event was deleted. */

package/dist/mixin.js

@@ -6,6 +6,8 @@ var u = o("_voltro_webhook_targets", {
 	event: s(),
 	url: s(),
 	secret: s().encrypted().serverOnly(),
+	previousSecret: s().encrypted().serverOnly().nullable(),
+	previousSecretUntil: c().nullable(),
 	signing: r(),
 	retry: r(),
 	scope: r().nullable(),

package/dist/plugin.js

@@ -0,0 +1,19 @@
+import { Effect as e } from "effect";
+import { definePlugin as t } from "@voltro/protocol";
+//#region src/plugin.ts
+var n = ["network:outbound:*"], r = [{
+	destination: "runtime:registered webhook targets (_voltro_webhook_targets)",
+	purpose: "event deliveries, HMAC-signed",
+	data: ["content", "metadata"],
+	disable: "remove or pause the targets; an emit then delivers nowhere"
+}], i = (i = {}) => t({
+	name: i.name ? `@voltro/plugin-webhooks#${i.name}` : "@voltro/plugin-webhooks",
+	description: "Outgoing webhooks (multi-target, durable-workflow delivery, HMAC signing, retry policies, rate limits) + incoming (signature verification, idempotency, provider templates). Declares wildcard outbound network access because targets are user-configured URLs.",
+	permissions: n,
+	egress: r,
+	onActivate: (t) => e.sync(() => {
+		t.logger.info("webhooks active", { outbound: "network:outbound:* (subscriber-configured target URLs — audit visibility, not a restriction)" });
+	})
+});
+//#endregion
+export { r as WEBHOOKS_EGRESS, n as WEBHOOKS_PLUGIN_PERMISSIONS, i as webhooksPlugin };

package/dist/providers/generic.js

@@ -0,0 +1,19 @@
+import { defineWebhookProvider as e } from "../dsl.js";
+import { genericHmacSignature as t } from "../signing.js";
+//#region src/providers/generic.ts
+var n = (n) => e({
+	id: "generic",
+	name: "Generic",
+	signature: {
+		...t(),
+		...n?.signatureHeader === void 0 ? {} : { header: n.signatureHeader },
+		...n?.replayWindowSeconds === void 0 ? {} : { replayWindowSeconds: n.replayWindowSeconds }
+	},
+	idempotency: {
+		from: "idempotency-key",
+		ttl: "7d"
+	},
+	bodyType: "json"
+});
+//#endregion
+export { n as genericProvider };

package/dist/providers/github.js

@@ -0,0 +1,16 @@
+import { defineWebhookProvider as e } from "../dsl.js";
+import { githubSignature as t } from "../signing.js";
+//#region src/providers/github.ts
+var n = () => e({
+	id: "github",
+	name: "GitHub",
+	signature: t(),
+	idempotency: {
+		from: "x-github-delivery",
+		ttl: "7d"
+	},
+	bodyType: "json",
+	eventTypeFrom: (e) => {}
+});
+//#endregion
+export { n as githubProvider };

package/dist/providers/index.js

@@ -1,86 +1,5 @@
-import { T as e, n as t, r as n, s as r } from "../signing-DeHObNv6.js";
-import { createHmac as i, timingSafeEqual as a } from "node:crypto";
-//#region src/providers/stripe.ts
-var o = (t) => e({
-	id: "stripe",
-	name: "Stripe",
-	signature: {
-		...r(),
-		...t?.replayWindowSeconds === void 0 ? {} : { replayWindowSeconds: t.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 = () => e({
-	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["x-slack-signature"], o = n["x-slack-request-timestamp"];
-		if (!r || !o || !/^\d+$/.test(o)) return !1;
-		let s = Math.floor(Date.now() / 1e3);
-		if (Math.abs(s - Number(o)) > 300) return !1;
-		let c = `v0:${o}:${new TextDecoder().decode(e)}`, l = `v0=${i("sha256", t).update(c).digest("hex")}`, u = Buffer.from(l, "utf8"), d = Buffer.from(r, "utf8");
-		return u.length === d.length ? a(u, d) : (a(u, Buffer.alloc(u.length)), !1);
-	}
-}), l = () => e({
-	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 = (n) => e({
-	id: "generic",
-	name: "Generic",
-	signature: {
-		...t(),
-		...n?.signatureHeader === void 0 ? {} : { header: n.signatureHeader },
-		...n?.replayWindowSeconds === void 0 ? {} : { replayWindowSeconds: n.replayWindowSeconds }
-	},
-	idempotency: {
-		from: "idempotency-key",
-		ttl: "7d"
-	},
-	bodyType: "json"
-});
-//#endregion
-export { u as genericProvider, s as githubProvider, l as slackProvider, o as stripeProvider };
+import { stripeProvider as e } from "./stripe.js";
+import { githubProvider as t } from "./github.js";
+import { slackProvider as n } from "./slack.js";
+import { genericProvider as r } from "./generic.js";
+export { r as genericProvider, t as githubProvider, n as slackProvider, e as stripeProvider };

package/dist/providers/slack.js

@@ -0,0 +1,39 @@
+import { defineWebhookProvider as e } from "../dsl.js";
+import { createHmac as t, timingSafeEqual as n } from "node:crypto";
+//#region src/providers/slack.ts
+var r = () => ({
+	_tag: "custom",
+	header: "X-Slack-Signature",
+	sign: (e, n) => {
+		let r = `v0:${Math.floor(Date.now() / 1e3)}:${new TextDecoder().decode(e)}`;
+		return `v0=${t("sha256", n).update(r).digest("hex")}`;
+	},
+	verify: (e, r, i) => {
+		let a = i["x-slack-signature"], o = i["x-slack-request-timestamp"];
+		if (!a || !o || !/^\d+$/.test(o)) return !1;
+		let s = Math.floor(Date.now() / 1e3);
+		if (Math.abs(s - Number(o)) > 300) return !1;
+		let c = `v0:${o}:${new TextDecoder().decode(e)}`, l = `v0=${t("sha256", r).update(c).digest("hex")}`, u = Buffer.from(l, "utf8"), d = Buffer.from(a, "utf8");
+		return u.length === d.length ? n(u, d) : (n(u, Buffer.alloc(u.length)), !1);
+	}
+}), i = () => e({
+	id: "slack",
+	name: "Slack",
+	signature: r(),
+	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;
+			}
+		}
+	}
+});
+//#endregion
+export { i as slackProvider };

package/dist/providers/stripe.js

@@ -0,0 +1,30 @@
+import { defineWebhookProvider as e } from "../dsl.js";
+import { stripeSignature as t } from "../signing.js";
+//#region src/providers/stripe.ts
+var n = (n) => e({
+	id: "stripe",
+	name: "Stripe",
+	signature: {
+		...t(),
+		...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;
+		}
+	}
+});
+//#endregion
+export { n as stripeProvider };

package/dist/rateLimit.js

@@ -0,0 +1,61 @@
+import { and as e, eq as t } from "@voltro/database";
+//#region src/rateLimit.ts
+var n = "_voltro_webhook_rate_windows", r = 6e4, i = (e, t) => `${e}@${t}`, a = async (n, r, i) => (await n.query({
+	table: "_voltro_webhook_rate_windows",
+	predicate: e(t("scope", r), t("bucket", i)),
+	order: [],
+	take: 1,
+	skip: void 0,
+	projection: void 0
+}))[0] ?? null, o = 32, s = async (r, s, c) => {
+	for (let l = 0; l < o; l++) {
+		l > 0 && await new Promise((e) => setTimeout(e, l));
+		let o = await a(r, s.key, c);
+		if (o === null) await r.insertIgnore(n, {
+			id: i(s.key, c),
+			scope: s.key,
+			bucket: c,
+			count: 0,
+			createdAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		}, { conflictColumns: ["id"] });
+		else {
+			if (o.count >= s.limit) return !1;
+			if (await r.updateMany("_voltro_webhook_rate_windows", {
+				count: o.count + 1,
+				updatedAt: /* @__PURE__ */ new Date()
+			}, { where: e(t("id", o.id), t("count", o.count)) }) === 1) return !0;
+		}
+	}
+	throw Error(`webhook rate window: contention on (${s.key}, ${c}) exceeded ${o} attempts`);
+}, c = async (n, r, i) => {
+	for (let s = 0; s < o; s++) {
+		s > 0 && await new Promise((e) => setTimeout(e, s));
+		let o = await a(n, r, i);
+		if (o === null || o.count <= 0 || await n.updateMany("_voltro_webhook_rate_windows", {
+			count: o.count - 1,
+			updatedAt: /* @__PURE__ */ new Date()
+		}, { where: e(t("id", o.id), t("count", o.count)) }) === 1) return;
+	}
+	throw Error(`webhook rate window: release contention on (${r}) exceeded ${o} attempts`);
+}, l = async (e, t, n, i = r) => {
+	if (t.length === 0) return {
+		acquired: !0,
+		retryInMs: 0
+	};
+	let a = Math.floor(n / i), o = [];
+	for (let r of t) if (await s(e, r, a)) o.push(r);
+	else {
+		for (let t of o) await c(e, t.key, a);
+		return {
+			acquired: !1,
+			retryInMs: (a + 1) * i - n
+		};
+	}
+	return {
+		acquired: !0,
+		retryInMs: 0
+	};
+};
+//#endregion
+export { r as RATE_WINDOW_MS, n as RATE_WINDOW_TABLE, l as acquireRateSlots, s as consumeRateSlot, c as releaseRateSlot };

package/dist/retry.js

@@ -0,0 +1,65 @@
+//#region src/retry.ts
+var e = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/, t = (t) => {
+	let n = e.exec(t);
+	if (!n) throw Error(`invalid duration literal: ${t}`);
+	let r = Number(n[1]), i = n[2] ?? "s";
+	switch (i) {
+		case "ms": return r;
+		case "s": return r * 1e3;
+		case "m": return r * 6e4;
+		case "h": return r * 36e5;
+		case "d": return r * 864e5;
+		default: throw Error(`unreachable unit: ${i}`);
+	}
+}, n = [
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+], r = (e, r, i) => {
+	if (r >= e.maxAttempts || i?.status !== void 0 && !(e.retryOn ?? n).includes(i.status)) return null;
+	if (e.honourRetryAfter !== !1 && i?.retryAfterSeconds !== void 0) {
+		let n = i.retryAfterSeconds * 1e3, r = t(e.maxDelay), a = Math.min(n, r);
+		return {
+			delayMs: a,
+			baseDelayMs: a
+		};
+	}
+	let a = t(e.initialDelay), o = t(e.maxDelay), s;
+	switch (e.strategy) {
+		case "fixed":
+			s = a;
+			break;
+		case "linear":
+			s = a * r;
+			break;
+		case "exponential": s = a * 2 ** (r - 1);
+	}
+	s = Math.min(s, o);
+	let c = s;
+	return e.jitter === "full" && (c = Math.random() * s), {
+		delayMs: Math.max(1, Math.floor(c)),
+		baseDelayMs: s
+	};
+}, i = () => ({
+	strategy: "exponential",
+	maxAttempts: 8,
+	initialDelay: "5s",
+	maxDelay: "1h",
+	retryOn: n,
+	honourRetryAfter: !0,
+	jitter: "full"
+}), a = () => ({
+	strategy: "fixed",
+	maxAttempts: 120,
+	initialDelay: "30s",
+	maxDelay: "30s",
+	retryOn: n,
+	honourRetryAfter: !0,
+	jitter: "full"
+});
+//#endregion
+export { i as defaultRetryPolicy, a as fastRetryPolicy, r as nextRetry, t as parseDuration };