@amirabaris/webhook-kit 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -72,6 +72,25 @@ export interface WebhookReplayStore {
    * @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.
@@ -261,6 +280,9 @@ export interface VerifyReplayStoreOptions {
    */
   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
@@ -271,6 +293,7 @@ export declare class InMemoryReplayStore implements WebhookReplayStore {
   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.
@@ -286,6 +309,14 @@ export declare class InMemoryReplayStore implements WebhookReplayStore {
    * @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.
    *
@@ -311,6 +342,18 @@ export declare class InMemoryReplayStore implements WebhookReplayStore {
    * 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;
 }
 /**
@@ -336,6 +379,8 @@ export declare function resolveWebhookEventId(options: {
 }, 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.
@@ -410,6 +455,9 @@ export interface GithubVerifyOptions extends ProviderVerifyOptions {
    */
   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.
  *
@@ -418,6 +466,32 @@ export interface GithubVerifyOptions extends ProviderVerifyOptions {
  * @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`.
  *
@@ -467,6 +541,8 @@ export interface ShopifyVerifyOptions extends ProviderVerifyOptions {
    */
   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.
  *
@@ -475,6 +551,32 @@ export interface ShopifyVerifyOptions extends ProviderVerifyOptions {
  * @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`.
  *
@@ -557,6 +659,7 @@ export interface StripeVerifyOptions extends ProviderVerifyOptions {
    */
   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=...`).
  *
@@ -574,6 +677,46 @@ export declare function parseStripeSignature(header: string): StripeParsedSignat
  * @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.
  *
@@ -920,4 +1063,29 @@ export declare function bytesToBase64(bytes: Uint8Array): 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