/**
 * Security Headers Middleware
 *
 * Adds essential security headers to all responses including:
 * - Content-Security-Policy (CSP)
 * - X-Content-Type-Options
 * - X-Frame-Options
 * - X-XSS-Protection
 * - Strict-Transport-Security (HSTS)
 * - Referrer-Policy
 * - Permissions-Policy
 *
 * Configuration options:
 * - Can be disabled entirely for development (SECURITY_HEADERS=false)
 * - Supports route-based exclusions (e.g., for static assets)
 * - CSP can be set to report-only mode for testing
 */
import { Request, Response, NextFunction } from 'express';
import type { ServerConfig } from '../types.js';
export interface SecurityHeadersConfig {
    /**
     * Enable security headers entirely
     * @default true in production, configurable in development
     */
    enabled?: boolean;
    /**
     * Enable Content-Security-Policy header
     * @default true
     */
    enableCSP?: boolean;
    /**
     * Custom CSP directives (merged with defaults)
     */
    cspDirectives?: Partial<CSPDirectives>;
    /**
     * Enable HSTS header (should only be enabled for HTTPS)
     * @default false (auto-enabled when NODE_ENV=production)
     */
    enableHSTS?: boolean;
    /**
     * HSTS max-age in seconds
     * @default 31536000 (1 year)
     */
    hstsMaxAge?: number;
    /**
     * Include subdomains in HSTS
     * @default true
     */
    hstsIncludeSubDomains?: boolean;
    /**
     * Enable HSTS preload
     * @default false
     */
    hstsPreload?: boolean;
    /**
     * X-Frame-Options value
     * @default 'DENY'
     */
    frameOptions?: 'DENY' | 'SAMEORIGIN';
    /**
     * Referrer-Policy value
     * @default 'strict-origin-when-cross-origin'
     */
    referrerPolicy?: string;
    /**
     * Routes to exclude from security headers (e.g., static assets)
     * Supports exact matches and prefix patterns (ending with *)
     * @example ['/static/*', '/assets/*', '/health']
     */
    excludeRoutes?: string[];
    /**
     * Use Content-Security-Policy-Report-Only instead of Content-Security-Policy
     * Useful for testing CSP without blocking content
     * @default false
     */
    cspReportOnly?: boolean;
    /**
     * URI for CSP violation reports
     * @example '/api/csp-report'
     */
    cspReportUri?: string;
}
export interface CSPDirectives {
    'default-src': string[];
    'script-src': string[];
    'style-src': string[];
    'img-src': string[];
    'font-src': string[];
    'connect-src': string[];
    'frame-ancestors': string[];
    'form-action': string[];
    'base-uri': string[];
    'object-src': string[];
    'upgrade-insecure-requests'?: boolean;
}
/**
 * Default CSP directives for a secure API server
 */
declare const DEFAULT_CSP_DIRECTIVES: CSPDirectives;
/**
 * Create security headers middleware
 *
 * @param serverConfig - Server configuration containing securityHeaders settings
 * @param securityConfig - Direct security headers configuration (optional, for backward compatibility)
 * @returns Express middleware function
 *
 * @example
 * // Basic usage with server config
 * app.use(createSecurityHeadersMiddleware(serverConfig));
 *
 * @example
 * // Disable in development
 * app.use(createSecurityHeadersMiddleware({ ...serverConfig, securityHeaders: { enabled: false } }));
 *
 * @example
 * // Custom CSP for specific needs
 * app.use(createSecurityHeadersMiddleware(serverConfig, {
 *   cspDirectives: {
 *     'script-src': ["'self'", 'cdn.example.com'],
 *   },
 *   excludeRoutes: ['/static/*'],
 * }));
 */
export declare function createSecurityHeadersMiddleware(serverConfig: ServerConfig, securityConfig?: SecurityHeadersConfig): (req: Request, res: Response, next: NextFunction) => void;
/**
 * Export default CSP directives for customization
 */
export { DEFAULT_CSP_DIRECTIVES };
/**
 * Strict CSP configuration for API-only servers
 * - No inline scripts or styles
 * - Self-only sources
 * - Blocks all frames
 */
export declare const STRICT_API_CONFIG: SecurityHeadersConfig;
/**
 * Relaxed CSP configuration for servers serving static assets
 * - Allows inline styles (for UI frameworks)
 * - Allows data: URIs for images
 * - Allows HTTPS sources for images
 */
export declare const STATIC_ASSETS_CONFIG: SecurityHeadersConfig;
/**
 * Development configuration - minimal security headers
 * - CSP in report-only mode
 * - HSTS disabled
 * - Useful for local development
 */
export declare const DEVELOPMENT_CONFIG: SecurityHeadersConfig;
/**
 * Get recommended security config based on environment
 */
export declare function getRecommendedConfig(): SecurityHeadersConfig;
