/**
 * Security Utilities
 *
 * HTML escaping, input detection, sanitization helpers,
 * timing-safe comparison, error sanitization, and request
 * correlation for safe, consistent security across all apps.
 */
/** Regex for protocol-prefixed URLs */
declare const URL_PROTOCOL_PATTERN: RegExp;
/** Regex for bare domain names with common TLDs */
declare const URL_DOMAIN_PATTERN: RegExp;
/** Regex for HTML tags */
declare const HTML_TAG_PATTERN: RegExp;
/**
 * Escape HTML special characters to prevent injection.
 * Use when inserting user content into HTML email templates or rendered HTML.
 */
declare function escapeHtml(str: string): string;
/** Check if a string contains protocol-prefixed URLs or bare domains */
declare function containsUrls(str: string): boolean;
/** Check if a string contains HTML tags */
declare function containsHtml(str: string): boolean;
/** Strip all HTML tags from a string */
declare function stripHtml(str: string): string;
/**
 * Strip null bytes (U+0000) from a string.
 *
 * Postgres rejects null bytes in `text`/`varchar` columns with a hard
 * `invalid byte sequence` error (→ HTTP 500 in app handlers). Apps that
 * forward raw user input — search queries, filter params, form fields —
 * into Drizzle/raw SQL queries hit this on malicious or malformed clients
 * that inject `%00` in URLs.
 *
 * Pass `undefined`/`null` through unchanged so it composes cleanly with
 * optional query params: `stripNullBytes(url.searchParams.get('q'))?.trim()`.
 *
 * @example
 * ```typescript
 * import { stripNullBytes } from '@digilogiclabs/platform-core/auth';
 *
 * const q = stripNullBytes(url.searchParams.get('q'))?.trim();
 * const results = await db.select().where(ilike(column, `%${q}%`));
 * ```
 */
declare function stripNullBytes(value: string): string;
declare function stripNullBytes(value: null | undefined): null | undefined;
declare function stripNullBytes(value: string | null | undefined): string | null | undefined;
/**
 * Recursively strip null bytes from all string values in a plain object or
 * array. Non-string values pass through unchanged. Use on parsed JSON
 * request bodies before forwarding to DB queries.
 *
 * Preserves the object's own keys and order; does NOT mutate the input.
 * Arrays stay arrays. Stops at 8 levels deep as a guard against accidental
 * circular references (throws at depth-limit exceeded).
 *
 * @example
 * ```typescript
 * import { stripNullBytesDeep } from '@digilogiclabs/platform-core/auth';
 *
 * const body = stripNullBytesDeep(await request.json());
 * const parsed = schema.safeParse(body);
 * ```
 */
declare function stripNullBytesDeep<T>(value: T, depth?: number): T;
/**
 * Defang URLs to prevent auto-linking in email clients.
 * Converts https://evil.com → hxxps://evil[.]com
 */
declare function defangUrl(str: string): string;
/**
 * Sanitize user content for safe insertion into HTML email templates.
 * Escapes HTML entities AND defangs any URLs that slipped through validation.
 */
declare function sanitizeForEmail(str: string): string;
/**
 * Constant-time string comparison to prevent timing side-channel attacks.
 * Use for comparing secrets, tokens, API keys, HMAC signatures, etc.
 *
 * Returns false (not throws) for length mismatches — still constant-time
 * relative to the shorter string to avoid leaking length info.
 *
 * @example
 * ```typescript
 * if (!constantTimeEqual(providedToken, expectedSecret)) {
 *   return { status: 401, error: 'Invalid token' }
 * }
 * ```
 */
declare function constantTimeEqual(a: string, b: string): boolean;
/**
 * Sanitize an error for client-facing API responses.
 *
 * - 4xx errors: returns the actual message (client needs to know what went wrong)
 * - 5xx errors: returns a generic message (never leak internals to clients)
 * - Development mode: optionally includes stack trace for debugging
 *
 * @example
 * ```typescript
 * catch (error) {
 *   const { message, code } = sanitizeApiError(error, 500)
 *   return Response.json({ error: message, code }, { status: 500 })
 * }
 * ```
 */
declare function sanitizeApiError(error: unknown, statusCode: number, isDevelopment?: boolean): {
    message: string;
    code?: string;
    stack?: string;
};
/**
 * Extract a correlation/request ID from standard headers, or generate one.
 *
 * Checks (in order): X-Request-ID, X-Correlation-ID, then falls back to
 * crypto.randomUUID(). Works with any headers-like object (plain object,
 * Headers API, or a getter function).
 *
 * @example
 * ```typescript
 * // With Next.js request
 * const id = getCorrelationId((name) => request.headers.get(name))
 *
 * // With plain object
 * const id = getCorrelationId({ 'x-request-id': 'abc-123' })
 * ```
 */
declare function getCorrelationId(headers: Record<string, string | string[] | undefined> | ((name: string) => string | null | undefined)): string;

export { HTML_TAG_PATTERN as H, URL_PROTOCOL_PATTERN as U, containsUrls as a, containsHtml as b, constantTimeEqual as c, stripNullBytes as d, escapeHtml as e, stripNullBytesDeep as f, sanitizeApiError as g, getCorrelationId as h, defangUrl as i, sanitizeForEmail as j, URL_DOMAIN_PATTERN as k, stripHtml as s };
