/**
 * CSRF Protection System for Vorion Platform
 *
 * Implements double-submit cookie pattern with HMAC-signed tokens
 * for protection against Cross-Site Request Forgery attacks.
 *
 * @module security/csrf
 */
import type { preHandlerHookHandler } from 'fastify';
/**
 * Cookie options for CSRF token cookie
 */
export interface CSRFCookieOptions {
    /** Whether the cookie should only be sent over HTTPS */
    secure: boolean;
    /** Whether the cookie is inaccessible to JavaScript */
    httpOnly: boolean;
    /** SameSite attribute for the cookie */
    sameSite: 'strict' | 'lax' | 'none';
    /** Cookie path */
    path?: string;
    /** Cookie domain */
    domain?: string;
    /** Max age in seconds */
    maxAge?: number;
}
/**
 * Configuration interface for CSRF protection
 */
export interface CSRFConfig {
    /** Length of the random token component in bytes (default: 32) */
    tokenLength: number;
    /** Name of the CSRF cookie (default: '__vorion_csrf') */
    cookieName: string;
    /** Name of the header containing the CSRF token (default: 'X-CSRF-Token') */
    headerName: string;
    /** Cookie configuration options */
    cookieOptions: CSRFCookieOptions;
    /** Array of path patterns to exclude from CSRF protection (e.g., webhooks) */
    excludePaths: string[];
    /** HTTP methods to exclude from CSRF validation (default: ['GET', 'HEAD', 'OPTIONS']) */
    excludeMethods: string[];
    /** Secret key for HMAC signing (should be loaded from environment) */
    secret: string;
    /** Token validity duration in milliseconds (default: 1 hour) */
    tokenTTL: number;
}
/**
 * Result of token validation
 */
export interface TokenValidationResult {
    /** Whether the token is valid */
    valid: boolean;
    /** Error message if validation failed */
    error?: string;
}
/**
 * CSRF Protection class implementing double-submit cookie pattern
 * with HMAC-signed tokens for secure request validation.
 *
 * @example
 * ```typescript
 * const csrf = new CSRFProtection({
 *   secret: process.env.CSRF_SECRET,
 *   excludePaths: ['/api/webhooks'],
 * });
 *
 * // Register middleware
 * fastify.addHook('preHandler', csrf.createMiddleware());
 *
 * // Generate token for a session
 * const token = csrf.generateToken('session-123');
 * ```
 */
export declare class CSRFProtection {
    private readonly config;
    /**
     * Creates a new CSRFProtection instance
     *
     * @param config - Partial configuration object (merged with defaults)
     * @throws {Error} If secret is not provided or is too short
     */
    constructor(config?: Partial<CSRFConfig>);
    /**
     * Generates a cryptographically secure CSRF token
     *
     * Token format: base64(sessionId.timestamp.random.signature)
     * where signature = HMAC-SHA256(sessionId + timestamp + random, secret)
     *
     * @param sessionId - The session identifier to bind the token to
     * @returns A signed CSRF token string
     */
    generateToken(sessionId?: string): string;
    /**
     * Validates a CSRF token against the cookie token
     *
     * Performs the following checks:
     * 1. Both tokens are present and non-empty
     * 2. Tokens match exactly (timing-safe comparison)
     * 3. Token signature is valid
     * 4. Token has not expired
     *
     * @param token - The token from the request header
     * @param cookieToken - The token from the cookie
     * @returns Whether the token is valid
     */
    validateToken(token: string, cookieToken: string): boolean;
    /**
     * Validates a CSRF token with detailed error information
     *
     * @param token - The token from the request header
     * @param cookieToken - The token from the cookie
     * @returns Validation result with error details if invalid
     */
    validateTokenWithDetails(token: string, cookieToken: string): TokenValidationResult;
    /**
     * Creates a Fastify preHandler middleware for CSRF protection
     *
     * The middleware:
     * - Skips validation for excluded paths and methods
     * - Sets the CSRF cookie on all responses
     * - Validates the token from header against cookie on state-changing requests
     * - Returns 403 Forbidden on validation failure
     *
     * @returns Fastify preHandler hook function
     */
    createMiddleware(): preHandlerHookHandler;
    /**
     * Gets the current configuration
     *
     * @returns A copy of the current configuration
     */
    getConfig(): Readonly<CSRFConfig>;
    /**
     * Creates an HMAC-SHA256 signature
     *
     * @param data - Data to sign
     * @returns Hex-encoded signature
     */
    private createSignature;
    /**
     * Parses a token string into its components
     *
     * @param token - The base64url-encoded token
     * @returns Parsed token components or null if invalid
     */
    private parseToken;
    /**
     * Checks if a path should be excluded from CSRF protection
     *
     * @param url - The request URL
     * @returns Whether the path is excluded
     */
    private isPathExcluded;
    /**
     * Extracts the CSRF token from the request header
     *
     * @param request - Fastify request object
     * @returns The token string or empty string if not found
     */
    private getTokenFromHeader;
    /**
     * Extracts the CSRF token from the cookie
     *
     * @param request - Fastify request object
     * @returns The token string or empty string if not found
     */
    private getTokenFromCookie;
    /**
     * Sets the CSRF cookie on the response
     *
     * @param request - Fastify request object
     * @param reply - Fastify reply object
     */
    private setCSRFCookie;
    /**
     * Attempts to extract session ID from request
     *
     * @param request - Fastify request object
     * @returns Session ID or empty string
     */
    private extractSessionId;
}
/**
 * Gets the singleton CSRFProtection instance
 *
 * Creates the instance on first call using configuration from getConfig().
 * Subsequent calls return the same instance.
 *
 * @returns The CSRFProtection singleton instance
 * @throws {Error} If CSRF secret is not configured
 *
 * @example
 * ```typescript
 * const csrf = getCSRFProtection();
 * fastify.addHook('preHandler', csrf.createMiddleware());
 * ```
 */
export declare function getCSRFProtection(): CSRFProtection;
/**
 * Resets the singleton instance (useful for testing)
 *
 * @internal
 */
export declare function resetCSRFProtection(): void;
/**
 * Type declaration for extending Fastify request with CSRF-related properties
 */
declare module 'fastify' {
    interface FastifyRequest {
        csrfToken?: string;
    }
}
export default CSRFProtection;
//# sourceMappingURL=csrf.d.ts.map