@voltro/plugin-webhooks 0.85.0 → 0.87.0

package/dist/incoming.js

@@ -0,0 +1,205 @@
+import { verifyRequest as e } from "./signing.js";
+import { getIdempotencyCache as t, parseTtl as n } from "./idempotency.js";
+import { Schema as r } from "effect";
+import { publishServerError as i } from "@voltro/protocol";
+import { createLogger as a } from "@voltro/logger";
+//#region src/incoming.ts
+var o = (e, t) => ({
+	status: e,
+	contentType: "application/json; charset=utf-8",
+	body: JSON.stringify(t)
+}), s = "voltroWebhookVerification", c = class extends Error {
+	webhookId;
+	name = "UnverifiedIncomingWebhook";
+	constructor(e) {
+		super(`incoming webhook '${e}' declares no verification. It would be mounted as a public, unauthenticated POST that runs your application code, so the framework refuses to mount it. Pick one on the descriptor:\n  · provider: stripeWebhookProvider()   — a preset (HMAC scheme + idempotency + body type)\n  · signature: { _tag: 'hmac', algorithm: 'hmacSha256', header: 'X-Signature', encoding: 'hex', includeTimestamp: true }\n  · verification: 'provider'            — the handler verifies with the provider's own SDK\n  · verification: 'none'                — deliberately public; a gateway / IP allow-list owns it\nA signature-verified webhook reads its shared secret from VOLTRO_WEBHOOK_SECRET_${e.toUpperCase().replace(/[^A-Z0-9]/g, "_")}. The framework never invents that value — the sender holds the other half of it.`), this.webhookId = e;
+	}
+}, l = (e) => `VOLTRO_WEBHOOK_SECRET_${e.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`, u = (e) => {
+	let t = e.signature ?? e.provider?.signature ?? null;
+	return (e.verification === void 0 || e.verification === "signature") && t === null ? null : e.verification ?? "signature";
+}, d = (d, f) => {
+	let p = d.provider, m = d.signature ?? p?.signature ?? null, h = d.idempotency ?? p?.idempotency ?? null, g = d.bodyType ?? p?.bodyType ?? "json", _ = u(d);
+	if (_ === null) throw new c(d.id);
+	let v = _;
+	v === "none" && a({ scope: `webhook:${d.id}` }).warn("incoming webhook mounted WITHOUT verification — anyone who can reach this URL can run its handler", {
+		webhookId: d.id,
+		verification: "none"
+	});
+	let y = f.idempotencyCache ?? t(), b = n(h?.ttl), x = f.log ?? ((e) => {
+		a({ scope: `webhook:${e.webhookId}` }).debug("incoming webhook", {
+			status: e.status,
+			signatureOk: e.signatureOk,
+			idempotency: e.idempotency,
+			durationMs: e.durationMs,
+			...e.errorMessage === void 0 ? {} : { errorMessage: e.errorMessage }
+		});
+	});
+	return Object.assign(async (t) => {
+		let n = Date.now();
+		if (t.method !== "POST") {
+			let e = o(405, {
+				error: "method not allowed",
+				expected: "POST"
+			});
+			return x({
+				webhookId: d.id,
+				status: 405,
+				signatureOk: "skipped",
+				idempotency: "skipped",
+				durationMs: Date.now() - n
+			}), e;
+		}
+		let a = "skipped";
+		if (m !== null && v === "signature") {
+			let r = await f.resolveSecret(d.id);
+			if (r === null) {
+				let e = `no signing secret configured — set ${l(d.id)}`, t = o(503, {
+					error: "webhook not configured",
+					reason: e
+				});
+				return x({
+					webhookId: d.id,
+					status: 503,
+					signatureOk: !1,
+					idempotency: "skipped",
+					durationMs: Date.now() - n,
+					errorMessage: e
+				}), t;
+			}
+			{
+				let i = e(m, {
+					rawBody: t.rawBody,
+					secret: r,
+					headers: t.headers
+				});
+				if (a = i.ok, !i.ok) {
+					let e = o(401, {
+						error: "invalid signature",
+						reason: i.reason
+					});
+					return x({
+						webhookId: d.id,
+						status: 401,
+						signatureOk: !1,
+						idempotency: "skipped",
+						durationMs: Date.now() - n,
+						errorMessage: i.reason
+					}), e;
+				}
+			}
+		}
+		let s;
+		try {
+			if (g === "json") {
+				let e = new TextDecoder().decode(t.rawBody);
+				s = e.length === 0 ? null : JSON.parse(e);
+			} else if (g === "form") {
+				let e = new TextDecoder().decode(t.rawBody), n = new URLSearchParams(e), r = {};
+				for (let [e, t] of n.entries()) r[e] = t;
+				s = r;
+			} else s = t.rawBody;
+		} catch (e) {
+			let t = o(400, {
+				error: "malformed body",
+				reason: e.message
+			});
+			return x({
+				webhookId: d.id,
+				status: 400,
+				signatureOk: a,
+				idempotency: "skipped",
+				durationMs: Date.now() - n,
+				errorMessage: e.message
+			}), t;
+		}
+		let c;
+		try {
+			c = r.decodeUnknownSync(d.payload)(s);
+		} catch (e) {
+			let t = o(422, {
+				error: "schema validation failed",
+				reason: e.message
+			});
+			return x({
+				webhookId: d.id,
+				status: 422,
+				signatureOk: a,
+				idempotency: "skipped",
+				durationMs: Date.now() - n,
+				errorMessage: e.message
+			}), t;
+		}
+		let u, p = "skipped";
+		if (h !== null) {
+			let e = h.from;
+			if (u = typeof e == "string" ? t.headers[e.toLowerCase()] : e(t.headers, t.rawBody), u !== void 0 && u.length > 0) {
+				let e = y.claim(u, b);
+				if (p = e, e === "duplicate") {
+					let e = o(200, {
+						received: !0,
+						duplicate: !0
+					});
+					return x({
+						webhookId: d.id,
+						status: 200,
+						signatureOk: a,
+						idempotency: "duplicate",
+						durationMs: Date.now() - n
+					}), e;
+				}
+				if (e === "inflight") {
+					let e = o(409, {
+						error: "request already in flight",
+						idempotencyKey: u
+					});
+					return x({
+						webhookId: d.id,
+						status: 409,
+						signatureOk: a,
+						idempotency: "inflight",
+						durationMs: Date.now() - n
+					}), e;
+				}
+			}
+		}
+		try {
+			let e = f.resolveWorkflows?.();
+			await d.handler({
+				body: c,
+				rawBody: t.rawBody,
+				headers: t.headers,
+				idempotencyKey: u ?? "",
+				...e ? { workflows: e } : {}
+			}), u !== void 0 && y.commit(u);
+			let r = o(200, { received: !0 });
+			return x({
+				webhookId: d.id,
+				status: 200,
+				signatureOk: a,
+				idempotency: p,
+				durationMs: Date.now() - n
+			}), r;
+		} catch (e) {
+			u !== void 0 && y.release(u);
+			let t = o(500, {
+				error: "handler threw",
+				reason: e.message
+			});
+			return x({
+				webhookId: d.id,
+				status: 500,
+				signatureOk: a,
+				idempotency: p,
+				durationMs: Date.now() - n,
+				errorMessage: e.message
+			}), i({
+				error: e,
+				source: "webhook",
+				name: d.id,
+				fields: { status: 500 }
+			}), t;
+		}
+	}, { [s]: v });
+}, f = (e) => `/webhooks/${e}`;
+//#endregion
+export { c as UnverifiedIncomingWebhook, s as WEBHOOK_VERIFICATION_PROPERTY, f as defaultIncomingPath, u as incomingWebhookVerification, d as mountIncomingWebhook };

