/**
 * Webhook Signature Verification Middleware
 *
 * Provides middleware for verifying inbound webhook signatures using HMAC-SHA256.
 * Includes timestamp validation to prevent replay attacks.
 *
 * @packageDocumentation
 */
import type { FastifyRequest, FastifyReply, FastifyPluginAsync } from 'fastify';
/**
 * Configuration for webhook verification
 */
export interface WebhookVerifyConfig {
    /**
     * The webhook secret used for signature verification.
     * Can be a static secret or a function that retrieves the secret
     * based on the request (e.g., from database based on webhook ID).
     */
    secret: string | ((request: FastifyRequest) => Promise<string | null>);
    /**
     * Maximum age of the request in seconds (default: 300 = 5 minutes)
     */
    timestampToleranceSeconds?: number;
    /**
     * Whether to allow requests without signatures (default: false)
     * Use this only for testing or gradual rollout.
     */
    allowUnsigned?: boolean;
    /**
     * Custom error message for invalid signatures
     */
    errorMessage?: string;
    /**
     * Optional callback for logging/metrics on verification failure
     */
    onVerificationFailed?: (request: FastifyRequest, reason: string) => void;
}
/**
 * Webhook verification result
 */
export interface WebhookVerifyResult {
    valid: boolean;
    reason?: string;
    timestamp?: number;
}
/**
 * Verify webhook signature from request headers.
 *
 * @param request - The Fastify request
 * @param secret - The webhook secret
 * @param toleranceSeconds - Maximum age of request in seconds
 * @returns Verification result
 */
export declare function verifyRequestSignature(request: FastifyRequest, secret: string, toleranceSeconds?: number): WebhookVerifyResult;
/**
 * Create webhook signature verification middleware.
 *
 * This middleware verifies that incoming webhook requests have valid
 * HMAC-SHA256 signatures and timestamps within tolerance.
 *
 * ## Usage
 *
 * ```typescript
 * // Static secret
 * fastify.register(webhookVerifyPlugin, {
 *   secret: process.env.WEBHOOK_SECRET,
 * });
 *
 * // Dynamic secret lookup
 * fastify.register(webhookVerifyPlugin, {
 *   secret: async (request) => {
 *     const webhookId = request.params.id;
 *     const webhook = await getWebhook(webhookId);
 *     return webhook?.secret ?? null;
 *   },
 * });
 * ```
 *
 * @param config - Verification configuration
 * @returns Fastify preHandler hook
 */
export declare function createWebhookVerifyMiddleware(config: WebhookVerifyConfig): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
/**
 * Fastify plugin for webhook signature verification.
 *
 * Registers the webhook verification middleware as a preHandler hook.
 * Can be scoped to specific routes using Fastify's encapsulation.
 *
 * @example
 * ```typescript
 * // Apply to all routes in a scope
 * fastify.register(async (scope) => {
 *   await scope.register(webhookVerifyPlugin, {
 *     secret: process.env.WEBHOOK_SECRET,
 *   });
 *
 *   scope.post('/webhook', async (request, reply) => {
 *     // Signature already verified
 *     return { received: true };
 *   });
 * });
 * ```
 */
export declare const webhookVerifyPlugin: FastifyPluginAsync<WebhookVerifyConfig>;
/**
 * Sample code for webhook signature verification.
 *
 * This is returned in API responses to help webhook consumers
 * implement signature verification.
 */
export declare const WEBHOOK_VERIFICATION_SAMPLE_CODE: {
    nodejs: string;
    python: string;
    go: string;
};
/**
 * Get verification documentation for webhook responses.
 */
export declare function getWebhookSecurityDocumentation(): {
    headers: {
        name: string;
        description: string;
    }[];
    algorithm: string;
    signatureFormat: string;
    verificationSteps: string[];
    sampleCode: typeof WEBHOOK_VERIFICATION_SAMPLE_CODE;
};
export { SIGNATURE_HEADER, SIGNATURE_TIMESTAMP_HEADER, } from '../../intent/webhooks.js';
//# sourceMappingURL=webhook-verify.d.ts.map