@amirabaris/webhook-kit 0.0.0-stage → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,1091 @@
+/**
+ * Base error class for all webhook-kit errors.
+ */
+export declare class WebhookKitError extends Error {
+  readonly code: string;
+  constructor(message: string, code?: string);
+}
+/**
+ * Thrown or returned when signature verification fails (e.g. invalid HMAC or mismatched hash).
+ */
+export declare class SignatureVerificationError extends WebhookKitError {
+  constructor(message?: string);
+}
+/**
+ * Thrown when the signature header is missing or malformed.
+ */
+export declare class InvalidSignatureHeaderError extends WebhookKitError {
+  constructor(message?: string);
+}
+/**
+ * Thrown when the timestamp outside the allowed tolerance window (replay attack protection).
+ */
+export declare class TimestampToleranceError extends WebhookKitError {
+  readonly timestamp: number;
+  readonly toleranceSeconds: number;
+  constructor(timestamp: number, toleranceSeconds: number, message?: string);
+}
+/**
+ * Thrown when extracting raw payload from request or stream fails.
+ */
+export declare class PayloadExtractionError extends WebhookKitError {
+  constructor(message?: string);
+}
+/**
+ * Thrown or returned when a webhook event ID has already been processed in the replay store.
+ */
+export declare class ReplayAttackError extends WebhookKitError {
+  readonly eventId: string;
+  constructor(eventId: string, message?: string);
+}
+/**
+ * Supported raw body representations across runtimes (Node, Edge, Browser, Bun, Deno).
+ */
+export type RawBody = string | Uint8Array | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | Request;
+/**
+ * Standard or framework headers representation.
+ */
+export type HeaderRecord = Record<string, string | string[] | undefined> | Headers;
+/**
+ * Supported HMAC cryptographic algorithms in Web Cryptography API.
+ */
+export type SupportedAlgorithm = "SHA-256" | "SHA-384" | "SHA-512" | "SHA-1";
+/**
+ * Built-in webhook provider names supported by the unified verification API.
+ */
+export type BuiltinProviderName = "stripe" | "github" | "shopify";
+/**
+ * Lightweight idempotency / replay store interface (`has(eventId)` / `set(eventId, ttl)`).
+ * Supports both synchronous (in-memory) and asynchronous (Redis, Upstash, Cloudflare KV) implementations.
+ */
+export interface WebhookReplayStore {
+  /**
+   * Returns `true` if `eventId` is already present and unexpired in the store.
+   *
+   * @param eventId - Unique webhook event or delivery identifier.
+   */
+  has(eventId: string): boolean | Promise<boolean>;
+  /**
+   * Records `eventId` in the store with the given time-to-live in seconds.
+   *
+   * @param eventId - Unique webhook event or delivery identifier.
+   * @param ttlSeconds - Time-to-live in seconds before the entry expires.
+   */
+  set(eventId: string, ttlSeconds: number): unknown | Promise<unknown>;
+  /**
+   * Atomically records `eventId` with TTL if it does not already exist in the store (set-if-not-exists).
+   *
+   * @param eventId - Unique webhook event or delivery identifier.
+   * @param ttlSeconds - Time-to-live in seconds before expiration.
+   * @returns `true` if newly recorded, `false` if already present in the store.
+   */
+  setNx?(eventId: string, ttlSeconds: number): boolean | Promise<boolean>;
+  /**
+   * Optional method to remove a specific event ID from the store.
+   *
+   * @param eventId - Unique webhook event or delivery identifier.
+   * @returns `true` if the entry existed and was removed, `false` otherwise.
+   */
+  delete?(eventId: string): boolean | Promise<boolean>;
+  /**
+   * Optional method to clear all tracked event IDs from the store.
+   */
+  clear?(): void | Promise<void>;
+}
+/**
+ * Options for generic or provider-specific webhook signature verification.
+ */
+export interface WebhookVerifyOptions {
+  /**
+   * The raw incoming body (Request, string, buffer, or stream).
+   * MUST NOT be pre-parsed JSON.
+   */
+  body: RawBody;
+  /**
+   * Signature string provided in the webhook header.
+   * Optional when `headers` or a `Request` `body` containing the signature header is passed.
+   */
+  signature?: string;
+  /**
+   * Shared secret key or signing secret.
+   */
+  secret: string | Uint8Array;
+  /**
+   * Optional built-in provider name ('stripe', 'github', 'shopify') or custom provider plugin.
+   * When omitted, generic HMAC verification is performed.
+   */
+  provider?: BuiltinProviderName | WebhookProviderPlugin<unknown, never>;
+  /**
+   * Cryptographic hash algorithm for generic HMAC verification. Defaults to 'SHA-256'.
+   */
+  algorithm?: SupportedAlgorithm;
+  /**
+   * Signature digest encoding for generic HMAC verification. Defaults to 'hex'.
+   */
+  encoding?: "hex" | "base64";
+  /**
+   * Optional incoming HTTP headers if provider or generic verifier requires extracting metadata.
+   */
+  headers?: HeaderRecord;
+  /**
+   * Maximum allowed age of the webhook in seconds to mitigate replay attacks.
+   */
+  toleranceSeconds?: number;
+  /**
+   * Timestamp extracted from header or options (Unix seconds).
+   */
+  timestamp?: number | string;
+  /**
+   * Current Unix timestamp in seconds (defaults to Math.floor(Date.now() / 1000)).
+   * Useful for deterministic testing.
+   */
+  currentTimestamp?: number;
+  /**
+   * Optional idempotency / replay store (`has(eventId)` / `set(eventId, ttl)`) to reject duplicate webhooks.
+   */
+  store?: WebhookReplayStore;
+  /**
+   * Optional explicit webhook event ID for idempotency / replay store tracking.
+   * When omitted, `webhook-kit` automatically extracts the delivery ID from headers or payload.
+   */
+  eventId?: string;
+  /**
+   * Optional TTL in seconds for entries recorded in `store` (defaults to `toleranceSeconds` or `300`).
+   */
+  storeTtlSeconds?: number;
+  /**
+   * Whether to automatically parse the verified body as JSON. Defaults to true.
+   */
+  parseJson?: boolean;
+  /**
+   * If true, throws a WebhookKitError on failure instead of returning `{ valid: false, error }`.
+   */
+  throwOnError?: boolean;
+}
+/**
+ * Successful outcome returned by verification operations.
+ */
+export interface WebhookVerificationSuccess<T = unknown> {
+  /**
+   * True when signature matches and all validations (e.g. timestamp) passed.
+   */
+  valid: true;
+  /**
+   * Exact raw body string used in the HMAC calculation.
+   */
+  rawBody: string;
+  /**
+   * Typed parsed JSON payload (or undefined if parseJson is false or body is non-JSON).
+   */
+  payload: T;
+  /**
+   * Verified timestamp if present in the signature header or options.
+   */
+  timestamp?: number;
+  /**
+   * Extracted or supplied webhook event ID if resolved.
+   */
+  eventId?: string;
+  /**
+   * Undefined on successful verification.
+   */
+  error?: undefined;
+}
+/**
+ * Failed outcome returned by verification operations.
+ */
+export interface WebhookVerificationFailure {
+  /**
+   * False when signature or timestamp validation failed.
+   */
+  valid: false;
+  /**
+   * Exact raw body string used in the HMAC calculation.
+   */
+  rawBody: string;
+  /**
+   * Undefined on failed verification.
+   */
+  payload?: undefined;
+  /**
+   * Extracted timestamp if parsed prior to failure.
+   */
+  timestamp?: number;
+  /**
+   * Extracted or supplied webhook event ID if resolved prior to failure.
+   */
+  eventId?: string;
+  /**
+   * Verification error details explaining the failure.
+   */
+  error: WebhookKitError;
+}
+/**
+ * Discriminated union outcome returned by verification operations.
+ * Narrowing via `if (result.valid)` narrows `result.payload` to `T`,
+ * while `if (!result.valid)` narrows `result.error` to `WebhookKitError`.
+ */
+export type WebhookVerificationResult<T = unknown> = WebhookVerificationSuccess<T> | WebhookVerificationFailure;
+/**
+ * Interface for extensible provider plugins (Stripe, GitHub, Shopify, etc.).
+ */
+export interface WebhookProviderPlugin<TPayload = unknown, TOptions = unknown> {
+  /**
+   * Unique name of the provider plugin (e.g. 'stripe', 'github', 'shopify').
+   */
+  readonly name: string;
+  /**
+   * Verify an incoming webhook for this specific provider format.
+   */
+  verify(options: TOptions): Promise<WebhookVerificationResult<TPayload>>;
+}
+/**
+ * Configuration options for `InMemoryReplayStore` / `createInMemoryReplayStore`.
+ */
+export interface InMemoryReplayStoreOptions {
+  /**
+   * Maximum number of entries retained in memory before evicting expired or oldest entries.
+   * Defaults to `10_000`.
+   */
+  maxSize?: number;
+  /**
+   * Default time-to-live in seconds when `ttlSeconds` is omitted or invalid.
+   * Defaults to `300` (5 minutes).
+   */
+  defaultTtlSeconds?: number;
+  /**
+   * Optional clock function returning current time in milliseconds (defaults to `Date.now`).
+   * Useful for deterministic unit testing.
+   */
+  now?: () => number;
+}
+/**
+ * Options for checking and recording an event ID in a `WebhookReplayStore`.
+ */
+export interface VerifyReplayStoreOptions {
+  /**
+   * Optional replay store instance.
+   */
+  store?: WebhookReplayStore;
+  /**
+   * Resolved event ID to check and record.
+   */
+  eventId?: string;
+  /**
+   * Explicit TTL in seconds for `store.set(eventId, ttl)`.
+   */
+  storeTtlSeconds?: number;
+  /**
+   * Fallback tolerance window in seconds used when `storeTtlSeconds` is not provided.
+   */
+  toleranceSeconds?: number;
+}
+export declare const DEFAULT_REPLAY_STORE_MAX_SIZE = 10000;
+export declare const DEFAULT_REPLAY_STORE_TTL_SECONDS = 300;
+export declare const GENERIC_EVENT_ID_HEADERS: readonly ["x-webhook-id", "webhook-id", "svix-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.
+ */
+export declare class InMemoryReplayStore implements WebhookReplayStore {
+  private readonly maxSize;
+  private readonly defaultTtlSeconds;
+  private readonly now;
+  private readonly entries;
+  private lastPruneMs;
+  constructor(options?: InMemoryReplayStoreOptions);
+  /**
+   * 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: string): boolean;
+  /**
+   * 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: string, ttlSeconds?: number): void;
+  /**
+   * Atomically records `eventId` with TTL if it does not already exist in the store (set-if-not-exists).
+   *
+   * @param eventId - Unique webhook event or delivery identifier.
+   * @param ttlSeconds - Time-to-live in seconds before expiration.
+   * @returns `true` if newly recorded, `false` if already present in the store.
+   */
+  setNx(eventId: string, ttlSeconds?: number): boolean;
+  /**
+   * 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: string): boolean;
+  /**
+   * Clears all tracked event IDs from the store.
+   */
+  clear(): void;
+  /**
+   * Removes all expired entries from the store and returns the number of purged entries.
+   *
+   * @returns Count of expired entries removed.
+   */
+  prune(): number;
+  /**
+   * Returns the current number of entries stored in the underlying map.
+   */
+  get size(): number;
+  /**
+   * Returns the maximum capacity of the store.
+   */
+  get capacity(): number;
+  /**
+   * Prepares a map slot for insertion by evicting an existing key or pruning capacity.
+   *
+   * @param eventId - Candidate event ID key.
+   */
+  private prepareInsertSlot;
+  /**
+   * Fast-path check from the head of the insertion-ordered Map to purge expired entries.
+   *
+   * @param currentMs - Current time in milliseconds.
+   */
+  private evictHeadExpired;
+  private evictExpiredOrOldest;
+}
+/**
+ * Creates a new `InMemoryReplayStore` instance with optional capacity and TTL settings.
+ *
+ * @param options - Optional capacity, default TTL, and clock configuration.
+ * @returns Configured `InMemoryReplayStore` instance.
+ */
+export declare function createInMemoryReplayStore(options?: InMemoryReplayStoreOptions): InMemoryReplayStore;
+/**
+ * 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`.
+ */
+export declare function resolveWebhookEventId(options: {
+  eventId?: string;
+  headers?: HeaderRecord;
+  body?: RawBody;
+  payload?: unknown;
+  rawBody?: string;
+}, headerCandidates?: readonly string[]): string | undefined;
+/**
+ * Verifies that `eventId` has not already been seen in `store`, and records it with a TTL if unseen.
+ * Automatically leverages atomic `setNx` when supported, or serializes in-flight checks to prevent
+ * TOCTOU race conditions under high concurrency.
+ *
+ * @param options - Store instance, resolved `eventId`, and TTL configuration.
+ * @returns `ReplayAttackError` if `eventId` is already present in `store`, or `null` if unseen / no store.
+ */
+export declare function checkAndRecordReplay(options: VerifyReplayStoreOptions): Promise<ReplayAttackError | null>;
+export interface ProviderVerifyOptions {
+  /**
+   * Raw body input (Request, string, buffer). Must not be pre-parsed.
+   */
+  body: RawBody;
+  /**
+   * Webhook signing secret provided by the platform dashboard.
+   */
+  secret: string | Uint8Array;
+  /**
+   * Request headers or header value containing the signature.
+   */
+  headers?: HeaderRecord;
+  /**
+   * Explicit signature header value if already extracted.
+   */
+  signature?: string;
+  /**
+   * Tolerance in seconds for replay-attack prevention (where supported).
+   */
+  toleranceSeconds?: number;
+  /**
+   * Optional idempotency / replay store (`has(eventId)` / `set(eventId, ttl)`) to reject duplicate webhooks.
+   */
+  store?: WebhookReplayStore;
+  /**
+   * Optional explicit webhook event ID for idempotency / replay store tracking.
+   */
+  eventId?: string;
+  /**
+   * Optional TTL in seconds for entries recorded in `store` (defaults to `toleranceSeconds` or `300`).
+   */
+  storeTtlSeconds?: number;
+  /**
+   * Whether to automatically parse the verified body as JSON. Defaults to true.
+   */
+  parseJson?: boolean;
+}
+/**
+ * Standard shape of a GitHub Webhook Event payload.
+ */
+export interface GithubWebhookEvent {
+  action?: string;
+  sender?: Record<string, unknown>;
+  repository?: Record<string, unknown>;
+  organization?: Record<string, unknown>;
+  installation?: Record<string, unknown>;
+  zen?: string;
+  hook_id?: number;
+  hook?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * Options for GitHub webhook verification.
+ */
+export interface GithubVerifyOptions extends ProviderVerifyOptions {
+  /**
+   * X-Hub-Signature-256 header format: `sha256=d57c68d10b284e3d...`
+   */
+  signature?: string;
+  /**
+   * If true, throws errors rather than returning `{ valid: false, error }`.
+   */
+  throwOnError?: boolean;
+  /**
+   * Whether to automatically parse the verified body as JSON. Defaults to true.
+   */
+  parseJson?: boolean;
+}
+export declare const GITHUB_SIGNATURE_PREFIX = "sha256=";
+export declare const GITHUB_SIGNATURE_HEX_REGEX: RegExp;
+export declare const GITHUB_EVENT_ID_HEADERS: readonly ["x-github-delivery", "x-webhook-id", "webhook-id"];
+/**
+ * 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.
+ */
+export declare function parseGithubSignature(header: string): string;
+/**
+ * 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.
+ */
+export declare function resolveGithubSignatureHeader(options: GithubVerifyOptions): string | undefined;
+/**
+ * Validates preconditions for GitHub webhook verification.
+ *
+ * @param options - GitHub verification options.
+ * @param rawHeader - Resolved header string.
+ * @returns Error if preconditions fail, null otherwise.
+ */
+export declare function validateGithubPreconditions(options: GithubVerifyOptions, rawHeader: string | undefined): WebhookKitError | null;
+/**
+ * Safely parses the raw signature header without uncaught exceptions.
+ *
+ * @param rawHeader - Raw header string.
+ * @returns Extracted signature string or error object.
+ */
+export declare function safeParseGithubHeader(rawHeader: string): {
+  signature: string;
+} | {
+  error: WebhookKitError;
+};
+/**
+ * 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.
+ */
+export declare function verifyGithubWebhook<T = GithubWebhookEvent>(options: GithubVerifyOptions): Promise<WebhookVerificationResult<T>>;
+/**
+ * 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.
+ */
+export declare function assertGithubWebhook<T = GithubWebhookEvent>(options: GithubVerifyOptions): Promise<T>;
+/**
+ * Webhook provider plugin for GitHub.
+ */
+export declare const githubPlugin: WebhookProviderPlugin<GithubWebhookEvent, GithubVerifyOptions>;
+/**
+ * Standard shape of a Shopify Webhook Event payload.
+ */
+export interface ShopifyWebhookEvent {
+  id?: number | string;
+  admin_graphql_api_id?: string;
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
+/**
+ * Options for Shopify webhook verification.
+ */
+export interface ShopifyVerifyOptions extends ProviderVerifyOptions {
+  /**
+   * X-Shopify-Hmac-Sha256 base64-encoded signature header.
+   */
+  signature?: string;
+  /**
+   * If true, throws errors rather than returning `{ valid: false, error }`.
+   */
+  throwOnError?: boolean;
+  /**
+   * Whether to automatically parse the verified body as JSON. Defaults to true.
+   */
+  parseJson?: boolean;
+}
+export declare const BASE64_REGEX: RegExp;
+export declare const SHOPIFY_EVENT_ID_HEADERS: readonly ["x-shopify-webhook-id", "x-webhook-id", "webhook-id"];
+/**
+ * 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.
+ */
+export declare function parseShopifySignature(header: string): string;
+/**
+ * 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.
+ */
+export declare function resolveShopifySignatureHeader(options: ShopifyVerifyOptions): string | undefined;
+/**
+ * Validates preconditions for Shopify webhook verification.
+ *
+ * @param options - Shopify verification options.
+ * @param rawHeader - Resolved header string.
+ * @returns Error if preconditions fail, null otherwise.
+ */
+export declare function validateShopifyPreconditions(options: ShopifyVerifyOptions, rawHeader: string | undefined): WebhookKitError | null;
+/**
+ * Safely parses the raw signature header without uncaught exceptions.
+ *
+ * @param rawHeader - Raw header string.
+ * @returns Extracted Base64 signature string or error object.
+ */
+export declare function safeParseShopifyHeader(rawHeader: string): {
+  signature: string;
+} | {
+  error: WebhookKitError;
+};
+/**
+ * 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.
+ */
+export declare function verifyShopifyWebhook<T = ShopifyWebhookEvent>(options: ShopifyVerifyOptions): Promise<WebhookVerificationResult<T>>;
+/**
+ * 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.
+ */
+export declare function assertShopifyWebhook<T = ShopifyWebhookEvent>(options: ShopifyVerifyOptions): Promise<T>;
+/**
+ * Webhook provider plugin for Shopify.
+ */
+export declare const shopifyPlugin: WebhookProviderPlugin<ShopifyWebhookEvent, ShopifyVerifyOptions>;
+/**
+ * Parsed components of a `Stripe-Signature` header.
+ */
+export interface StripeParsedSignatureHeader {
+  /**
+   * Extracted Unix timestamp in seconds.
+   */
+  timestamp: number;
+  /**
+   * One or more valid v1 HMAC-SHA256 signatures.
+   */
+  signatures: string[];
+  /**
+   * Optional v0 legacy signatures if present.
+   */
+  v0Signatures?: string[];
+}
+/**
+ * Standard shape of a Stripe Webhook Event payload.
+ */
+export interface StripeWebhookEvent {
+  id: string;
+  object: string;
+  type: string;
+  created: number;
+  data: {
+    object: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  livemode?: boolean;
+  pending_webhooks?: number;
+  request?: {
+    id: string | null;
+    idempotency_key: string | null;
+  };
+  [key: string]: unknown;
+}
+/**
+ * Options for Stripe webhook verification.
+ */
+export interface StripeVerifyOptions extends ProviderVerifyOptions {
+  /**
+   * Stripe-Signature header format: `t=1492774577,v1=5257a869e7ecebeda32affa62cd4923...`
+   */
+  signature?: string;
+  /**
+   * Timestamp tolerance window in seconds (Stripe default is 300s).
+   * Pass 0 to disable replay protection check.
+   */
+  toleranceSeconds?: number;
+  /**
+   * Current Unix timestamp in seconds (defaults to Math.floor(Date.now() / 1000)).
+   * Useful for deterministic testing.
+   */
+  currentTimestamp?: number;
+  /**
+   * If true, throws errors rather than returning `{ valid: false, error }`.
+   */
+  throwOnError?: boolean;
+}
+export declare const STRIPE_EVENT_ID_HEADERS: readonly ["x-stripe-webhook-id", "x-webhook-id", "webhook-id"];
+/**
+ * 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.
+ */
+export declare function parseStripeSignature(header: string): StripeParsedSignatureHeader;
+/**
+ * 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.
+ */
+export declare function validateTimestampTolerance(timestamp: number, toleranceSeconds?: number, currentTimestamp?: number): void;
+/**
+ * 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.
+ */
+export declare function resolveStripeSignatureHeader(options: StripeVerifyOptions): string | undefined;
+/**
+ * Validates preconditions for Stripe webhook verification.
+ *
+ * @param options - Stripe verification options.
+ * @param rawHeader - Resolved header string.
+ * @returns Error if preconditions fail, null otherwise.
+ */
+export declare function validateStripePreconditions(options: StripeVerifyOptions, rawHeader: string | undefined): WebhookKitError | null;
+/**
+ * Safely parses the raw signature header without uncaught exceptions.
+ *
+ * @param rawHeader - Raw header string.
+ * @returns Parsed header or error object.
+ */
+export declare function safeParseStripeHeader(rawHeader: string): StripeParsedSignatureHeader | {
+  error: WebhookKitError;
+};
+/**
+ * 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.
+ */
+export declare function checkStripeTolerance(timestamp: number, options: StripeVerifyOptions): TimestampToleranceError | null;
+/**
+ * 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.
+ */
+export declare function matchesAnyStripeSignature(expectedSignature: string, candidates: string[]): boolean;
+/**
+ * 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
+ */
+export declare function verifyStripeWebhook<T = StripeWebhookEvent>(options: StripeVerifyOptions): Promise<WebhookVerificationResult<T>>;
+/**
+ * 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.
+ */
+export declare function assertStripeWebhook<T = StripeWebhookEvent>(options: StripeVerifyOptions): Promise<T>;
+/**
+ * Webhook provider plugin for Stripe.
+ */
+export declare const stripePlugin: WebhookProviderPlugin<StripeWebhookEvent, StripeVerifyOptions>;
+/**
+ * Built-in provider plugin registry keyed by lowercase provider name.
+ */
+export declare const PROVIDER_REGISTRY: Record<BuiltinProviderName, WebhookProviderPlugin<unknown, never>>;
+/**
+ * Verifies an incoming Stripe webhook signature via the unified verification API.
+ */
+export declare function verifyWebhookSignature<T = StripeWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "stripe";
+}): Promise<WebhookVerificationResult<T>>;
+/**
+ * Verifies an incoming GitHub webhook signature via the unified verification API.
+ */
+export declare function verifyWebhookSignature<T = GithubWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "github";
+}): Promise<WebhookVerificationResult<T>>;
+/**
+ * Verifies an incoming Shopify webhook signature via the unified verification API.
+ */
+export declare function verifyWebhookSignature<T = ShopifyWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "shopify";
+}): Promise<WebhookVerificationResult<T>>;
+/**
+ * Verifies an incoming webhook signature using a custom `WebhookProviderPlugin`.
+ */
+export declare function verifyWebhookSignature<T>(options: WebhookVerifyOptions & {
+  provider: WebhookProviderPlugin<T, never>;
+}): Promise<WebhookVerificationResult<T>>;
+/**
+ * Verifies an incoming webhook signature against the raw request body using constant-time HMAC check.
+ *
+ * @param options - Verification options including body, signature, secret, and optional provider or tolerance
+ * @returns Verification result object with validity, extracted raw body, and narrowed payload or error
+ */
+export declare function verifyWebhookSignature<T = unknown>(options: WebhookVerifyOptions): Promise<WebhookVerificationResult<T>>;
+/**
+ * Asserts that an incoming Stripe webhook signature is valid, returning the typed payload or throwing.
+ */
+export declare function assertWebhookSignature<T = StripeWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "stripe";
+}): Promise<T>;
+/**
+ * Asserts that an incoming GitHub webhook signature is valid, returning the typed payload or throwing.
+ */
+export declare function assertWebhookSignature<T = GithubWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "github";
+}): Promise<T>;
+/**
+ * Asserts that an incoming Shopify webhook signature is valid, returning the typed payload or throwing.
+ */
+export declare function assertWebhookSignature<T = ShopifyWebhookEvent>(options: WebhookVerifyOptions & {
+  provider: "shopify";
+}): Promise<T>;
+/**
+ * Asserts that an incoming webhook signature is valid using a custom `WebhookProviderPlugin`.
+ */
+export declare function assertWebhookSignature<T>(options: WebhookVerifyOptions & {
+  provider: WebhookProviderPlugin<T, never>;
+}): Promise<T>;
+/**
+ * Asserts that an incoming webhook signature is valid, throwing a `WebhookKitError` if invalid.
+ * Returns the typed payload if valid and parsed.
+ *
+ * @throws {SignatureVerificationError} If signature verification fails
+ * @throws {TimestampToleranceError} If timestamp tolerance is exceeded
+ */
+export declare function assertWebhookSignature<T = unknown>(options: WebhookVerifyOptions): Promise<T>;
+/**
+ * Structural duck-type for Hono's `Context` (and compatible edge routers that expose
+ * the underlying Web Standard `Request` at `req.raw`).
+ */
+export interface WebhookLikeContext {
+  readonly req: {
+    readonly raw: Request;
+  };
+}
+/**
+ * Supported first-argument inputs to a universal webhook route handler:
+ * - Web Standard `Request` (Next.js App Router, Remix, SvelteKit, Astro, Cloudflare Workers, Bun, Deno)
+ * - Framework context object exposing `{ req: { raw: Request } }` (Hono)
+ */
+export type WebhookRequestInput = Request | WebhookLikeContext;
+/**
+ * Static secret value or dynamic secret resolver function.
+ */
+export type SecretResolver<TContext = Request> = string | Uint8Array | ((context: TContext, request: Request) => string | Uint8Array | Promise<string | Uint8Array>);
+/**
+ * Static replay store instance or dynamic store resolver function.
+ */
+export type ReplayStoreResolver<TContext = Request> = WebhookReplayStore | ((context: TContext, request: Request) => WebhookReplayStore | undefined | Promise<WebhookReplayStore | undefined>);
+/**
+ * Metadata passed as the second argument to `onEvent` alongside the verified payload.
+ */
+export interface WebhookEventMeta<TContext = Request> {
+  readonly context: TContext;
+  readonly request: Request;
+  readonly rawBody: string;
+  readonly timestamp?: number;
+  readonly eventId?: string;
+}
+/**
+ * Metadata passed as the second argument to `onError` when verification fails.
+ */
+export interface WebhookErrorMeta<TContext = Request> {
+  readonly context: TContext;
+  readonly request: Request;
+  readonly rawBody?: string;
+  readonly timestamp?: number;
+  readonly eventId?: string;
+}
+/**
+ * Return value allowed from `onEvent`.
+ */
+export type WebhookHandlerReturn = Response | Record<string, unknown> | void | undefined;
+/**
+ * Configuration options for `createWebhookHandler`.
+ */
+export interface WebhookHandlerOptions<TPayload = unknown, TContext extends WebhookRequestInput = Request> {
+  /**
+   * Optional built-in provider name (`'stripe'`, `'github'`, `'shopify'`) or custom provider plugin.
+   * When omitted, generic HMAC verification is performed.
+   */
+  provider?: BuiltinProviderName | WebhookProviderPlugin<TPayload, never>;
+  /**
+   * Shared signing secret or dynamic resolver function receiving `(context, request)`.
+   */
+  secret: SecretResolver<TContext>;
+  /**
+   * Optional idempotency / replay store (`has(eventId)` / `set(eventId, ttl)`) or dynamic resolver function.
+   */
+  store?: ReplayStoreResolver<TContext>;
+  /**
+   * Optional explicit webhook event ID for idempotency / replay store tracking.
+   */
+  eventId?: string;
+  /**
+   * Optional TTL in seconds for entries recorded in `store` (defaults to `toleranceSeconds` or `300`).
+   */
+  storeTtlSeconds?: number;
+  /**
+   * Callback invoked after the webhook signature and timestamp have been verified.
+   */
+  onEvent: (event: TPayload, meta: WebhookEventMeta<TContext>) => WebhookHandlerReturn | Promise<WebhookHandlerReturn>;
+  /**
+   * Optional custom error responder invoked when signature verification or body extraction fails.
+   */
+  onError?: (error: WebhookKitError, meta: WebhookErrorMeta<TContext>) => Response | Promise<Response>;
+  /**
+   * Cryptographic hash algorithm for generic HMAC verification. Defaults to `'SHA-256'`.
+   */
+  algorithm?: SupportedAlgorithm;
+  /**
+   * Signature digest encoding for generic HMAC verification. Defaults to `'hex'`.
+   */
+  encoding?: "hex" | "base64";
+  /**
+   * Maximum allowed age of the webhook in seconds to mitigate replay attacks.
+   */
+  toleranceSeconds?: number;
+  /**
+   * Current Unix timestamp in seconds (defaults to `Math.floor(Date.now() / 1000)`).
+   */
+  currentTimestamp?: number;
+  /**
+   * Whether to automatically parse the verified body as JSON. Defaults to `true`.
+   */
+  parseJson?: boolean;
+}
+/**
+ * Universal webhook route handler function produced by `createWebhookHandler`.
+ */
+export type UniversalWebhookHandler<TContext extends WebhookRequestInput = Request> = (input: TContext) => Promise<Response>;
+/**
+ * Creates a universal Stripe webhook route handler for Next.js App Router, Hono, and WinterCG runtimes.
+ */
+export declare function createWebhookHandler<TPayload = StripeWebhookEvent, TContext extends WebhookRequestInput = Request>(options: WebhookHandlerOptions<TPayload, TContext> & {
+  provider: "stripe";
+}): UniversalWebhookHandler<TContext>;
+/**
+ * Creates a universal GitHub webhook route handler for Next.js App Router, Hono, and WinterCG runtimes.
+ */
+export declare function createWebhookHandler<TPayload = GithubWebhookEvent, TContext extends WebhookRequestInput = Request>(options: WebhookHandlerOptions<TPayload, TContext> & {
+  provider: "github";
+}): UniversalWebhookHandler<TContext>;
+/**
+ * Creates a universal Shopify webhook route handler for Next.js App Router, Hono, and WinterCG runtimes.
+ */
+export declare function createWebhookHandler<TPayload = ShopifyWebhookEvent, TContext extends WebhookRequestInput = Request>(options: WebhookHandlerOptions<TPayload, TContext> & {
+  provider: "shopify";
+}): UniversalWebhookHandler<TContext>;
+/**
+ * Creates a universal webhook route handler using a custom `WebhookProviderPlugin`.
+ */
+export declare function createWebhookHandler<TPayload, TContext extends WebhookRequestInput = Request>(options: WebhookHandlerOptions<TPayload, TContext> & {
+  provider: WebhookProviderPlugin<TPayload, never>;
+}): UniversalWebhookHandler<TContext>;
+/**
+ * Creates a universal webhook route handler that unwraps a Web Standard `Request` (Next.js App Router,
+ * Cloudflare Workers, Remix, Bun, Deno) or `{ req: { raw: Request } }` context (Hono), verifies the
+ * cryptographic signature, and dispatches the typed payload to `onEvent`.
+ *
+ * @param options - Provider, secret resolver, event handler, and optional verification settings.
+ * @returns Universal async route handler `(input: TContext) => Promise<Response>`.
+ */
+export declare function createWebhookHandler<TPayload = unknown, TContext extends WebhookRequestInput = Request>(options: WebhookHandlerOptions<TPayload, TContext>): UniversalWebhookHandler<TContext>;
+/**
+ * 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.
+ */
+export declare function extractRawBody(body: RawBody): Promise<string>;
+/**
+ * Web Cryptography API helper utilities using globalThis.crypto.subtle.
+ * Provides zero-dependency, edge-compatible HMAC computation and constant-time verification.
+ */
+/**
+ * Output encodings supported by `computeSubtleHmac`.
+ */
+export type SubtleHmacEncoding = "hex" | "base64" | "uint8array" | "binary";
+/**
+ * Options for configuring HMAC computation output.
+ */
+export interface SubtleHmacOptions {
+  /**
+   * Output encoding format. Defaults to `'uint8array'`.
+   */
+  encoding?: SubtleHmacEncoding;
+  /**
+   * Whether to bypass the in-memory CryptoKey cache. Defaults to `false`.
+   */
+  bypassCache?: boolean;
+}
+/**
+ * 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.
+ */
+export declare class CryptoKeyLruCache {
+  private readonly maxSize;
+  private readonly map;
+  constructor(maxSize?: number);
+  get(key: string): Promise<CryptoKey> | undefined;
+  set(key: string, value: Promise<CryptoKey>): void;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  get size(): number;
+  get capacity(): number;
+}
+/**
+ * Clears all compiled WebCrypto HMAC keys from the global key cache.
+ */
+export declare function clearCryptoKeyCache(): void;
+/**
+ * Returns the current number of compiled WebCrypto HMAC keys stored in the global key cache.
+ */
+export declare function getCryptoKeyCacheSize(): number;
+/**
+ * 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.
+ */
+export declare function getCachedCryptoKey(algorithm: string, secret: string | Uint8Array, cache?: CryptoKeyLruCache): Promise<CryptoKey>;
+/**
+ * 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.
+ */
+export declare function timingSafeEqual(a: Uint8Array | string, b: Uint8Array | string): boolean;
+/**
+ * Computes an HMAC digest using `crypto.subtle` across modern JavaScript runtimes.
+ *
+ * @param algorithm HMAC digest algorithm (`'SHA-256'`, `'SHA-384'`, `'SHA-512'`, `'SHA-1'`).
+ * @param secret Shared secret key as UTF-8 string or raw bytes.
+ * @param data Raw payload string or bytes.
+ * @param encodingOrOptions Output encoding (`'uint8array'`, `'hex'`, `'base64'`) or options object.
+ * @returns Raw HMAC digest bytes (`Uint8Array`) or encoded digest string.
+ */
+export declare function computeSubtleHmac(algorithm: string, secret: string | Uint8Array, data: string | Uint8Array, encodingOrOptions?: "uint8array" | "binary" | {
+  encoding?: "uint8array" | "binary";
+  bypassCache?: boolean;
+}): Promise<Uint8Array>;
+export declare function computeSubtleHmac(algorithm: string, secret: string | Uint8Array, data: string | Uint8Array, encodingOrOptions: "hex" | "base64" | {
+  encoding: "hex" | "base64";
+  bypassCache?: boolean;
+}): Promise<string>;
+/**
+ * Converts a `Uint8Array` into a lowercase hexadecimal string.
+ *
+ * @param bytes Input byte array.
+ * @returns Lowercase hexadecimal string.
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Converts a hexadecimal string into a `Uint8Array`.
+ *
+ * @param hex Hexadecimal string (with optional `0x` prefix).
+ * @returns Decoded byte array.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Converts a `Uint8Array` into a Base64-encoded string using standard Web APIs.
+ *
+ * @param bytes Input byte array.
+ * @returns Base64-encoded string.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Converts a Base64-encoded string into a `Uint8Array` using standard Web APIs.
+ *
+ * @param base64 Base64-encoded string.
+ * @returns Decoded byte array.
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Asserts that a header value is a non-empty string.
+ *
+ * @param header - Candidate header value.
+ * @param errorMessage - Error message to throw if header is invalid or missing.
+ */
+export declare function assertNonEmptyHeader(header: unknown, errorMessage: string): asserts header is string;
+/**
+ * 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.
+ * @param eventId - Optional webhook event ID.
+ * @returns Failed verification result.
+ */
+export declare function failVerification(rawBody: string, error: WebhookKitError, throwOnError?: boolean, timestamp?: number, eventId?: string): WebhookVerificationResult<never>;
+/**
+ * Attempts to parse the raw body as JSON.
+ *
+ * @param rawBody - Raw body payload string.
+ * @returns Parsed payload or undefined.
+ */
+export declare function tryParseJson<T>(rawBody: string): T | undefined;
+//# sourceMappingURL=index.d.mts.map