/**
 * Result of verifying an inbound webhook signature.
 */
interface WebhookVerificationResult {
  /**
   * Machine-readable reason when {@link WebhookVerificationResult.valid} is `false`.
   */
  reason?: string;
  /**
   * Whether the signature (and, when applicable, the timestamp) is valid.
   */
  valid: boolean;
}
/**
 * Headers passed to a webhook verifier. Either a plain record or a `Headers` instance.
 *
 * Lookups are case-insensitive.
 */
type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
/**
 * Shared options for verifiers that enforce a timestamp tolerance to guard against replay attacks.
 */
interface TimestampToleranceOptions {
  /**
   * Maximum allowed difference, in seconds, between the signed timestamp and the current time.
   *
   * Set to `0` to disable the replay-protection window.
   * @default 300
   */
  tolerance?: number;
}
/**
 * Options for {@link verifyMailgunWebhook}.
 *
 * Mailgun nests these three fields under a `signature` object in the webhook JSON body.
 */
interface MailgunWebhookOptions extends TimestampToleranceOptions {
  /**
   * Override the current time (milliseconds) — primarily for testing.
   */
  now?: number;
  /**
   * The HMAC value from `signature.signature`.
   */
  signature: string;
  /**
   * Your Mailgun HTTP webhook signing key (Settings → Webhooks).
   */
  signingKey: string;
  /**
   * The timestamp from `signature.timestamp` (unix seconds, as a string or number).
   */
  timestamp: number | string;
  /**
   * The token from `signature.token`.
   */
  token: string;
}
/**
 * Verifies a [Mailgun](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/#webhooks) webhook.
 *
 * Mailgun computes `HMAC-SHA256(key = signingKey, message = timestamp + token)` and sends the hex
 * digest as `signature.signature`.
 * @param options Verification inputs. See {@link MailgunWebhookOptions}.
 * @returns The verification result.
 */
declare const verifyMailgunWebhook: (options: MailgunWebhookOptions) => WebhookVerificationResult;
/**
 * Options for {@link verifyPostmarkWebhook}.
 *
 * Postmark does not sign webhook payloads; instead it supports HTTP Basic Auth credentials embedded
 * in the webhook URL (and IP allow-listing). This verifier checks the Basic Auth credentials.
 */
interface PostmarkWebhookOptions {
  /**
   * The value of the incoming `Authorization` header (e.g. `Basic dXNlcjpwYXNz`).
   */
  authorization: string | undefined;
  /**
   * The password configured on the Postmark webhook URL.
   */
  password: string;
  /**
   * The username configured on the Postmark webhook URL.
   */
  username: string;
}
/**
 * Verifies a [Postmark](https://postmarkapp.com/support/article/1213-securing-inbound-and-open-webhooks)
 * webhook by validating its HTTP Basic Auth credentials.
 * @param options Verification inputs. See {@link PostmarkWebhookOptions}.
 * @returns The verification result.
 */
declare const verifyPostmarkWebhook: (options: PostmarkWebhookOptions) => WebhookVerificationResult;
/**
 * Options for {@link verifySendGridWebhook}.
 */
interface SendGridWebhookOptions extends TimestampToleranceOptions {
  /**
   * Override the current time (milliseconds) — primarily for testing.
   */
  now?: number;
  /**
   * The raw, unparsed request body exactly as received.
   */
  payload: string;
  /**
   * The verification key from the SendGrid Event Webhook settings.
   *
   * Either the base64-encoded DER (SPKI) string SendGrid displays, or a full PEM block.
   */
  publicKey: string;
  /**
   * The value of the `X-Twilio-Email-Event-Webhook-Signature` header (base64 DER ECDSA signature).
   */
  signature: string;
  /**
   * The value of the `X-Twilio-Email-Event-Webhook-Timestamp` header (unix epoch seconds).
   */
  timestamp: string;
}
/**
 * Verifies a [SendGrid Event Webhook](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features)
 * using its ECDSA (prime256v1) signature, and rejects stale requests to prevent replay.
 *
 * The signed message is `timestamp + payload`. The signature header is the base64-encoded DER
 * ECDSA signature. The timestamp is unix epoch seconds and must fall within `tolerance` of now.
 * @param options Verification inputs. See {@link SendGridWebhookOptions}.
 * @returns The verification result.
 * @throws {EmailError} When the supplied public key cannot be parsed.
 */
declare const verifySendGridWebhook: (options: SendGridWebhookOptions) => WebhookVerificationResult;
/**
 * The subset of an Amazon SNS message envelope relevant to signature verification.
 *
 * AWS SES delivers events (deliveries, bounces, complaints) wrapped in SNS notifications.
 */
