/**
 * Cookie Utilities
 *
 * Browser-safe cookie building, parsing, and extraction.
 * Auto-detects Secure flag based on environment (localhost, HTTPS, browser).
 */
/**
 * Options for building a Set-Cookie header value.
 */
export interface CookieOptions {
    /** Cookie name */
    name: string;
    /** Cookie value */
    value: string;
    /** Cookie path (default: '/') */
    path?: string;
    /** Max age in seconds (default: 86400 = 24h) */
    maxAge?: number;
    /** HttpOnly flag — prevents JS access (default: true) */
    httpOnly?: boolean;
    /** SameSite policy (default: 'Strict') */
    sameSite?: 'Strict' | 'Lax' | 'None';
    /** Secure flag — if omitted, auto-detected from request context */
    secure?: boolean;
    /** Domain for the cookie (default: omitted = current domain) */
    domain?: string;
}
/**
 * Check if a host string is localhost.
 * Matches: localhost, 127.0.0.1, ::1, 0.0.0.0 (with or without port).
 */
export declare function isLocalhost(host: string | undefined): boolean;
/**
 * Minimal request shape for secure detection.
 * Works with Express, Koa, raw Node.js, and plain objects.
 */
export interface SecureDetectionRequest {
    headers?: Record<string, string | string[] | undefined>;
    protocol?: string;
    socket?: {
        encrypted?: boolean;
    };
}
/**
 * Detect if a request was made over HTTPS.
 * Checks (in order): protocol field, X-Forwarded-Proto header, socket.encrypted.
 */
export declare function isSecureRequest(req?: SecureDetectionRequest): boolean;
/**
 * Build a Set-Cookie header value.
 *
 * Auto-detects the Secure flag based on environment:
 * - Browser: returns `null` (server-side cookies don't apply)
 * - localhost/127.0.0.1: omits Secure (dev mode works over HTTP)
 * - HTTPS request: sets Secure
 * - No request context: sets Secure in production, omits in development
 *
 * @param options - Cookie options
 * @param req - Optional request for auto-detecting Secure and localhost
 * @returns Set-Cookie header value, or `null` if cookies don't apply (browser-only environment)
 */
export declare function buildSetCookie(options: CookieOptions, req?: SecureDetectionRequest): string | null;
/**
 * Parse a Cookie header string into key-value pairs.
 * Works in both Node.js and browser environments.
 *
 * @param cookieHeader - The Cookie header value (e.g., "name=value; other=123")
 * @returns Record of cookie name to value
 */
export declare function parseCookies(cookieHeader: string): Record<string, string>;
/**
 * Extract a specific cookie value from a Cookie header string.
 *
 * @param cookieHeader - The Cookie header value
 * @param name - Cookie name to find
 * @returns The cookie value, or undefined if not found
 */
export declare function getCookie(cookieHeader: string | undefined, name: string): string | undefined;