import { VorionError } from '../common/errors.js';
/**
 * Error thrown when attempting to use a cleared secure value
 */
export declare class SecureMemoryError extends VorionError {
    code: string;
    statusCode: number;
    constructor(message: string, details?: Record<string, unknown>);
}
/**
 * Error thrown when a required environment variable is missing
 */
export declare class MissingEnvironmentError extends VorionError {
    code: string;
    statusCode: number;
    constructor(variableName: string);
}
/**
 * SecureString class for handling sensitive string data
 *
 * Provides best-effort memory clearing when no longer needed.
 * Uses Buffer internally for more reliable memory clearing than
 * JavaScript strings, which are immutable and may be interned.
 *
 * @example
 * ```typescript
 * // Create a secure string from a password
 * const password = new SecureString(userInput);
 *
 * // Use the value safely
 * const hash = password.use((pwd) => bcrypt.hashSync(pwd, 10));
 *
 * // Explicitly clear when done (or use 'using' declaration)
 * password.clear();
 *
 * // Using the 'using' declaration (TypeScript 5.2+)
 * {
 *   using secret = new SecureString(apiKey);
 *   await secret.useAsync((key) => fetchWithAuth(key));
 * } // Automatically cleared at end of block
 * ```
 */
export declare class SecureString {
    private buffer;
    private cleared;
    private readonly createdAt;
    private readonly id;
    /**
     * Create a new SecureString from a string value
     *
     * @param value - The sensitive string to protect
     */
    constructor(value: string);
    /**
     * Use the secret value with a callback
     *
     * Creates a temporary string copy for the operation. The callback
     * should not store the value or allow it to escape the function scope.
     *
     * @param fn - Callback that receives the decrypted value
     * @returns The return value of the callback
     * @throws SecureMemoryError if the string has been cleared
     */
    use<T>(fn: (value: string) => T): T;
    /**
     * Async version of use
     *
     * Creates a temporary string copy for the async operation.
     *
     * @param fn - Async callback that receives the decrypted value
     * @returns Promise resolving to the callback's return value
     * @throws SecureMemoryError if the string has been cleared
     */
    useAsync<T>(fn: (value: string) => Promise<T>): Promise<T>;
    /**
     * Zero-fill the buffer and mark as cleared
     *
     * This provides best-effort memory clearing. Due to V8's garbage
     * collection and string interning, complete clearing is not guaranteed.
     */
    clear(): void;
    /**
     * Check if the secure string has been cleared
     *
     * @returns true if the value has been cleared
     */
    isCleared(): boolean;
    /**
     * Get the length of the secure string (without exposing the value)
     *
     * @returns Length of the string in bytes
     * @throws SecureMemoryError if the string has been cleared
     */
    get length(): number;
    /**
     * Symbol.dispose for using declaration (TypeScript 5.2+)
     *
     * Enables automatic cleanup with the 'using' keyword:
     * ```typescript
     * using secret = new SecureString(value);
     * // secret is automatically cleared at end of block
     * ```
     */
    [Symbol.dispose](): void;
    /**
     * Ensure the value hasn't been cleared
     * @throws SecureMemoryError if cleared
     */
    private ensureNotCleared;
    /**
     * Override toString to prevent accidental logging
     */
    toString(): string;
    /**
     * Override toJSON to prevent accidental serialization
     */
    toJSON(): string;
}
/**
 * SecureBuffer class for handling sensitive binary data
 *
 * Similar to SecureString but designed for binary data such as
 * encryption keys, random bytes, or binary secrets.
 *
 * @example
 * ```typescript
 * // Create a secure buffer from binary data
 * const key = new SecureBuffer(cryptoKeyBytes);
 *
 * // Use the value safely
 * const encrypted = key.use((k) => crypto.encrypt(data, k));
 *
 * // Clear when done
 * key.clear();
 * ```
 */