package/dist/index.d.ts

@@ -617,6 +617,9 @@ emitter: () => Pick<WebhooksServiceShape, "emit"> | undefined) => OutboxHandlerD
  */
 export declare const matchesFilter: (filter: WebhookFilter | Readonly<Record<string, unknown>> | null, payload: unknown) => boolean;
 
+/** The longest overlap `rotateSecret` accepts, and its default: 30 days, unless ended earlier. */
+export declare const MAX_SECRET_OVERLAP_SECONDS: number;
+
 /** A mounted handler, carrying its verification declaration. */
 export declare type MountedIncomingWebhook = ((request: IncomingRequest) => Promise<IncomingResponse>) & {
     readonly [WEBHOOK_VERIFICATION_PROPERTY]: IncomingWebhookVerification;
@@ -822,6 +825,28 @@ export declare interface RetryPolicy {
 
 export declare type RetryStrategy = 'fixed' | 'linear' | 'exponential';
 
+/** What `rotateSecret` returns. */
+export declare interface RotatedSecret {
+    /** The new secret — returned once; hand it to the receiver. */
+    readonly secret: string;
+    /** Until when deliveries are signed under the previous secret too. `null`:
+     *  no overlap — asked for none, or a scheme with one signature per message. */
+    readonly previousSignedUntil: Date | null;
+}
+
+/** How long a rotated webhook secret keeps signing beside the new one. */
+export declare interface RotateSecretOptions {
+    /**
+     * Seconds every delivery still carries a signature under the previous
+     * secret, so the receiver can switch when it is ready. The length is the
+     * RECEIVER's switch-over time — nothing on the sending side can measure it —
+     * so by default the overlap lasts until {@link WebhooksServiceShape.endSecretOverlap}
+     * ends it (once the receiver has switched), and at most 30 days. Pass a
+     * number to bound it yourself; `0` switches at once (after a leak).
+     */
+    readonly overlapSeconds?: number;
+}
+
 export declare type SignatureScheme = HmacSignatureScheme | CustomSignatureScheme | StandardWebhooksSignatureScheme;
 
 export declare interface SignedRequest {
@@ -1250,7 +1275,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. */
@@ -1389,6 +1414,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>;
@@ -1702,8 +1734,11 @@ export declare interface WebhooksServiceShape {
      * must sign identically, and the previous way to achieve it was delete +
      * re-subscribe, minting new ids and orphaning the delivery history.
      */
-    readonly rotateSecret: (target: TargetSelector) => Promise<{
-        readonly secret: string;
+    readonly rotateSecret: (target: TargetSelector, options?: RotateSecretOptions) => Promise<RotatedSecret>;
+    /** End a rotation's overlap once the receiver verifies with the new secret: the
+     *  previous secret stops signing at once. Returns how many targets were overlapping. */
+    readonly endSecretOverlap: (target: TargetSelector) => Promise<{
+        readonly ended: number;
     }>;
     /** Re-pin a target's `payloadVersion` to the event's current
      *  version. Called from the dashboard's "Re-pin" action after
@@ -1805,6 +1840,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>;
@@ -1910,7 +1952,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. */