/**
 * Debug Authentication Middleware
 *
 * Secures debug endpoints by:
 * - Restricting access to localhost only (127.0.0.1)
 * - Requiring a debug authentication token
 * - Logging all access attempts
 *
 * @packageDocumentation
 */
import { IncomingMessage, ServerResponse } from 'http';
/**
 * Debug token configuration
 */
export interface DebugTokenConfig {
    /** The debug token (from environment variable) */
    token: string;
    /** Token header name */
    headerName?: string;
}
/**
 * Debug endpoint access result
 */
export interface DebugAccessResult {
    allowed: boolean;
    reason?: string;
    clientIp?: string;
    requestId?: string;
}
/**
 * Get the configured debug token from environment
 *
 * @returns The debug token or null if not configured
 */
export declare function getDebugToken(): string | null;
/**
 * Extract client IP address from request
 *
 * Handles various proxy headers and direct connections
 */
export declare function getClientIp(req: IncomingMessage): string;
/**
 * Check if the request is from localhost
 */
export declare function isLocalhost(clientIp: string): boolean;
/**
 * Validate debug authentication token
 *
 * @param providedToken - Token provided in request
 * @param expectedToken - Expected token from configuration
 * @returns true if tokens match
 */
export declare function validateDebugToken(providedToken: string | undefined, expectedToken: string): boolean;
/**
 * Check if debug endpoints are allowed for this request
 *
 * Validates:
 * 1. Debug endpoints are enabled in current security mode
 * 2. Request comes from localhost (if bind address is restricted)
 * 3. Valid debug token is provided (if required)
 *
 * @param req - The incoming HTTP request
 * @param requestId - Optional request ID for logging
 * @returns Access result indicating if request is allowed
 */
export declare function checkDebugAccess(req: IncomingMessage, requestId?: string): DebugAccessResult;
/**
 * Express-style middleware for debug endpoint authentication
 *
 * @example
 * ```typescript
 * import { debugAuthMiddleware } from './debug-auth-middleware';
 *
 * app.use('/debug', debugAuthMiddleware);
 * app.get('/debug/info', (req, res) => {
 *   res.json({ status: 'ok' });
 * });
 * ```
 */
export declare function debugAuthMiddleware(req: IncomingMessage & {
    requestId?: string;
}, res: ServerResponse, next: () => void): void;
/**
 * Create a debug endpoint handler with built-in authentication
 *
 * @param handler - The actual debug handler to wrap
 * @returns Wrapped handler with authentication
 */
export declare function createSecureDebugHandler<T extends IncomingMessage>(handler: (req: T, res: ServerResponse) => void | Promise<void>): (req: T, res: ServerResponse) => Promise<void>;
/**
 * Configuration for debug server binding
 *
 * Returns the appropriate bind address based on security mode
 */
export declare function getDebugBindAddress(): string;
/**
 * Validate debug configuration at startup
 *
 * Checks that debug endpoints are properly configured
 */
export declare function validateDebugConfig(): {
    valid: boolean;
    warnings: string[];
};
/**
 * Generate a secure debug token for configuration
 *
 * @returns A random 32-byte hex string suitable for use as debug token
 */
export declare function generateDebugToken(): string;
//# sourceMappingURL=debug-auth-middleware.d.ts.map