@amirabaris/webhook-kit 0.0.0-stage → 0.1.1

package/dist/index.cjs

@@ -0,0 +1,1774 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/errors.ts
+/**
+* Base error class for all webhook-kit errors.
+*/
+var WebhookKitError = class extends Error {
+	code;
+	constructor(message, code = "WEBHOOK_KIT_ERROR") {
+		super(message);
+		this.name = "WebhookKitError";
+		this.code = code;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
+* Thrown or returned when signature verification fails (e.g. invalid HMAC or mismatched hash).
+*/
+var SignatureVerificationError = class extends WebhookKitError {
+	constructor(message = "Signature verification failed: signature does not match expected HMAC") {
+		super(message, "SIGNATURE_VERIFICATION_FAILED");
+		this.name = "SignatureVerificationError";
+	}
+};
+/**
+* Thrown when the signature header is missing or malformed.
+*/
+var InvalidSignatureHeaderError = class extends WebhookKitError {
+	constructor(message = "Invalid or missing signature header") {
+		super(message, "INVALID_SIGNATURE_HEADER");
+		this.name = "InvalidSignatureHeaderError";
+	}
+};
+/**
+* Thrown when the timestamp outside the allowed tolerance window (replay attack protection).
+*/
+var TimestampToleranceError = class extends WebhookKitError {
+	timestamp;
+	toleranceSeconds;
+	constructor(timestamp, toleranceSeconds, message) {
+		super(message ?? `Timestamp outside tolerance window (timestamp: ${timestamp}, tolerance: ${toleranceSeconds}s)`, "TIMESTAMP_TOLERANCE_EXCEEDED");
+		this.name = "TimestampToleranceError";
+		this.timestamp = timestamp;
+		this.toleranceSeconds = toleranceSeconds;
+	}
+};
+/**
+* Thrown when extracting raw payload from request or stream fails.
+*/
+var PayloadExtractionError = class extends WebhookKitError {
+	constructor(message = "Failed to extract raw body payload for verification") {
+		super(message, "PAYLOAD_EXTRACTION_FAILED");
+		this.name = "PayloadExtractionError";
+	}
+};
+/**
+* Thrown or returned when a webhook event ID has already been processed in the replay store.
+*/
+var ReplayAttackError = class extends WebhookKitError {
+	eventId;
+	constructor(eventId, message) {
+		super(message ?? `Duplicate webhook event rejected (replay protection): event "${eventId}" was already processed`, "WEBHOOK_REPLAY_DETECTED");
+		this.name = "ReplayAttackError";
+		this.eventId = eventId;
+	}
+};
+// src/store.ts
+const DEFAULT_REPLAY_STORE_MAX_SIZE = 1e4;
+const DEFAULT_REPLAY_STORE_TTL_SECONDS = 300;
+const GENERIC_EVENT_ID_HEADERS = [
+	"x-webhook-id",
+	"webhook-id",
+	"x-github-delivery",
+	"x-shopify-webhook-id",
+	"x-event-id",
+	"x-idempotency-key"
+];
+/**
+* Default in-memory TTL replay store backed by a JavaScript `Map`.
+* Automatically evicts expired entries on lookup and enforces an upper capacity bound
+* with LRU (Least Recently Used) eviction.
+*/
+var InMemoryReplayStore = class {
+	maxSize;
+	defaultTtlSeconds;
+	now;
+	entries = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.maxSize = options.maxSize ?? DEFAULT_REPLAY_STORE_MAX_SIZE;
+		this.defaultTtlSeconds = options.defaultTtlSeconds ?? DEFAULT_REPLAY_STORE_TTL_SECONDS;
+		this.now = options.now ?? Date.now;
+	}
+	/**
+	* Checks whether `eventId` is currently tracked and unexpired in the store.
+	*
+	* @param eventId - Unique webhook event or delivery identifier.
+	* @returns `true` if `eventId` is present and unexpired, `false` otherwise.
+	*/
+	has(eventId) {
+		const expiresAt = this.entries.get(eventId);
+		if (expiresAt === void 0) return false;
+		if (this.now() >= expiresAt) {
+			this.entries.delete(eventId);
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Records `eventId` in the store with the specified TTL in seconds.
+	*
+	* @param eventId - Unique webhook event or delivery identifier.
+	* @param ttlSeconds - Time-to-live in seconds before expiration.
+	*/
+	set(eventId, ttlSeconds = this.defaultTtlSeconds) {
+		const effectiveTtl = Number.isFinite(ttlSeconds) ? ttlSeconds : this.defaultTtlSeconds;
+		if (effectiveTtl <= 0) {
+			this.entries.delete(eventId);
+			return;
+		}
+		if (this.entries.has(eventId)) this.entries.delete(eventId);
+		else if (this.entries.size >= this.maxSize) this.evictExpiredOrOldest();
+		this.entries.set(eventId, this.now() + effectiveTtl * 1e3);
+	}
+	/**
+	* Removes a specific `eventId` from the store.
+	*
+	* @param eventId - Unique webhook event or delivery identifier.
+	* @returns `true` if the entry existed and was removed.
+	*/
+	delete(eventId) {
+		return this.entries.delete(eventId);
+	}
+	/**
+	* Clears all tracked event IDs from the store.
+	*/
+	clear() {
+		this.entries.clear();
+	}
+	/**
+	* Removes all expired entries from the store and returns the number of purged entries.
+	*
+	* @returns Count of expired entries removed.
+	*/
+	prune() {
+		const currentMs = this.now();
+		let removed = 0;
+		for (const [key, expiresAt] of this.entries.entries()) if (currentMs >= expiresAt) {
+			this.entries.delete(key);
+			removed += 1;
+		}
+		return removed;
+	}
+	/**
+	* Returns the current number of entries stored in the underlying map.
+	*/
+	get size() {
+		return this.entries.size;
+	}
+	/**
+	* Returns the maximum capacity of the store.
+	*/
+	get capacity() {
+		return this.maxSize;
+	}
+	evictExpiredOrOldest() {
+		this.prune();
+		if (this.entries.size < this.maxSize) return;
+		const oldestKey = this.entries.keys().next().value;
+		if (oldestKey !== void 0) this.entries.delete(oldestKey);
+	}
+};
+/**
+* Creates a new `InMemoryReplayStore` instance with optional capacity and TTL settings.
+*
+* @param options - Optional capacity, default TTL, and clock configuration.
+* @returns Configured `InMemoryReplayStore` instance.
+*/
+function createInMemoryReplayStore(options) {
+	return new InMemoryReplayStore(options);
+}
+/**
+* Case-insensitively extracts a single header value from a `Headers` instance or plain record.
+*
+* @param headers - Web standard `Headers` instance or record.
+* @param targetName - Lowercase target header name.
+* @returns Header value string or undefined.
+*/
+function getHeaderCaseInsensitive(headers, targetName) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(targetName) ?? void 0;
+	const record = headers;
+	const lowerTarget = targetName.toLowerCase();
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerTarget) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Searches candidate header names in a `Headers` or record object for a non-empty value.
+*
+* @param headers - Headers source.
+* @param candidateNames - Ordered list of lowercase header names.
+* @returns Trimmed non-empty header value or undefined.
+*/
+function findHeaderValue(headers, candidateNames) {
+	if (!headers) return;
+	for (const name of candidateNames) {
+		const trimmed = getHeaderCaseInsensitive(headers, name)?.trim();
+		if (trimmed) return trimmed;
+	}
+}
+/**
+* Extracts a string or finite number `id` property from a parsed payload or raw JSON body.
+*
+* @param payload - Already parsed payload object if available.
+* @param rawBody - Raw JSON string fallback when `parseJson` was disabled.
+* @returns Extracted string event ID or undefined.
+*/
+function extractIdFromPayload(payload, rawBody) {
+	const candidate = resolvePayloadObject(payload, rawBody);
+	if (!candidate) return;
+	const idValue = candidate.id;
+	if (typeof idValue === "string" && idValue.trim()) return idValue.trim();
+	if (typeof idValue === "number" && Number.isFinite(idValue)) return String(idValue);
+}
+/**
+* Resolves a record object from either an already-parsed payload or a raw JSON string.
+*
+* @param payload - Parsed payload value.
+* @param rawBody - Raw body string.
+* @returns Object record or null.
+*/
+function resolvePayloadObject(payload, rawBody) {
+	if (typeof payload === "object" && payload !== null) return payload;
+	if (!rawBody) return null;
+	try {
+		const parsed = JSON.parse(rawBody);
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Extracts a matching header value from a Web Standard `Request` body if provided.
+*
+* @param body - Candidate raw body input.
+* @param headerCandidates - Ordered delivery ID header names.
+* @returns Matching header value or undefined.
+*/
+function findHeaderInRequest(body, headerCandidates) {
+	if (typeof Request !== "undefined" && body instanceof Request) return findHeaderValue(body.headers, headerCandidates);
+}
+/**
+* Resolves the unique webhook event ID from explicit options, delivery headers, or payload `id`.
+*
+* @param options - Source options containing explicit `eventId`, `headers`, `body`, `payload`, and `rawBody`.
+* @param headerCandidates - Ordered delivery ID header names to inspect prior to payload fallback.
+* @returns Resolved non-empty event ID string or `undefined`.
+*/
+function resolveWebhookEventId(options, headerCandidates = GENERIC_EVENT_ID_HEADERS) {
+	const explicitId = options.eventId?.trim();
+	if (explicitId) return explicitId;
+	const fromHeaders = findHeaderValue(options.headers, headerCandidates) ?? findHeaderInRequest(options.body, headerCandidates);
+	if (fromHeaders) return fromHeaders;
+	return extractIdFromPayload(options.payload, options.rawBody);
+}
+/**
+* Computes the effective replay store TTL in seconds from explicit `storeTtlSeconds` or `toleranceSeconds`.
+*
+* @param storeTtlSeconds - Explicit TTL in seconds.
+* @param toleranceSeconds - Timestamp tolerance in seconds.
+* @returns Positive TTL in seconds (defaults to 300s).
+*/
+function resolveEffectiveTtl(storeTtlSeconds, toleranceSeconds) {
+	if (storeTtlSeconds !== void 0 && storeTtlSeconds > 0) return storeTtlSeconds;
+	if (toleranceSeconds !== void 0 && toleranceSeconds > 0) return toleranceSeconds;
+	return DEFAULT_REPLAY_STORE_TTL_SECONDS;
+}
+/**
+* Verifies that `eventId` has not already been seen in `store`, and records it with a TTL if unseen.
+*
+* @param options - Store instance, resolved `eventId`, and TTL configuration.
+* @returns `ReplayAttackError` if `eventId` is already present in `store`, or `null` if unseen / no store.
+*/
+async function checkAndRecordReplay(options) {
+	const { store, eventId } = options;
+	if (!store || !eventId) return null;
+	if (await store.has(eventId)) return new ReplayAttackError(eventId);
+	const ttlSeconds = resolveEffectiveTtl(options.storeTtlSeconds, options.toleranceSeconds);
+	await store.set(eventId, ttlSeconds);
+	return null;
+}
+// src/crypto/subtle.ts
+/**
+* Lightweight LRU (Least Recently Used) cache backed by a JavaScript `Map`.
+* Reuses compiled WebCrypto keys across concurrent requests and evicts the
+* oldest entries when capacity is reached.
+*/
+var CryptoKeyLruCache = class {
+	maxSize;
+	map = /* @__PURE__ */ new Map();
+	constructor(maxSize = 256) {
+		this.maxSize = maxSize;
+	}
+	get(key) {
+		const item = this.map.get(key);
+		if (!item) return;
+		this.map.delete(key);
+		this.map.set(key, item);
+		return item;
+	}
+	set(key, value) {
+		if (this.map.has(key)) this.map.delete(key);
+		else if (this.map.size >= this.maxSize) {
+			const oldestKey = this.map.keys().next().value;
+			if (oldestKey !== void 0) this.map.delete(oldestKey);
+		}
+		this.map.set(key, value);
+	}
+	has(key) {
+		return this.map.has(key);
+	}
+	delete(key) {
+		return this.map.delete(key);
+	}
+	clear() {
+		this.map.clear();
+	}
+	get size() {
+		return this.map.size;
+	}
+	get capacity() {
+		return this.maxSize;
+	}
+};
+/**
+* Global in-memory LRU cache holding compiled WebCrypto HMAC keys.
+*/
+const defaultCryptoKeyCache = new CryptoKeyLruCache(256);
+/**
+* Computes a fast 128-bit composite hash of secret bytes for safe cache key generation
+* without retaining raw secret strings or byte sequences in cache keys.
+*
+* @param bytes Raw secret bytes.
+* @returns Hex-encoded composite hash with length prefix.
+*/
+function hashSecret(bytes) {
+	let h1 = 2166136261;
+	let h2 = 668265263;
+	let h3 = 2654435769;
+	let h4 = 1164378403;
+	const len = bytes.length;
+	for (let i = 0; i < len; i++) {
+		const b = bytes[i];
+		h1 = Math.imul(h1 ^ b, 16777619);
+		h2 = Math.imul(h2 ^ b + i, 1540483477);
+		h3 = Math.imul(h3 ^ (b << 4 | b >>> 4), 461845907);
+		h4 = Math.imul(h4 ^ b * 31, 3432918353);
+	}
+	return `${len}_${(h1 >>> 0).toString(16)}_${(h2 >>> 0).toString(16)}_${(h3 >>> 0).toString(16)}_${(h4 >>> 0).toString(16)}`;
+}
+/**
+* Generates an in-memory cache key composed of the normalized algorithm and secret hash.
+*
+* @param normalizedHash Normalized hash algorithm (e.g. `'SHA-256'`).
+* @param secretBytes Raw secret bytes.
+* @returns Formatted cache key string.
+*/
+function getSecretCacheKey(normalizedHash, secretBytes) {
+	return `${normalizedHash}:${hashSecret(secretBytes)}`;
+}
+/**
+* Invokes `crypto.subtle.importKey` for an HMAC signing key.
+*/
+function importHmacKey(subtle, normalizedHash, secretBytes) {
+	return subtle.importKey("raw", secretBytes, {
+		name: "HMAC",
+		hash: { name: normalizedHash }
+	}, false, ["sign"]);
+}
+/**
+* Resolves a compiled `CryptoKey` from cache or initiates and caches a new one.
+*/
+function getOrCreateCryptoKey(subtle, normalizedHash, secretBytes, cache = defaultCryptoKeyCache) {
+	const cacheKey = getSecretCacheKey(normalizedHash, secretBytes);
+	const cachedPromise = cache.get(cacheKey);
+	if (cachedPromise) return cachedPromise;
+	const keyPromise = importHmacKey(subtle, normalizedHash, secretBytes);
+	keyPromise.catch(() => {
+		cache.delete(cacheKey);
+	});
+	cache.set(cacheKey, keyPromise);
+	return keyPromise;
+}
+/**
+* Clears all compiled WebCrypto HMAC keys from the global key cache.
+*/
+function clearCryptoKeyCache() {
+	defaultCryptoKeyCache.clear();
+}
+/**
+* Returns the current number of compiled WebCrypto HMAC keys stored in the global key cache.
+*/
+function getCryptoKeyCacheSize() {
+	return defaultCryptoKeyCache.size;
+}
+/**
+* Retrieves a cached WebCrypto HMAC key or compiles and caches a new one.
+*
+* @param algorithm HMAC digest algorithm (e.g. `'SHA-256'`).
+* @param secret Raw secret string or byte array.
+* @param cache Optional custom `CryptoKeyLruCache` instance.
+* @returns Compiled `CryptoKey` instance.
+*/
+async function getCachedCryptoKey(algorithm, secret, cache = defaultCryptoKeyCache) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("Web Cryptography API (crypto.subtle) is not available in the current runtime environment.");
+	return getOrCreateCryptoKey(subtle, normalizeHashAlgorithm(algorithm), toUint8Array(secret), cache);
+}
+/**
+* Normalizes hash algorithm names into standard W3C Web Crypto format.
+*
+* @param algorithm Algorithm identifier (e.g. `'sha256'`, `'SHA256'`, `'SHA-256'`).
+* @returns Normalized Web Crypto hash identifier (e.g. `'SHA-256'`).
+*/
+function normalizeHashAlgorithm(algorithm) {
+	const upper = algorithm.toUpperCase().trim();
+	if (/^SHA-?\d+$/.test(upper)) return upper.startsWith("SHA-") ? upper : upper.replace("SHA", "SHA-");
+	return upper;
+}
+/**
+* Converts a string or buffer into a `Uint8Array` backed by an `ArrayBuffer`.
+*
+* @param input String, `Uint8Array`, or `ArrayBuffer` payload.
+* @returns `Uint8Array<ArrayBuffer>` view suitable for Web Crypto `BufferSource`.
+*/
+function toUint8Array(input) {
+	if (typeof input === "string") return new TextEncoder().encode(input);
+	if (input instanceof Uint8Array) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+	return new Uint8Array(input);
+}
+/**
+* Constant-time comparison between two buffers or strings to prevent timing side-channel attacks.
+*
+* @param a First byte array or string.
+* @param b Second byte array or string.
+* @returns `true` if byte sequences are identical, `false` otherwise.
+*/
+function timingSafeEqual(a, b) {
+	const bufA = typeof a === "string" ? new TextEncoder().encode(a) : a;
+	const bufB = typeof b === "string" ? new TextEncoder().encode(b) : b;
+	const lenA = bufA.length;
+	const lenB = bufB.length;
+	let mismatch = lenA === lenB ? 0 : 1;
+	const maxLen = Math.max(lenA, lenB);
+	for (let i = 0; i < maxLen; i++) {
+		const byteA = i < lenA ? bufA[i] : 0;
+		const byteB = i < lenB ? bufB[i] : 0;
+		mismatch |= byteA ^ byteB;
+	}
+	return mismatch === 0;
+}
+/**
+* Formats a raw HMAC digest according to the requested encoding.
+*/
+function formatHmacDigest(bytes, encoding) {
+	if (encoding === "hex") return bytesToHex(bytes);
+	if (encoding === "base64") return bytesToBase64(bytes);
+	return bytes;
+}
+/**
+* Normalizes options and extract encoding and cache preferences.
+*/
+function extractHmacOptions(encodingOrOptions) {
+	if (typeof encodingOrOptions === "string") return {
+		encoding: encodingOrOptions,
+		bypassCache: false
+	};
+	return {
+		encoding: encodingOrOptions?.encoding,
+		bypassCache: Boolean(encodingOrOptions?.bypassCache)
+	};
+}
+/**
+* Obtains a `CryptoKey` either by bypassing or utilizing the LRU cache.
+*/
+function resolveSubtleHmacKey(subtle, normalizedHash, secretBytes, bypassCache) {
+	if (bypassCache) return importHmacKey(subtle, normalizedHash, secretBytes);
+	return getOrCreateCryptoKey(subtle, normalizedHash, secretBytes);
+}
+async function computeSubtleHmac(algorithm, secret, data, encodingOrOptions) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("Web Cryptography API (crypto.subtle) is not available in the current runtime environment.");
+	const normalizedHash = normalizeHashAlgorithm(algorithm);
+	const secretBytes = toUint8Array(secret);
+	const dataBytes = toUint8Array(data);
+	const { encoding, bypassCache } = extractHmacOptions(encodingOrOptions);
+	const key = await resolveSubtleHmacKey(subtle, normalizedHash, secretBytes, bypassCache);
+	const signatureBuffer = await subtle.sign("HMAC", key, dataBytes);
+	return formatHmacDigest(new Uint8Array(signatureBuffer), encoding);
+}
+/**
+* Converts a `Uint8Array` into a lowercase hexadecimal string.
+*
+* @param bytes Input byte array.
+* @returns Lowercase hexadecimal string.
+*/
+function bytesToHex(bytes) {
+	return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Converts a hexadecimal string into a `Uint8Array`.
+*
+* @param hex Hexadecimal string (with optional `0x` prefix).
+* @returns Decoded byte array.
+*/
+function hexToBytes(hex) {
+	const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+	const normalizedHex = cleanHex.length % 2 === 1 ? `0${cleanHex}` : cleanHex;
+	const bytes = new Uint8Array(normalizedHex.length / 2);
+	for (let i = 0; i < normalizedHex.length; i += 2) bytes[i / 2] = parseInt(normalizedHex.slice(i, i + 2), 16);
+	return bytes;
+}
+/**
+* Converts a `Uint8Array` into a Base64-encoded string using standard Web APIs.
+*
+* @param bytes Input byte array.
+* @returns Base64-encoded string.
+*/
+function bytesToBase64(bytes) {
+	let binary = "";
+	const len = bytes.byteLength;
+	const chunkSize = 32768;
+	for (let i = 0; i < len; i += chunkSize) {
+		const chunk = bytes.subarray(i, Math.min(i + chunkSize, len));
+		binary += String.fromCharCode(...chunk);
+	}
+	return globalThis.btoa(binary);
+}
+/**
+* Converts a Base64-encoded string into a `Uint8Array` using standard Web APIs.
+*
+* @param base64 Base64-encoded string.
+* @returns Decoded byte array.
+*/
+function base64ToBytes(base64) {
+	const binary = globalThis.atob(base64.trim());
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+// src/utils/extract-body.ts
+/**
+* Checks whether an unknown value is a binary BufferSource (ArrayBuffer or ArrayBufferView).
+*
+* @param value Candidate value.
+* @returns `true` if the value is an ArrayBuffer or ArrayBufferView.
+*/
+function isBinarySource(value) {
+	return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+/**
+* Checks whether an unknown value is a Web Standard `Request`.
+*
+* @param value Candidate value.
+* @returns `true` if the value is a Request instance.
+*/
+function isRequest(value) {
+	return typeof Request !== "undefined" && value instanceof Request;
+}
+/**
+* Checks whether an unknown value is a Web Standard `ReadableStream`.
+*
+* @param value Candidate value.
+* @returns `true` if the value exposes a stream reader.
+*/
+function isReadableStream(value) {
+	return typeof value === "object" && value !== null && typeof value.getReader === "function";
+}
+/**
+* Clones and reads text from a Web Standard `Request` without consuming the original body.
+*
+* @param request Incoming `Request` instance.
+* @returns Raw UTF-8 body string.
+*/
+async function readRequestBody(request) {
+	try {
+		return await request.clone().text();
+	} catch (err) {
+		throw new PayloadExtractionError(`Failed to read text from Request body: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Decodes a single chunk from a ReadableStream using a streaming TextDecoder.
+*
+* @param decoder Streaming TextDecoder instance.
+* @param chunk Incoming chunk value.
+* @returns Decoded string chunk.
+*/
+function decodeStreamChunk(decoder, chunk) {
+	if (typeof chunk === "string") return chunk;
+	if (isBinarySource(chunk)) return decoder.decode(chunk, { stream: true });
+	throw new PayloadExtractionError(`Unsupported stream chunk type: expected binary or string, received ${typeof chunk}`);
+}
+/**
+* Reads all chunks from a Web Standard `ReadableStream` into a complete UTF-8 string.
+*
+* @param stream Incoming `ReadableStream` instance.
+* @returns Complete raw string body.
+*/
+async function readReadableStream(stream) {
+	try {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		let result = "";
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				result += decodeStreamChunk(decoder, value);
+			}
+			result += decoder.decode();
+			return result;
+		} finally {
+			reader.releaseLock();
+		}
+	} catch (err) {
+		if (err instanceof PayloadExtractionError) throw err;
+		throw new PayloadExtractionError(`Failed to read text from ReadableStream: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Safely extracts the unmodified raw string body from various input representations:
+* Web Standard `Request`, `ReadableStream`, `Uint8Array`, `ArrayBuffer`, `ArrayBufferView`, or primitive `string`.
+*
+* @param body The raw request or body object.
+* @returns Unmodified string representation suitable for cryptographic HMAC verification.
+* @throws {PayloadExtractionError} If body cannot be read or is invalid.
+*/
+async function extractRawBody(body) {
+	if (typeof body === "string") return body;
+	if (isBinarySource(body)) return new TextDecoder().decode(body);
+	if (isRequest(body)) return readRequestBody(body);
+	if (isReadableStream(body)) return readReadableStream(body);
+	throw new PayloadExtractionError("Unsupported body type. Expected string, Uint8Array, ArrayBuffer, ReadableStream, or Request.");
+}
+// src/providers/github.ts
+const GITHUB_SIGNATURE_PREFIX = "sha256=";
+const GITHUB_EVENT_ID_HEADERS = [
+	"x-github-delivery",
+	"x-webhook-id",
+	"webhook-id"
+];
+/**
+* Asserts that a header value is a non-empty string.
+*
+* @param header - Candidate header value.
+*/
+function assertNonEmptyHeader$2(header) {
+	if (typeof header !== "string" || !header.trim()) throw new InvalidSignatureHeaderError("Missing or empty X-Hub-Signature-256 header");
+}
+/**
+* Parses an `X-Hub-Signature-256` header, validating and extracting the hex signature.
+*
+* @param header - Raw `X-Hub-Signature-256` header string (e.g. `sha256=d57c68d1...`).
+* @returns Hexadecimal signature string after the `sha256=` prefix.
+* @throws {InvalidSignatureHeaderError} If header is missing, empty, or lacks a valid sha256= prefix.
+*/
+function parseGithubSignature(header) {
+	assertNonEmptyHeader$2(header);
+	const trimmed = header.trim();
+	if (!trimmed.toLowerCase().startsWith(GITHUB_SIGNATURE_PREFIX)) throw new InvalidSignatureHeaderError("Invalid X-Hub-Signature-256 header format: expected 'sha256=' prefix");
+	const signature = trimmed.slice(7).trim();
+	if (!signature) throw new InvalidSignatureHeaderError("Invalid X-Hub-Signature-256 header: missing signature hash after prefix");
+	return signature;
+}
+/**
+* Case-insensitively extracts a header value from a `Headers` instance or plain record.
+*
+* @param headers - Web standard `Headers` instance or record.
+* @param targetName - Lowercase target header name.
+* @returns Header value string or undefined.
+*/
+function extractHeaderValue$3(headers, targetName) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(targetName) ?? void 0;
+	const record = headers;
+	const lowerTarget = targetName.toLowerCase();
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerTarget) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Resolves the raw signature header string from options, headers record, or request.
+*
+* @param options - GitHub verification options.
+* @returns GitHub signature header string or undefined if not found.
+*/
+function resolveSignatureHeader$2(options) {
+	if (options.signature) return options.signature;
+	if (options.headers) return extractHeaderValue$3(options.headers, "x-hub-signature-256");
+	if (typeof Request !== "undefined" && options.body instanceof Request) return options.body.headers.get("x-hub-signature-256") ?? void 0;
+}
+/**
+* Validates preconditions for GitHub webhook verification.
+*
+* @param options - GitHub verification options.
+* @param rawHeader - Resolved header string.
+* @returns Error if preconditions fail, null otherwise.
+*/
+function validatePreconditions$2(options, rawHeader) {
+	if (!options.secret) return new SignatureVerificationError("Missing GitHub webhook signing secret");
+	if (!rawHeader) return new InvalidSignatureHeaderError("Missing X-Hub-Signature-256 header");
+	return null;
+}
+/**
+* Safely parses the raw signature header without uncaught exceptions.
+*
+* @param rawHeader - Raw header string.
+* @returns Extracted signature string or error object.
+*/
+function safeParseHeader$2(rawHeader) {
+	try {
+		return { signature: parseGithubSignature(rawHeader) };
+	} catch (err) {
+		return { error: err instanceof WebhookKitError ? err : new InvalidSignatureHeaderError(String(err)) };
+	}
+}
+/**
+* Constructs a failed WebhookVerificationResult or throws if throwOnError is set.
+*
+* @param rawBody - Raw body string.
+* @param error - WebhookKitError instance.
+* @param throwOnError - Optional flag to throw immediately.
+* @returns Failed verification result.
+*/
+function failVerification$3(rawBody, error, throwOnError, eventId) {
+	if (throwOnError) throw error;
+	return {
+		valid: false,
+		rawBody,
+		eventId,
+		error
+	};
+}
+/**
+* Attempts to parse the raw body as JSON.
+*
+* @param rawBody - Raw body payload string.
+* @returns Parsed payload or undefined.
+*/
+function tryParseJson$3(rawBody) {
+	try {
+		return JSON.parse(rawBody);
+	} catch {
+		return;
+	}
+}
+/**
+* Verifies a GitHub webhook payload signature against `X-Hub-Signature-256`.
+*
+* GitHub signs the raw request payload using HMAC-SHA256 with the webhook secret.
+*
+* @param options - GitHub verification options.
+* @returns Verification result with typed payload.
+*/
+async function verifyGithubWebhook(options) {
+	const rawBody = await extractRawBody(options.body);
+	const rawHeader = resolveSignatureHeader$2(options);
+	const preconditionError = validatePreconditions$2(options, rawHeader);
+	if (preconditionError) return failVerification$3(rawBody, preconditionError, options.throwOnError);
+	const parsed = safeParseHeader$2(rawHeader);
+	if ("error" in parsed) return failVerification$3(rawBody, parsed.error, options.throwOnError);
+	if (!timingSafeEqual((await computeSubtleHmac("SHA-256", options.secret, rawBody, "hex")).toLowerCase(), parsed.signature.toLowerCase())) return failVerification$3(rawBody, new SignatureVerificationError("GitHub signature verification failed: signature does not match expected HMAC"), options.throwOnError);
+	const payload = options.parseJson !== false ? tryParseJson$3(rawBody) : void 0;
+	const eventId = resolveWebhookEventId({
+		eventId: options.eventId,
+		headers: options.headers,
+		body: options.body,
+		payload,
+		rawBody
+	}, GITHUB_EVENT_ID_HEADERS);
+	const replayError = await checkAndRecordReplay({
+		store: options.store,
+		eventId,
+		storeTtlSeconds: options.storeTtlSeconds,
+		toleranceSeconds: options.toleranceSeconds
+	});
+	if (replayError) return failVerification$3(rawBody, replayError, options.throwOnError, eventId);
+	return {
+		valid: true,
+		rawBody,
+		eventId,
+		payload
+	};
+}
+/**
+* Asserts that a GitHub webhook payload signature is valid, throwing on verification failure.
+*
+* @param options - GitHub verification options.
+* @returns Parsed and typed event payload.
+* @throws {SignatureVerificationError} If signature verification fails.
+* @throws {InvalidSignatureHeaderError} If header format is invalid or missing.
+*/
+async function assertGithubWebhook(options) {
+	return (await verifyGithubWebhook({
+		...options,
+		throwOnError: true
+	})).payload;
+}
+/**
+* Webhook provider plugin for GitHub.
+*/
+const githubPlugin = {
+	name: "github",
+	verify: verifyGithubWebhook
+};
+// src/providers/shopify.ts
+const BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const SHOPIFY_EVENT_ID_HEADERS = [
+	"x-shopify-webhook-id",
+	"x-webhook-id",
+	"webhook-id"
+];
+/**
+* Asserts that a header value is a non-empty string.
+*
+* @param header - Candidate header value.
+*/
+function assertNonEmptyHeader$1(header) {
+	if (typeof header !== "string" || !header.trim()) throw new InvalidSignatureHeaderError("Missing or empty X-Shopify-Hmac-Sha256 header");
+}
+/**
+* Parses an `X-Shopify-Hmac-Sha256` header, validating and normalizing the Base64 signature.
+*
+* @param header - Raw `X-Shopify-Hmac-Sha256` Base64 header string.
+* @returns Normalized Base64-encoded HMAC-SHA256 signature string.
+* @throws {InvalidSignatureHeaderError} If header is missing, empty, or not valid Base64.
+*/
+function parseShopifySignature(header) {
+	assertNonEmptyHeader$1(header);
+	const trimmed = header.trim();
+	if (!BASE64_REGEX.test(trimmed)) throw new InvalidSignatureHeaderError("Invalid X-Shopify-Hmac-Sha256 header format: expected Base64-encoded string");
+	return trimmed;
+}
+/**
+* Case-insensitively extracts a header value from a `Headers` instance or plain record.
+*
+* @param headers - Web standard `Headers` instance or record.
+* @param targetName - Lowercase target header name.
+* @returns Header value string or undefined.
+*/
+function extractHeaderValue$2(headers, targetName) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(targetName) ?? void 0;
+	const record = headers;
+	const lowerTarget = targetName.toLowerCase();
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerTarget) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Resolves the raw signature header string from options, headers record, or request.
+*
+* @param options - Shopify verification options.
+* @returns Shopify signature header string or undefined if not found.
+*/
+function resolveSignatureHeader$1(options) {
+	if (options.signature) return options.signature;
+	if (options.headers) return extractHeaderValue$2(options.headers, "x-shopify-hmac-sha256");
+	if (typeof Request !== "undefined" && options.body instanceof Request) return options.body.headers.get("x-shopify-hmac-sha256") ?? void 0;
+}
+/**
+* Validates preconditions for Shopify webhook verification.
+*
+* @param options - Shopify verification options.
+* @param rawHeader - Resolved header string.
+* @returns Error if preconditions fail, null otherwise.
+*/
+function validatePreconditions$1(options, rawHeader) {
+	if (!options.secret) return new SignatureVerificationError("Missing Shopify webhook signing secret");
+	if (!rawHeader) return new InvalidSignatureHeaderError("Missing X-Shopify-Hmac-Sha256 header");
+	return null;
+}
+/**
+* Safely parses the raw signature header without uncaught exceptions.
+*
+* @param rawHeader - Raw header string.
+* @returns Extracted Base64 signature string or error object.
+*/
+function safeParseHeader$1(rawHeader) {
+	try {
+		return { signature: parseShopifySignature(rawHeader) };
+	} catch (err) {
+		return { error: err instanceof WebhookKitError ? err : new InvalidSignatureHeaderError(String(err)) };
+	}
+}
+/**
+* Constructs a failed WebhookVerificationResult or throws if throwOnError is set.
+*
+* @param rawBody - Raw body string.
+* @param error - WebhookKitError instance.
+* @param throwOnError - Optional flag to throw immediately.
+* @returns Failed verification result.
+*/
+function failVerification$2(rawBody, error, throwOnError, eventId) {
+	if (throwOnError) throw error;
+	return {
+		valid: false,
+		rawBody,
+		eventId,
+		error
+	};
+}
+/**
+* Attempts to parse the raw body as JSON.
+*
+* @param rawBody - Raw body payload string.
+* @returns Parsed payload or undefined.
+*/
+function tryParseJson$2(rawBody) {
+	try {
+		return JSON.parse(rawBody);
+	} catch {
+		return;
+	}
+}
+/**
+* Verifies a Shopify webhook payload signature against `X-Shopify-Hmac-Sha256`.
+*
+* Shopify computes HMAC-SHA256 of the raw body and encodes it as Base64.
+*
+* @param options - Shopify verification options.
+* @returns Verification result with typed payload.
+*/
+async function verifyShopifyWebhook(options) {
+	const rawBody = await extractRawBody(options.body);
+	const rawHeader = resolveSignatureHeader$1(options);
+	const preconditionError = validatePreconditions$1(options, rawHeader);
+	if (preconditionError) return failVerification$2(rawBody, preconditionError, options.throwOnError);
+	const parsed = safeParseHeader$1(rawHeader);
+	if ("error" in parsed) return failVerification$2(rawBody, parsed.error, options.throwOnError);
+	if (!timingSafeEqual(await computeSubtleHmac("SHA-256", options.secret, rawBody, "base64"), parsed.signature)) return failVerification$2(rawBody, new SignatureVerificationError("Shopify signature verification failed: signature does not match expected HMAC"), options.throwOnError);
+	const payload = options.parseJson !== false ? tryParseJson$2(rawBody) : void 0;
+	const eventId = resolveWebhookEventId({
+		eventId: options.eventId,
+		headers: options.headers,
+		body: options.body,
+		payload,
+		rawBody
+	}, SHOPIFY_EVENT_ID_HEADERS);
+	const replayError = await checkAndRecordReplay({
+		store: options.store,
+		eventId,
+		storeTtlSeconds: options.storeTtlSeconds,
+		toleranceSeconds: options.toleranceSeconds
+	});
+	if (replayError) return failVerification$2(rawBody, replayError, options.throwOnError, eventId);
+	return {
+		valid: true,
+		rawBody,
+		eventId,
+		payload
+	};
+}
+/**
+* Asserts that a Shopify webhook payload signature is valid, throwing on verification failure.
+*
+* @param options - Shopify verification options.
+* @returns Parsed and typed event payload.
+* @throws {SignatureVerificationError} If signature verification fails.
+* @throws {InvalidSignatureHeaderError} If header format is invalid or missing.
+*/
+async function assertShopifyWebhook(options) {
+	return (await verifyShopifyWebhook({
+		...options,
+		throwOnError: true
+	})).payload;
+}
+/**
+* Webhook provider plugin for Shopify.
+*/
+const shopifyPlugin = {
+	name: "shopify",
+	verify: verifyShopifyWebhook
+};
+// src/providers/stripe.ts
+const STRIPE_EVENT_ID_HEADERS = [
+	"x-stripe-webhook-id",
+	"x-webhook-id",
+	"webhook-id"
+];
+/**
+* Case-insensitively extracts a header value from a `Headers` instance or plain record.
+*
+* @param headers - Web standard `Headers` instance or record.
+* @param targetName - Lowercase target header name.
+* @returns Header value string or undefined.
+*/
+function extractHeaderValue$1(headers, targetName) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(targetName) ?? void 0;
+	const record = headers;
+	const lowerTarget = targetName.toLowerCase();
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerTarget) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Resolves the raw signature header string from options, headers record, or request.
+*
+* @param options - Stripe verification options.
+* @returns Stripe signature header string or undefined if not found.
+*/
+function resolveSignatureHeader(options) {
+	if (options.signature) return options.signature;
+	if (options.headers) return extractHeaderValue$1(options.headers, "stripe-signature");
+	if (typeof Request !== "undefined" && options.body instanceof Request) return options.body.headers.get("stripe-signature") ?? void 0;
+}
+/**
+* Splits a header tag pair into key and value.
+*
+* @param item - Header entry (e.g. `t=1492774577` or `v1=...`).
+* @returns Key-value tuple or null if malformed.
+*/
+function parseKeyValue(item) {
+	const trimmed = item.trim();
+	const eqIndex = trimmed.indexOf("=");
+	if (eqIndex === -1) return null;
+	return [trimmed.slice(0, eqIndex).trim(), trimmed.slice(eqIndex + 1).trim()];
+}
+/**
+* Processes a single parsed tag from the Stripe signature header into accumulator state.
+*
+* @param key - Tag key (e.g. `'t'`, `'v1'`, `'v0'`).
+* @param value - Tag value string.
+* @param state - Mutable parsing state.
+*/
+function processHeaderTag(key, value, state) {
+	if (!value) return;
+	if (key === "v1") {
+		state.signatures.push(value);
+		return;
+	}
+	if (key === "v0") {
+		state.v0Signatures.push(value);
+		return;
+	}
+	if (key === "t") {
+		const parsed = parseInt(value, 10);
+		if (Number.isInteger(parsed) && parsed > 0) state.timestamp = parsed;
+	}
+}
+/**
+* Asserts that a header value is a non-empty string.
+*
+* @param header - Candidate header value.
+*/
+function assertNonEmptyHeader(header) {
+	if (typeof header !== "string" || !header.trim()) throw new InvalidSignatureHeaderError("Missing or empty Stripe-Signature header");
+}
+/**
+* Collects timestamp and signature schemes across comma-separated header entries.
+*
+* @param header - Non-empty header string.
+* @returns Parsed mutable state accumulator.
+*/
+function collectHeaderState(header) {
+	const state = {
+		signatures: [],
+		v0Signatures: []
+	};
+	const items = header.split(",");
+	for (const item of items) {
+		const pair = parseKeyValue(item);
+		if (pair) processHeaderTag(pair[0], pair[1], state);
+	}
+	return state;
+}
+/**
+* Validates that parsed header state satisfies Stripe protocol requirements.
+*
+* @param timestamp - Extracted Unix timestamp.
+* @param signaturesCount - Count of valid v1 signatures.
+*/
+function validateParsedState(timestamp, signaturesCount) {
+	if (timestamp === void 0) throw new InvalidSignatureHeaderError("Stripe-Signature header missing or invalid timestamp (t=...)");
+	if (!signaturesCount) throw new InvalidSignatureHeaderError("Stripe-Signature header missing valid v1 signature scheme (v1=...)");
+}
+/**
+* Parses a Stripe signature header string (`t=...,v1=...,v0=...`).
+*
+* @param header - Raw `Stripe-Signature` header string.
+* @returns Parsed header components including timestamp and signatures.
+* @throws {InvalidSignatureHeaderError} If header format is invalid or missing required tags.
+*/
+function parseStripeSignature(header) {
+	assertNonEmptyHeader(header);
+	const state = collectHeaderState(header);
+	validateParsedState(state.timestamp, state.signatures.length);
+	return {
+		timestamp: state.timestamp,
+		signatures: state.signatures,
+		v0Signatures: state.v0Signatures.length ? state.v0Signatures : void 0
+	};
+}
+/**
+* Validates that a webhook timestamp falls within the allowed tolerance window.
+*
+* @param timestamp - Unix timestamp in seconds from the signature header.
+* @param toleranceSeconds - Maximum allowed drift/age in seconds (default: 300s). Pass 0 to disable.
+* @param currentTimestamp - Optional current Unix timestamp in seconds (defaults to now).
+* @throws {TimestampToleranceError} If timestamp falls outside the tolerance window.
+*/
+function validateTimestampTolerance(timestamp, toleranceSeconds = 300, currentTimestamp) {
+	if (toleranceSeconds <= 0) return;
+	const now = currentTimestamp ?? Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - timestamp) > toleranceSeconds) throw new TimestampToleranceError(timestamp, toleranceSeconds);
+}
+/**
+* Compares an expected HMAC hex signature against candidate signatures in constant time.
+*
+* @param expectedSignature - Computed hex signature.
+* @param candidates - List of candidate hex signatures from the header.
+* @returns `true` if any candidate matches the expected signature.
+*/
+function matchesAnySignature(expectedSignature, candidates) {
+	let matched = false;
+	for (const candidate of candidates) if (timingSafeEqual(expectedSignature, candidate)) matched = true;
+	return matched;
+}
+/**
+* Attempts to parse the raw body as JSON.
+*
+* @param rawBody - Raw body payload string.
+* @returns Parsed payload or undefined.
+*/
+function tryParseJson$1(rawBody) {
+	try {
+		return JSON.parse(rawBody);
+	} catch {
+		return;
+	}
+}
+/**
+* Validates preconditions for Stripe webhook verification.
+*
+* @param options - Stripe verification options.
+* @param rawHeader - Resolved header string.
+* @returns Error if preconditions fail, null otherwise.
+*/
+function validatePreconditions(options, rawHeader) {
+	if (!options.secret) return new SignatureVerificationError("Missing Stripe webhook signing secret");
+	if (!rawHeader) return new InvalidSignatureHeaderError("Missing Stripe-Signature header");
+	return null;
+}
+/**
+* Safely parses the raw signature header without uncaught exceptions.
+*
+* @param rawHeader - Raw header string.
+* @returns Parsed header or error object.
+*/
+function safeParseHeader(rawHeader) {
+	try {
+		return parseStripeSignature(rawHeader);
+	} catch (err) {
+		return { error: err instanceof WebhookKitError ? err : new InvalidSignatureHeaderError(String(err)) };
+	}
+}
+/**
+* Checks timestamp tolerance, returning an error if tolerance window is exceeded.
+*
+* @param timestamp - Unix timestamp in seconds.
+* @param options - Stripe verification options.
+* @returns TimestampToleranceError if exceeded, null otherwise.
+*/
+function checkTolerance(timestamp, options) {
+	const tolerance = options.toleranceSeconds ?? 300;
+	try {
+		validateTimestampTolerance(timestamp, tolerance, options.currentTimestamp);
+		return null;
+	} catch (err) {
+		return err instanceof TimestampToleranceError ? err : new TimestampToleranceError(timestamp, tolerance);
+	}
+}
+/**
+* Constructs a failed WebhookVerificationResult or throws if throwOnError is set.
+*
+* @param rawBody - Raw body string.
+* @param error - WebhookKitError instance.
+* @param throwOnError - Optional flag to throw immediately.
+* @param timestamp - Optional parsed timestamp.
+* @returns Failed verification result.
+*/
+function failVerification$1(rawBody, error, throwOnError, timestamp, eventId) {
+	if (throwOnError) throw error;
+	return {
+		valid: false,
+		rawBody,
+		timestamp,
+		eventId,
+		error
+	};
+}
+/**
+* Verifies a Stripe webhook event signature.
+*
+* Stripe computes HMAC-SHA256 over `${timestamp}.${rawPayload}` and compares
+* against the `v1` signature tag in `Stripe-Signature`.
+*
+* @param options - Stripe verification options
+* @returns Verification result with typed payload
+*/
+async function verifyStripeWebhook(options) {
+	const rawBody = await extractRawBody(options.body);
+	const rawHeader = resolveSignatureHeader(options);
+	const preconditionError = validatePreconditions(options, rawHeader);
+	if (preconditionError) return failVerification$1(rawBody, preconditionError, options.throwOnError);
+	const parsedHeader = safeParseHeader(rawHeader);
+	if ("error" in parsedHeader) return failVerification$1(rawBody, parsedHeader.error, options.throwOnError);
+	const { timestamp, signatures } = parsedHeader;
+	const toleranceError = checkTolerance(timestamp, options);
+	if (toleranceError) return failVerification$1(rawBody, toleranceError, options.throwOnError, timestamp);
+	const signedPayload = `${timestamp}.${rawBody}`;
+	if (!matchesAnySignature(await computeSubtleHmac("SHA-256", options.secret, signedPayload, "hex"), signatures)) return failVerification$1(rawBody, new SignatureVerificationError("Stripe signature verification failed: signature does not match expected HMAC"), options.throwOnError, timestamp);
+	const payload = options.parseJson !== false ? tryParseJson$1(rawBody) : void 0;
+	const eventId = resolveWebhookEventId({
+		eventId: options.eventId,
+		headers: options.headers,
+		body: options.body,
+		payload,
+		rawBody
+	}, STRIPE_EVENT_ID_HEADERS);
+	const replayError = await checkAndRecordReplay({
+		store: options.store,
+		eventId,
+		storeTtlSeconds: options.storeTtlSeconds,
+		toleranceSeconds: options.toleranceSeconds
+	});
+	if (replayError) return failVerification$1(rawBody, replayError, options.throwOnError, timestamp, eventId);
+	return {
+		valid: true,
+		rawBody,
+		timestamp,
+		eventId,
+		payload
+	};
+}
+/**
+* Asserts that a Stripe webhook event signature is valid, throwing on verification failure.
+*
+* @param options - Stripe verification options.
+* @returns Parsed and typed event payload.
+* @throws {SignatureVerificationError} If signature verification fails.
+* @throws {TimestampToleranceError} If timestamp falls outside the tolerance window.
+* @throws {InvalidSignatureHeaderError} If header format is invalid or missing.
+*/
+async function assertStripeWebhook(options) {
+	return (await verifyStripeWebhook({
+		...options,
+		throwOnError: true
+	})).payload;
+}
+/**
+* Webhook provider plugin for Stripe.
+*/
+const stripePlugin = {
+	name: "stripe",
+	verify: verifyStripeWebhook
+};
+// src/verify.ts
+const GENERIC_SIGNATURE_HEADERS = [
+	"x-webhook-signature",
+	"x-signature",
+	"x-hub-signature-256",
+	"stripe-signature",
+	"x-shopify-hmac-sha256"
+];
+const GENERIC_TIMESTAMP_HEADERS = [
+	"x-webhook-timestamp",
+	"x-timestamp",
+	"webhook-timestamp"
+];
+const HEX_SCHEME_PREFIX_REGEX = /^(?:sha-?(?:256|384|512|1)|v1)=/i;
+/**
+* Built-in provider plugin registry keyed by lowercase provider name.
+*/
+const PROVIDER_REGISTRY = {
+	stripe: stripePlugin,
+	github: githubPlugin,
+	shopify: shopifyPlugin
+};
+/**
+* Case-insensitively extracts a single header value from a `Headers` instance or plain record.
+*
+* @param headers - Web standard `Headers` instance or record.
+* @param targetName - Lowercase target header name.
+* @returns Header value string or undefined.
+*/
+function extractHeaderValue(headers, targetName) {
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(targetName) ?? void 0;
+	const record = headers;
+	const lowerTarget = targetName.toLowerCase();
+	for (const key of Object.keys(record)) if (key.toLowerCase() === lowerTarget) {
+		const value = record[key];
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Searches a list of candidate header names in a `Headers` or record object.
+*
+* @param headers - Headers source.
+* @param candidateNames - Ordered list of lowercase header names to check.
+* @returns First matching non-empty header value or undefined.
+*/
+function findFirstHeader(headers, candidateNames) {
+	if (!headers) return;
+	for (const name of candidateNames) {
+		const val = extractHeaderValue(headers, name);
+		if (val) return val;
+	}
+}
+/**
+* Resolves the signature string from explicit options, headers record, or a `Request` body.
+*
+* @param options - Verification options.
+* @returns Resolved signature string or undefined.
+*/
+function resolveGenericSignature(options) {
+	if (options.signature) return options.signature;
+	const fromHeaders = findFirstHeader(options.headers, GENERIC_SIGNATURE_HEADERS);
+	if (fromHeaders) return fromHeaders;
+	if (typeof Request !== "undefined" && options.body instanceof Request) return findFirstHeader(options.body.headers, GENERIC_SIGNATURE_HEADERS);
+}
+/**
+* Resolves an optional timestamp value from explicit options, headers record, or a `Request` body.
+*
+* @param options - Verification options.
+* @returns Raw timestamp value or undefined.
+*/
+function resolveRawTimestamp(options) {
+	if (options.timestamp !== void 0) return options.timestamp;
+	const fromHeaders = findFirstHeader(options.headers, GENERIC_TIMESTAMP_HEADERS);
+	if (fromHeaders !== void 0) return fromHeaders;
+	if (typeof Request !== "undefined" && options.body instanceof Request) return findFirstHeader(options.body.headers, GENERIC_TIMESTAMP_HEADERS);
+}
+/**
+* Parses a raw timestamp number or string into a positive integer Unix timestamp.
+*
+* @param rawTimestamp - Raw timestamp from options or headers.
+* @returns Positive integer timestamp or `null` if invalid.
+*/
+function parseTimestampValue(rawTimestamp) {
+	const parsed = typeof rawTimestamp === "number" ? rawTimestamp : parseInt(String(rawTimestamp).trim(), 10);
+	if (!Number.isInteger(parsed) || parsed <= 0) return null;
+	return parsed;
+}
+/**
+* Parses and validates an optional timestamp against the configured tolerance window.
+*
+* @param options - Verification options.
+* @returns Parsed timestamp or a `TimestampToleranceError`.
+*/
+function verifyGenericTimestamp(options) {
+	const rawTimestamp = resolveRawTimestamp(options);
+	if (rawTimestamp === void 0) return {};
+	const parsed = parseTimestampValue(rawTimestamp);
+	const tolerance = options.toleranceSeconds ?? 300;
+	if (parsed === null) return { error: new TimestampToleranceError(0, tolerance, "Invalid webhook timestamp header or option") };
+	try {
+		validateTimestampTolerance(parsed, tolerance, options.currentTimestamp);
+		return { timestamp: parsed };
+	} catch (err) {
+		return { error: err instanceof TimestampToleranceError ? err : new TimestampToleranceError(parsed, tolerance) };
+	}
+}
+/**
+* Checks whether a secret string or byte array is non-empty.
+*
+* @param secret - Candidate secret key.
+* @returns `true` if secret is present and non-empty.
+*/
+function hasSecret(secret) {
+	if (!secret) return false;
+	return typeof secret === "string" ? secret.length > 0 : secret.byteLength > 0;
+}
+/**
+* Normalizes a candidate signature string according to the target encoding.
+*
+* @param signature - Raw signature string.
+* @param encoding - Digest encoding (`'hex'` or `'base64'`).
+* @returns Normalized signature string for constant-time comparison.
+*/
+function normalizeCandidateSignature(signature, encoding) {
+	const trimmed = signature.trim();
+	if (encoding === "base64") return trimmed;
+	return trimmed.replace(HEX_SCHEME_PREFIX_REGEX, "").trim().toLowerCase();
+}
+/**
+* Computes a normalized HMAC digest string for comparison.
+*
+* @param options - Verification options.
+* @param data - Signing payload string.
+* @param encoding - Digest encoding (`'hex'` or `'base64'`).
+* @returns Normalized digest string.
+*/
+async function computeNormalizedDigest(options, data, encoding) {
+	const digest = await computeSubtleHmac(options.algorithm ?? "SHA-256", options.secret, data, encoding);
+	return encoding === "hex" ? digest.toLowerCase() : digest;
+}
+/**
+* Compares candidate signature against HMAC of rawBody (and `${timestamp}.${rawBody}` if timestamped).
+*
+* @param options - Verification options.
+* @param rawBody - Extracted raw body string.
+* @param rawSignature - Raw signature header or option.
+* @param timestamp - Optional validated Unix timestamp.
+* @returns `true` if signature matches expected HMAC.
+*/
+async function matchesGenericHmac(options, rawBody, rawSignature, timestamp) {
+	const encoding = options.encoding ?? "hex";
+	const candidate = normalizeCandidateSignature(rawSignature, encoding);
+	if (!candidate) return false;
+	let matched = timingSafeEqual(await computeNormalizedDigest(options, rawBody, encoding), candidate);
+	if (timestamp !== void 0) {
+		if (timingSafeEqual(await computeNormalizedDigest(options, `${timestamp}.${rawBody}`, encoding), candidate)) matched = true;
+	}
+	return matched;
+}
+/**
+* Constructs a failed `WebhookVerificationResult` or throws if `throwOnError` is enabled.
+*
+* @param rawBody - Extracted raw body string.
+* @param error - `WebhookKitError` instance.
+* @param throwOnError - Whether to throw the error immediately.
+* @param timestamp - Optional parsed timestamp.
+* @returns Failed verification result.
+*/
+function failVerification(rawBody, error, throwOnError, timestamp, eventId) {
+	if (throwOnError) throw error;
+	return {
+		valid: false,
+		rawBody,
+		timestamp,
+		eventId,
+		error
+	};
+}
+/**
+* Safely parses a raw body string as JSON, returning `undefined` on syntax errors.
+*
+* @param rawBody - Raw body string.
+* @returns Parsed JSON value or `undefined`.
+*/
+function tryParseJson(rawBody) {
+	try {
+		return JSON.parse(rawBody);
+	} catch {
+		return;
+	}
+}
+/**
+* Executes a `WebhookProviderPlugin` and honors `options.throwOnError` if verification fails.
+*
+* @param plugin - Target webhook provider plugin.
+* @param options - Verification options.
+* @param enforceStoreAfterPlugin - Whether to run replay store enforcement after custom plugin verification.
+* @returns Provider verification result.
+*/
+async function runPluginVerification(plugin, options, enforceStoreAfterPlugin = false) {
+	const result = await plugin.verify(options);
+	if (!result.valid) {
+		if (options.throwOnError) throw result.error;
+		return result;
+	}
+	if (!enforceStoreAfterPlugin) return result;
+	const eventId = result.eventId ?? resolveWebhookEventId({
+		eventId: options.eventId,
+		headers: options.headers,
+		body: options.body,
+		payload: result.payload,
+		rawBody: result.rawBody
+	});
+	const replayError = await checkAndRecordReplay({
+		store: options.store,
+		eventId,
+		storeTtlSeconds: options.storeTtlSeconds,
+		toleranceSeconds: options.toleranceSeconds
+	});
+	if (replayError) return failVerification(result.rawBody, replayError, options.throwOnError, result.timestamp, eventId);
+	return {
+		...result,
+		eventId
+	};
+}
+/**
+* Delegates verification to a named built-in provider or custom `WebhookProviderPlugin`.
+*
+* @param options - Verification options containing `provider`.
+* @returns Provider verification result.
+*/
+async function delegateToProvider(options) {
+	const provider = options.provider;
+	if (typeof provider === "object") return runPluginVerification(provider, options, true);
+	const normalizedName = String(provider).toLowerCase().trim();
+	const builtin = PROVIDER_REGISTRY[normalizedName];
+	if (!builtin) return failVerification(await extractRawBody(options.body), new WebhookKitError(`Unsupported webhook provider: "${String(provider)}"`, "UNSUPPORTED_PROVIDER"), options.throwOnError);
+	return runPluginVerification(builtin, options);
+}
+/**
+* Verifies a generic HMAC webhook signature when no specific provider plugin is selected.
+*
+* @param options - Generic verification options.
+* @returns Verification outcome with typed payload.
+*/
+async function verifyGenericWebhook(options) {
+	const rawBody = await extractRawBody(options.body);
+	const rawSignature = resolveGenericSignature(options);
+	if (!hasSecret(options.secret) || !rawSignature) return failVerification(rawBody, new SignatureVerificationError("Missing signature or secret"), options.throwOnError);
+	const tsResult = verifyGenericTimestamp(options);
+	if (tsResult.error) return failVerification(rawBody, tsResult.error, options.throwOnError);
+	if (!await matchesGenericHmac(options, rawBody, rawSignature, tsResult.timestamp)) return failVerification(rawBody, new SignatureVerificationError(), options.throwOnError, tsResult.timestamp);
+	const payload = options.parseJson !== false ? tryParseJson(rawBody) : void 0;
+	const eventId = resolveWebhookEventId({
+		eventId: options.eventId,
+		headers: options.headers,
+		body: options.body,
+		payload,
+		rawBody
+	});
+	const replayError = await checkAndRecordReplay({
+		store: options.store,
+		eventId,
+		storeTtlSeconds: options.storeTtlSeconds,
+		toleranceSeconds: options.toleranceSeconds
+	});
+	if (replayError) return failVerification(rawBody, replayError, options.throwOnError, tsResult.timestamp, eventId);
+	return {
+		valid: true,
+		rawBody,
+		timestamp: tsResult.timestamp,
+		eventId,
+		payload
+	};
+}
+async function verifyWebhookSignature(options) {
+	if (options.provider !== void 0) return delegateToProvider(options);
+	return verifyGenericWebhook(options);
+}
+async function assertWebhookSignature(options) {
+	const result = await verifyWebhookSignature({
+		...options,
+		throwOnError: true
+	});
+	if (!result.valid) throw result.error;
+	return result.payload;
+}
+// src/handler.ts
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+const DEFAULT_SUCCESS_BODY = JSON.stringify({ received: true });
+/**
+* Creates a JSON `Response` with UTF-8 content-type headers.
+*
+* @param body - Serialized JSON string.
+* @param status - HTTP status code.
+* @returns Web Standard `Response`.
+*/
+function createJsonResponse(body, status) {
+	return new Response(body, {
+		status,
+		headers: { "content-type": JSON_CONTENT_TYPE }
+	});
+}
+/**
+* Resolves the appropriate HTTP status code for a `WebhookKitError`.
+*
+* @param error - Verification, replay, or extraction error.
+* @returns `400` for extraction errors, `409` for duplicate event replays, or `401` for verification errors.
+*/
+function resolveErrorStatus(error) {
+	if (error instanceof PayloadExtractionError) return 400;
+	if (error instanceof ReplayAttackError) return 409;
+	return 401;
+}
+/**
+* Converts a `WebhookKitError` into a structured JSON HTTP error `Response`.
+*
+* @param error - Verification or extraction error.
+* @returns `400`, `409`, or `401` JSON error response.
+*/
+function createErrorResponse(error) {
+	const status = resolveErrorStatus(error);
+	return createJsonResponse(JSON.stringify({ error: {
+		code: error.code,
+		message: error.message
+	} }), status);
+}
+/**
+* Checks whether an unknown value is a non-null object record.
+*
+* @param value - Candidate value.
+* @returns `true` if `value` is a non-null object.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Extracts a Web Standard `Request` from a framework context object (`{ req: { raw: Request } }`).
+*
+* @param value - Candidate context object.
+* @returns Extracted `Request` or `null` if not present.
+*/
+function extractRequestFromContext(value) {
+	if (!isRecord(value) || !isRecord(value.req)) return null;
+	return typeof Request !== "undefined" && value.req.raw instanceof Request ? value.req.raw : null;
+}
+/**
+* Unwraps a Web Standard `Request` from either a direct `Request` or a `WebhookLikeContext`.
+*
+* @param input - Handler first argument.
+* @returns Underlying `Request` or `null` if invalid.
+*/
+function unwrapRequest(input) {
+	if (typeof Request !== "undefined" && input instanceof Request) return input;
+	return extractRequestFromContext(input);
+}
+/**
+* Resolves the signing secret from a static value or dynamic secret resolver function.
+*
+* @param secret - Static secret or resolver function.
+* @param context - Original handler input (`Request` or framework context).
+* @param request - Unwrapped Web Standard `Request`.
+* @returns Resolved secret string or byte array.
+*/
+async function resolveSecret(secret, context, request) {
+	if (typeof secret === "function") return secret(context, request);
+	return secret;
+}
+/**
+* Resolves the replay store from a static store object or dynamic resolver function.
+*
+* @param store - Static replay store or resolver function.
+* @param context - Original handler input (`Request` or framework context).
+* @param request - Unwrapped Web Standard `Request`.
+* @returns Resolved `WebhookReplayStore` or `undefined`.
+*/
+async function resolveStore(store, context, request) {
+	if (typeof store === "function") return store(context, request);
+	return store;
+}
+/**
+* Converts the return value of `onEvent` into a Web Standard `Response`.
+*
+* @param output - Return value from `onEvent`.
+* @returns Web Standard `Response`.
+*/
+function formatSuccessResponse(output) {
+	if (typeof Response !== "undefined" && output instanceof Response) return output;
+	if (output === void 0) return createJsonResponse(DEFAULT_SUCCESS_BODY, 200);
+	return createJsonResponse(JSON.stringify(output), 200);
+}
+/**
+* Produces an error `Response` via `options.onError` if configured, or the default JSON responder.
+*
+* @param error - `WebhookKitError` instance.
+* @param meta - Error metadata including context, request, rawBody, and timestamp.
+* @param onError - Optional user-supplied error callback.
+* @returns Error `Response`.
+*/
+async function handleVerificationFailure(error, meta, onError) {
+	if (onError) return onError(error, meta);
+	return createErrorResponse(error);
+}
+/**
+* Resolves the secret and executes `verifyWebhookSignature`, catching `WebhookKitError` exceptions.
+*
+* @param options - Handler configuration options.
+* @param context - Handler input context.
+* @param request - Unwrapped Web Standard `Request`.
+* @returns Discriminated verification outcome for handler dispatch.
+*/
+async function verifyRequest(options, context, request) {
+	try {
+		const secret = await resolveSecret(options.secret, context, request);
+		const store = await resolveStore(options.store, context, request);
+		const result = await verifyWebhookSignature({
+			body: request,
+			secret,
+			provider: options.provider,
+			algorithm: options.algorithm,
+			encoding: options.encoding,
+			toleranceSeconds: options.toleranceSeconds,
+			currentTimestamp: options.currentTimestamp,
+			store,
+			eventId: options.eventId,
+			storeTtlSeconds: options.storeTtlSeconds,
+			parseJson: options.parseJson
+		});
+		if (!result.valid) return {
+			ok: false,
+			error: result.error,
+			rawBody: result.rawBody,
+			timestamp: result.timestamp,
+			eventId: result.eventId
+		};
+		return {
+			ok: true,
+			result
+		};
+	} catch (err) {
+		if (err instanceof WebhookKitError) return {
+			ok: false,
+			error: err
+		};
+		throw err;
+	}
+}
+function createWebhookHandler(options) {
+	return async (input) => {
+		const request = unwrapRequest(input);
+		if (!request) return createErrorResponse(new PayloadExtractionError("Invalid webhook handler input: expected Web Standard Request or context with { req: { raw: Request } }"));
+		const outcome = await verifyRequest(options, input, request);
+		if (!outcome.ok) return handleVerificationFailure(outcome.error, {
+			context: input,
+			request,
+			rawBody: outcome.rawBody,
+			timestamp: outcome.timestamp,
+			eventId: outcome.eventId
+		}, options.onError);
+		return formatSuccessResponse(await options.onEvent(outcome.result.payload, {
+			context: input,
+			request,
+			rawBody: outcome.result.rawBody,
+			timestamp: outcome.result.timestamp,
+			eventId: outcome.result.eventId
+		}));
+	};
+}
+exports.CryptoKeyLruCache = CryptoKeyLruCache;
+exports.InMemoryReplayStore = InMemoryReplayStore;
+exports.InvalidSignatureHeaderError = InvalidSignatureHeaderError;
+exports.PROVIDER_REGISTRY = PROVIDER_REGISTRY;
+exports.PayloadExtractionError = PayloadExtractionError;
+exports.ReplayAttackError = ReplayAttackError;
+exports.SignatureVerificationError = SignatureVerificationError;
+exports.TimestampToleranceError = TimestampToleranceError;
+exports.WebhookKitError = WebhookKitError;
+exports.assertGithubWebhook = assertGithubWebhook;
+exports.assertShopifyWebhook = assertShopifyWebhook;
+exports.assertStripeWebhook = assertStripeWebhook;
+exports.assertWebhookSignature = assertWebhookSignature;
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;
+exports.bytesToHex = bytesToHex;
+exports.checkAndRecordReplay = checkAndRecordReplay;
+exports.clearCryptoKeyCache = clearCryptoKeyCache;
+exports.computeSubtleHmac = computeSubtleHmac;
+exports.createInMemoryReplayStore = createInMemoryReplayStore;
+exports.createWebhookHandler = createWebhookHandler;
+exports.extractRawBody = extractRawBody;
+exports.getCachedCryptoKey = getCachedCryptoKey;
+exports.getCryptoKeyCacheSize = getCryptoKeyCacheSize;
+exports.githubPlugin = githubPlugin;
+exports.hexToBytes = hexToBytes;
+exports.parseGithubSignature = parseGithubSignature;
+exports.parseShopifySignature = parseShopifySignature;
+exports.parseStripeSignature = parseStripeSignature;
+exports.resolveWebhookEventId = resolveWebhookEventId;
+exports.shopifyPlugin = shopifyPlugin;
+exports.stripePlugin = stripePlugin;
+exports.timingSafeEqual = timingSafeEqual;
+exports.validateTimestampTolerance = validateTimestampTolerance;
+exports.verifyGithubWebhook = verifyGithubWebhook;
+exports.verifyShopifyWebhook = verifyShopifyWebhook;
+exports.verifyStripeWebhook = verifyStripeWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;