interface SnsMessage {
  [key: string]: unknown;
  Message?: string;
  MessageId?: string;
  Signature?: string;
  SignatureVersion?: string;
  SigningCertURL?: string;
  Subject?: string;
  SubscribeURL?: string;
  Timestamp?: string;
  Token?: string;
  TopicArn?: string;
  Type?: string;
}
/**
 * Resolves a signing-certificate URL to its PEM contents. Injectable for testing and caching.
 */
type CertificateResolver = (url: string) => Promise<string> | string;
/**
 * Options for {@link verifySnsMessage}.
 */
interface SnsVerifyOptions {
  /**
   * Override how the signing certificate is fetched. Defaults to a `fetch`-based resolver that
   * only accepts `https://*.amazonaws.com` URLs.
   */
  certificateResolver?: CertificateResolver;
}
/**
 * Validates that a signing-certificate URL points at an AWS SNS signing host over HTTPS.
 * @param url The `SigningCertURL` from the SNS message.
 * @returns `true` when the URL is an acceptable AWS SNS certificate endpoint.
 */
declare const isValidSigningCertUrl: (url: string) => boolean;
/**
 * Verifies the RSA signature on an Amazon SNS message (used to wrap AWS SES events).
 *
 * Signature version `1` uses SHA1, version `2` uses SHA256. The signing certificate is fetched from
 * `SigningCertURL` (validated to be an `sns.&lt;region>.amazonaws.com` HTTPS endpoint with no userinfo
 * or explicit port) unless a custom {@link CertificateResolver} is supplied.
 * @param message The parsed SNS message envelope.
 * @param options Optional overrides. See {@link SnsVerifyOptions}.
 * @returns The verification result.
 * @throws {EmailError} When the certificate cannot be resolved.
 */
declare const verifySnsMessage: (message: SnsMessage, options?: SnsVerifyOptions) => Promise<WebhookVerificationResult>;
/**
 * Options for {@link verifyStandardWebhook}.
 */
interface StandardWebhookOptions extends TimestampToleranceOptions {
  /**
   * The request headers, or the three signature headers as a plain record.
   *
   * Recognized header names (case-insensitive): `webhook-id` / `svix-id`,
   * `webhook-timestamp` / `svix-timestamp`, and `webhook-signature` / `svix-signature`.
   */
  headers: WebhookHeaders;
  /**
   * Override the current time (milliseconds) — primarily for testing.
   */
  now?: number;
  /**
   * The raw, unparsed request body exactly as received.
   *
   * Parsing and re-serializing the body changes the bytes and breaks verification.
   */
  payload: string;
  /**
   * The signing secret. Supports the `whsec_`-prefixed, base64-encoded form used by Svix/Resend,
   * or a raw secret string.
   */
  secret: string;
}
/**
 * Verifies a webhook signed according to the [Standard Webhooks](https://www.standardwebhooks.com/) spec.
 *
 * This is the scheme used by Svix and, by extension, Resend. The signed content is
 * `${id}.${timestamp}.${payload}`, HMAC-SHA256'd with the (base64-decoded) secret and base64-encoded.
 * The `webhook-signature` header may contain multiple space-separated `v1,&lt;sig>` entries; a match
 * against any one of them passes.
 * @param options Verification inputs. See {@link StandardWebhookOptions}.
 * @returns The verification result.
 */
declare const verifyStandardWebhook: (options: StandardWebhookOptions) => WebhookVerificationResult;
/**
 * Verifies a [Resend](https://resend.com/docs/dashboard/webhooks/verify-webhooks-requests) webhook.
 *
 * Resend uses Svix, so this is an alias for {@link verifyStandardWebhook} that accepts the
 * `svix-*` headers.
 * @param options Verification inputs. See {@link StandardWebhookOptions}.
 * @returns The verification result.
 */
declare const verifyResendWebhook: (options: StandardWebhookOptions) => WebhookVerificationResult;
export { type CertificateResolver, type MailgunWebhookOptions, type PostmarkWebhookOptions, type SendGridWebhookOptions, type SnsMessage, type SnsVerifyOptions, type StandardWebhookOptions, type TimestampToleranceOptions, type WebhookHeaders, type WebhookVerificationResult, isValidSigningCertUrl, verifyMailgunWebhook, verifyPostmarkWebhook, verifyResendWebhook, verifySendGridWebhook, verifySnsMessage, verifyStandardWebhook };