export declare class SecureBuffer {
    private buffer;
    private cleared;
    private readonly createdAt;
    private readonly id;
    /**
     * Create a new SecureBuffer from binary data
     *
     * @param data - The sensitive binary data to protect (Buffer, Uint8Array, or hex string)
     */
    constructor(data: Buffer | Uint8Array | string);
    /**
     * Use the secret value with a callback
     *
     * Creates a copy of the buffer for the operation to prevent
     * external modification of the internal buffer.
     *
     * @param fn - Callback that receives a copy of the buffer
     * @returns The return value of the callback
     * @throws SecureMemoryError if the buffer has been cleared
     */
    use<T>(fn: (value: Buffer) => T): T;
    /**
     * Async version of use
     *
     * @param fn - Async callback that receives a copy of the buffer
     * @returns Promise resolving to the callback's return value
     * @throws SecureMemoryError if the buffer has been cleared
     */
    useAsync<T>(fn: (value: Buffer) => Promise<T>): Promise<T>;
    /**
     * Zero-fill the buffer and mark as cleared
     */
    clear(): void;
    /**
     * Check if the secure buffer has been cleared
     *
     * @returns true if the value has been cleared
     */
    isCleared(): boolean;
    /**
     * Get the length of the secure buffer (without exposing the value)
     *
     * @returns Length of the buffer in bytes
     * @throws SecureMemoryError if the buffer has been cleared
     */
    get length(): number;
    /**
     * Symbol.dispose for using declaration (TypeScript 5.2+)
     */
    [Symbol.dispose](): void;
    /**
     * Ensure the value hasn't been cleared
     * @throws SecureMemoryError if cleared
     */
    private ensureNotCleared;
    /**
     * Override toString to prevent accidental logging
     */
    toString(): string;
    /**
     * Override toJSON to prevent accidental serialization
     */
    toJSON(): string;
}
/**
 * Create a SecureString from an environment variable
 *
 * @param name - The name of the environment variable
 * @returns SecureString containing the value, or undefined if not set
 *
 * @example
 * ```typescript
 * const apiKey = secureEnv('API_KEY');
 * if (apiKey) {
 *   apiKey.use((key) => callApi(key));
 *   apiKey.clear();
 * }
 * ```
 */
export declare function secureEnv(name: string): SecureString | undefined;
/**
 * Create a SecureString from a required environment variable
 *
 * @param name - The name of the environment variable
 * @returns SecureString containing the value
 * @throws MissingEnvironmentError if the variable is not set
 *
 * @example
 * ```typescript
 * // Throws if DATABASE_PASSWORD is not set
 * const dbPassword = requireSecureEnv('DATABASE_PASSWORD');
 * ```
 */
export declare function requireSecureEnv(name: string): SecureString;
/**
 * Create a SecureBuffer from random bytes
 *
 * @param length - Number of random bytes to generate
 * @returns SecureBuffer containing random bytes
 *
 * @example
 * ```typescript
 * const key = secureRandomBytes(32);
 * key.use((bytes) => encrypt(data, bytes));
 * key.clear();
 * ```
 */
export declare function secureRandomBytes(length: number): SecureBuffer;
/**
 * Securely compare two SecureStrings in constant time
 *
 * @param a - First SecureString
 * @param b - Second SecureString
 * @returns true if values are equal
 * @throws SecureMemoryError if either string has been cleared
 *
 * @example
 * ```typescript
 * const input = new SecureString(userInput);
 * const stored = new SecureString(storedHash);
 * const match = secureCompare(input, stored);
 * ```
 */
export declare function secureCompare(a: SecureString, b: SecureString): boolean;
/**
 * Securely compare two SecureBuffers in constant time
 *
 * @param a - First SecureBuffer
 * @param b - Second SecureBuffer
 * @returns true if values are equal
 * @throws SecureMemoryError if either buffer has been cleared
 */
export declare function secureCompareBuffers(a: SecureBuffer, b: SecureBuffer): boolean;
/**
 * Execute a function with a temporary secure string that is automatically cleared
 *
 * @param value - The sensitive string value
 * @param fn - Function to execute with the secure string
 * @returns The return value of the function
 *
 * @example
 * ```typescript
 * const result = withSecureString(password, (secure) => {
 *   return secure.use((pwd) => hashPassword(pwd));
 * });
 * // SecureString is automatically cleared
 * ```
 */
export declare function withSecureString<T>(value: string, fn: (secure: SecureString) => T): T;
/**
 * Execute an async function with a temporary secure string that is automatically cleared
 *
 * @param value - The sensitive string value
 * @param fn - Async function to execute with the secure string
 * @returns Promise resolving to the function's return value
 */
export declare function withSecureStringAsync<T>(value: string, fn: (secure: SecureString) => Promise<T>): Promise<T>;
/**
 * Execute a function with a temporary secure buffer that is automatically cleared
 *
 * @param data - The sensitive binary data
 * @param fn - Function to execute with the secure buffer
 * @returns The return value of the function
 */
export declare function withSecureBuffer<T>(data: Buffer | Uint8Array | string, fn: (secure: SecureBuffer) => T): T;
/**
 * Execute an async function with a temporary secure buffer that is automatically cleared
 *
 * @param data - The sensitive binary data
 * @param fn - Async function to execute with the secure buffer
 * @returns Promise resolving to the function's return value
 */
export declare function withSecureBufferAsync<T>(data: Buffer | Uint8Array | string, fn: (secure: SecureBuffer) => Promise<T>): Promise<T>;
//# sourceMappingURL=secure-memory.d.ts.map