@samva/webhooks 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/webhooks",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Runtime-neutral verification for Samva webhook deliveries",
   "keywords": [
     "samva",
@@ -46,6 +46,10 @@
     "./protocol": {
       "types": "./dist/protocol.d.ts",
       "import": "./dist/protocol.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.gen.d.ts",
+      "import": "./dist/schemas.gen.js"
     }
   },
   "publishConfig": {
@@ -54,11 +58,17 @@
   "scripts": {
     "build": "tsdown && tsc --project tsconfig.build.json",
     "prepack": "bun run build",
-    "test": "vitest run --root ../.. --project packages packages/webhooks/tests",
-    "typecheck": "tsc --noEmit"
+    "test": "bun run test:generation && vitest run --root ../.. --project packages packages/webhooks/tests",
+    "typecheck": "tsc --noEmit",
+    "generate": "bun run scripts/generate.ts",
+    "test:generation": "bun run scripts/generate.ts --check",
+    "test:bundle": "bun run build && bun run scripts/check-bundle.ts"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0",
+    "@samva/core": "0.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "effect": "4.0.0",
     "tsdown": "^0.22.13",
     "typescript": "^7.0.2",

package/dist/protocol-BGKUmvlI.js

@@ -1,333 +0,0 @@
-//#region src/errors.ts
-/**
-* Base class for every failure this package reports while verifying a webhook delivery.
-*
-* Each subclass carries a literal `_tag` (also used as `name`), so you can branch on the failure
-* with a `switch` or Effect's `catchTag`. `detail` is a human-readable reason for your logs; do not
-* echo it to the sender, and do not match on its wording.
-*/
-var WebhookVerificationError = class extends Error {
-	/** Discriminant naming the concrete failure; equal to the subclass name. */
-	_tag;
-	/** Human-readable reason for logs. The wording is not a stable contract. */
-	detail;
-	constructor(tag, options) {
-		super(options.detail);
-		this.name = tag;
-		this._tag = tag;
-		this.detail = options.detail;
-	}
-};
-/**
-* The signing secret is unusable: it lacks the `whsec_` prefix, the remainder is not Base64, or
-* the decoded key length is outside the accepted range (`detail` names the range). This is a
-* configuration error on the receiving side, not a bad delivery; copy the endpoint's signing
-* secret from Samva again.
-*/
-var InvalidWebhookSecretError = class extends WebhookVerificationError {
-	constructor(options) {
-		super("InvalidWebhookSecretError", options);
-	}
-};
-/**
-* One of the `webhook-id`, `webhook-timestamp`, or `webhook-signature` headers is missing or
-* empty; `header` names it. The request is not a Samva delivery, or something between Samva and
-* your handler stripped the headers.
-*/
-var InvalidWebhookHeadersError = class extends WebhookVerificationError {
-	/** The first signing header, in id, timestamp, signature order, that is missing or empty. */
-	header;
-	constructor(options) {
-		super("InvalidWebhookHeadersError", options);
-		this.header = options.header;
-	}
-};
-/**
-* The `webhook-timestamp` header is not an integer count of Unix seconds, it lies further from the
-* current time than the replay tolerance, or the tolerance you passed is negative or not finite.
-* A delivery outside the tolerance is rejected even when its signature is valid; that bounds how
-* long a captured request can be replayed. Repeated failures on genuine deliveries usually mean
-* the receiving server's clock is wrong.
-*/
-var WebhookTimestampError = class extends WebhookVerificationError {
-	constructor(options) {
-		super("WebhookTimestampError", options);
-	}
-};
-/**
-* No signature in the `webhook-signature` header matches the delivery, or no verification key was
-* supplied. Treat the request as forged and reject it. When genuine deliveries fail, the usual
-* causes are the wrong endpoint secret or a body that was parsed and re-serialized before
-* verification instead of passed through as the exact bytes received.
-*/
-var WebhookSignatureError = class extends WebhookVerificationError {
-	constructor(options) {
-		super("WebhookSignatureError", options);
-	}
-};
-/**
-* The signature is valid, but the body is not UTF-8 JSON holding exactly the `type`,
-* `timestamp`, and `data` fields of a Samva event envelope.
-*/
-var MalformedWebhookPayloadError = class extends WebhookVerificationError {
-	constructor(options) {
-		super("MalformedWebhookPayloadError", options);
-	}
-};
-/**
-* The runtime's Web Crypto implementation could not import a key or compute a signature, none of
-* the supplied public keys could be imported, or the Effect entrypoint could not read the request
-* body. Points at the runtime or its configuration rather than at the delivery.
-*/
-var WebhookCryptoError = class extends WebhookVerificationError {
-	constructor(options) {
-		super("WebhookCryptoError", options);
-	}
-};
-//#endregion
-//#region src/protocol.ts
-/**
-* Header carrying the delivery's unique message ID. Retries of the same delivery reuse it, so it
-* is the key for deduplicating deliveries you have already handled.
-*/
-const WEBHOOK_ID_HEADER = "webhook-id";
-/** Header carrying the time Samva signed the delivery, as integer Unix seconds. */
-const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
-/**
-* Header carrying one or more space-separated `<version>,<base64 signature>` entries. More than one
-* entry appears while a signing secret is being rotated; a delivery verifies when any entry of the
-* expected version matches.
-*/
-const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
-/**
-* Replay tolerance, in seconds, used when a caller passes no `toleranceSeconds`. A delivery whose
-* `webhook-timestamp` differs from the current time by more than this, in either direction, is
-* rejected with {@link WebhookTimestampError}.
-*/
-const DEFAULT_TOLERANCE_SECONDS = 300;
-const SECRET_PREFIX = "whsec_";
-const ASYMMETRIC_ALGORITHM = {
-	name: "RSASSA-PKCS1-v1_5",
-	hash: "SHA-256"
-};
-const MINIMUM_SECRET_BYTES = 24;
-const MAXIMUM_SECRET_BYTES = 64;
-const GENERATED_SECRET_BYTES = 32;
-const encoder = new TextEncoder();
-const toBytes = (body) => typeof body === "string" ? encoder.encode(body) : body;
-const toCryptoBytes = (bytes) => new Uint8Array(bytes);
-const bytesToBase64 = (bytes) => {
-	let binary = "";
-	for (const byte of bytes) binary += String.fromCharCode(byte);
-	return btoa(binary);
-};
-const base64ToBytes = (encoded) => {
-	const binary = atob(encoded);
-	return Uint8Array.from(binary, (character) => character.charCodeAt(0));
-};
-const decodeSecret = (secret) => {
-	if (!secret.startsWith(SECRET_PREFIX)) throw new InvalidWebhookSecretError({ detail: "Webhook secret must start with whsec_" });
-	const decoded = (() => {
-		try {
-			return base64ToBytes(secret.slice(6));
-		} catch {
-			throw new InvalidWebhookSecretError({ detail: "Webhook secret is not valid Base64" });
-		}
-	})();
-	if (decoded.byteLength < MINIMUM_SECRET_BYTES || decoded.byteLength > MAXIMUM_SECRET_BYTES) throw new InvalidWebhookSecretError({ detail: `Webhook secret must decode to ${MINIMUM_SECRET_BYTES}-${MAXIMUM_SECRET_BYTES} bytes` });
-	return decoded;
-};
-const importHmacKey = async (secret) => {
-	const secretBytes = decodeSecret(secret);
-	try {
-		return await crypto.subtle.importKey("raw", toCryptoBytes(secretBytes), {
-			name: "HMAC",
-			hash: "SHA-256"
-		}, false, ["sign"]);
-	} catch (cause) {
-		throw new WebhookCryptoError({ detail: `Unable to import webhook signing key: ${cause instanceof Error ? cause.message : String(cause)}` });
-	}
-};
-const importVerificationKey = async (publicKey) => {
-	try {
-		return await crypto.subtle.importKey("spki", toCryptoBytes(base64ToBytes(publicKey.trim())), ASYMMETRIC_ALGORITHM, false, ["verify"]);
-	} catch {
-		return;
-	}
-};
-const signedBytes = (id, timestamp, body) => {
-	const prefix = encoder.encode(`${id}.${timestamp}.`);
-	const material = new Uint8Array(prefix.byteLength + body.byteLength);
-	material.set(prefix);
-	material.set(body, prefix.byteLength);
-	return material;
-};
-const hmac = async (secret, id, timestamp, body) => {
-	const key = await importHmacKey(secret);
-	try {
-		return new Uint8Array(await crypto.subtle.sign("HMAC", key, toCryptoBytes(signedBytes(id, timestamp, body))));
-	} catch (cause) {
-		throw new WebhookCryptoError({ detail: `Unable to sign webhook: ${cause instanceof Error ? cause.message : String(cause)}` });
-	}
-};
-const asymmetricMatch = async (key, candidate, content) => {
-	try {
-		return await crypto.subtle.verify(ASYMMETRIC_ALGORITHM, key, toCryptoBytes(candidate), content);
-	} catch {
-		return false;
-	}
-};
-const timingSafeEqual = (left, right) => {
-	if (left.byteLength !== right.byteLength) return false;
-	let difference = 0;
-	for (let index = 0; index < left.byteLength; index += 1) difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
-	return difference === 0;
-};
-const signatureCandidates = (header, expected) => header.split(" ").map((candidate) => candidate.split(",", 2)).flatMap(([version, encoded]) => {
-	if (version !== expected || encoded === void 0) return [];
-	try {
-		return [base64ToBytes(encoded)];
-	} catch {
-		return [];
-	}
-});
-const parseEvent = (body) => {
-	try {
-		const parsed = JSON.parse(new TextDecoder("utf-8", {
-			fatal: true,
-			ignoreBOM: false
-		}).decode(body));
-		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new MalformedWebhookPayloadError({ detail: "Webhook event must be an object" });
-		const event = parsed;
-		const keys = Object.keys(event);
-		if (keys.length !== 3 || !keys.every((key) => key === "type" || key === "timestamp" || key === "data") || typeof event.type !== "string" || typeof event.timestamp !== "string" || !("data" in event)) throw new MalformedWebhookPayloadError({ detail: "Webhook event has an invalid envelope" });
-		return {
-			type: event.type,
-			timestamp: event.timestamp,
-			data: event.data
-		};
-	} catch {
-		throw new MalformedWebhookPayloadError({ detail: "Webhook body must be valid UTF-8 JSON containing type, timestamp, and data" });
-	}
-};
-/**
-* Creates a random `whsec_`-prefixed signing secret from the runtime's secure random source.
-* Samva issues each endpoint's secret for you; use this to sign test deliveries with
-* {@link signWebhook}.
-*/
-const generateWebhookSecret = () => {
-	const bytes = crypto.getRandomValues(new Uint8Array(GENERATED_SECRET_BYTES));
-	return `${SECRET_PREFIX}${bytesToBase64(bytes)}`;
-};
-/**
-* Builds the bytes every signature version covers: `<id>.<timestamp>.<body>`. Use it to verify a
-* signature with your own crypto code; {@link verifyWebhookAt} and
-* {@link verifyWebhookAtWithPublicKeys} build it for you.
-*/
-const webhookSignedContent = (input) => signedBytes(input.id, input.timestamp, toBytes(input.body));
-/** Formats raw signature bytes as one `<version>,<base64>` entry of the `webhook-signature` header. */
-const encodeWebhookSignature = (version, signature) => `${version},${bytesToBase64(signature)}`;
-/**
-* Computes the `v1` HMAC-SHA256 signature Samva sends, formatted as one `webhook-signature`
-* entry. Use it to produce signed test deliveries for your handler.
-*
-* `timestamp` is Unix seconds; a number is stringified, and the verifier requires an integer.
-* Rejects with {@link InvalidWebhookSecretError} for an unusable secret and
-* {@link WebhookCryptoError} when Web Crypto fails.
-*/
-const signWebhook = async (input) => {
-	const timestamp = String(input.timestamp);
-	const signature = await hmac(input.secret, input.id, timestamp, toBytes(input.body));
-	return encodeWebhookSignature("v1", signature);
-};
-const requireHeader = (header, value) => {
-	if (value === null || value === void 0) throw new InvalidWebhookHeadersError({
-		header,
-		detail: `${header} header is missing`
-	});
-	if (value.length === 0) throw new InvalidWebhookHeadersError({
-		header,
-		detail: `${header} header is empty`
-	});
-	return value;
-};
-const requireHeaders = (values) => ({
-	id: requireHeader(WEBHOOK_ID_HEADER, values.id),
-	timestamp: requireHeader(WEBHOOK_TIMESTAMP_HEADER, values.timestamp),
-	signature: requireHeader(WEBHOOK_SIGNATURE_HEADER, values.signature)
-});
-const freshHeaders = (input) => {
-	const { id, timestamp, signature } = requireHeaders(input.headers);
-	const timestampSeconds = Number(timestamp);
-	if (!Number.isInteger(timestampSeconds)) throw new WebhookTimestampError({ detail: "webhook-timestamp must be Unix seconds" });
-	const toleranceSeconds = input.toleranceSeconds ?? 300;
-	if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) throw new WebhookTimestampError({ detail: "Webhook tolerance must be non-negative" });
-	if (Math.abs(input.nowMilliseconds / 1e3 - timestampSeconds) > toleranceSeconds) throw new WebhookTimestampError({ detail: "Webhook timestamp is outside the replay tolerance" });
-	return {
-		id,
-		timestamp,
-		signature
-	};
-};
-/**
-* Verifies a `v1` (HMAC-SHA256) delivery against an explicit current time. The `verify` and
-* `verifyRequest` entry points call this with the current clock; call it directly when your
-* framework owns the clock or a test needs a fixed time.
-*
-* Checks, in order: all three headers are present and non-empty; the timestamp is integer Unix seconds within
-* `toleranceSeconds` of `nowMilliseconds`; some `v1` entry in the signature header matches, using
-* a constant-time comparison; the body is a Samva event envelope. The replay window rejects stale
-* deliveries but does not detect a repeat inside it; deduplicate on the returned `id`.
-*
-* Rejects with {@link InvalidWebhookHeadersError}, {@link WebhookTimestampError},
-* {@link InvalidWebhookSecretError}, {@link WebhookSignatureError},
-* {@link MalformedWebhookPayloadError}, or {@link WebhookCryptoError}.
-*/
-const verifyWebhookAt = async (input) => {
-	const { id, timestamp, signature } = freshHeaders(input);
-	const body = toBytes(input.body);
-	const expected = await hmac(input.secret, id, timestamp, body);
-	if (!signatureCandidates(signature, "v1").some((candidate) => timingSafeEqual(expected, candidate))) throw new WebhookSignatureError({ detail: "Webhook signature verification failed" });
-	return {
-		id,
-		event: parseEvent(body)
-	};
-};
-/**
-* Verifies a `v2` (RSASSA-PKCS1-v1_5, SHA-256) delivery against one or more public keys, each a
-* Base64-encoded SPKI DER key. Pass several keys during a key rotation; the delivery verifies when
-* any `v2` signature entry matches any key.
-*
-* Header, timestamp, and envelope checks match {@link verifyWebhookAt}. Keys that fail to import
-* are skipped. Rejects with {@link WebhookSignatureError} when `publicKeys` is empty or nothing
-* matches, and {@link WebhookCryptoError} when none of the keys imports.
-*/
-const verifyWebhookAtWithPublicKeys = async (input) => {
-	const { id, timestamp, signature } = freshHeaders(input);
-	if (input.publicKeys.length === 0) throw new WebhookSignatureError({ detail: "No webhook verification key is available" });
-	const keys = (await Promise.all(input.publicKeys.map(importVerificationKey))).filter((key) => key !== void 0);
-	if (keys.length === 0) throw new WebhookCryptoError({ detail: "Unable to import any webhook verification key: keys must be Base64 SPKI DER" });
-	const body = toBytes(input.body);
-	const content = toCryptoBytes(signedBytes(id, timestamp, body));
-	const candidates = signatureCandidates(signature, "v2");
-	if (!(await Promise.all(keys.flatMap((key) => candidates.map((candidate) => asymmetricMatch(key, candidate, content))))).includes(true)) throw new WebhookSignatureError({ detail: "Webhook signature verification failed" });
-	return {
-		id,
-		event: parseEvent(body)
-	};
-};
-/**
-* Reads the three signing headers from a Fetch API `Headers` object, for code that needs a header
-* value, such as the timestamp, before or beside verification. Throws
-* {@link InvalidWebhookHeadersError}, naming the header, when one is missing or empty; call it
-* inside the same error handling as the verification that follows.
-*/
-const readWebhookHeaders = (headers) => requireHeaders({
-	id: headers.get(WEBHOOK_ID_HEADER),
-	timestamp: headers.get(WEBHOOK_TIMESTAMP_HEADER),
-	signature: headers.get(WEBHOOK_SIGNATURE_HEADER)
-});
-//#endregion
-export { WebhookTimestampError as _, encodeWebhookSignature as a, signWebhook as c, webhookSignedContent as d, InvalidWebhookHeadersError as f, WebhookSignatureError as g, WebhookCryptoError as h, WEBHOOK_TIMESTAMP_HEADER as i, verifyWebhookAt as l, MalformedWebhookPayloadError as m, WEBHOOK_ID_HEADER as n, generateWebhookSecret as o, InvalidWebhookSecretError as p, WEBHOOK_SIGNATURE_HEADER as r, readWebhookHeaders as s, DEFAULT_TOLERANCE_SECONDS as t, verifyWebhookAtWithPublicKeys as u, WebhookVerificationError as v };
-
-//# sourceMappingURL=protocol-BGKUmvlI.js.map