/**
 * Password Hashing Module
 *
 * Production-grade password hashing using Argon2id with OWASP-recommended settings.
 * Provides secure password hashing, verification, and rehash detection.
 *
 * Security Features:
 * - Argon2id (preferred) with fallback to Argon2i
 * - OWASP-recommended memory/time/parallelism settings
 * - Timing-safe comparison via argon2 library
 * - Constant-time hash format validation
 * - Information-leak prevention in error handling
 *
 * @packageDocumentation
 * @module security/password-hashing
 */
import { VorionError } from '../common/errors.js';
/**
 * Argon2 variant identifiers from the library
 */
declare const Argon2Type: {
    readonly ARGON2D: 0;
    readonly ARGON2I: 1;
    readonly ARGON2ID: 2;
};
type Argon2Type = (typeof Argon2Type)[keyof typeof Argon2Type];
/**
 * Error thrown when password hashing operations fail.
 * Intentionally vague to prevent information leakage.
 */
export declare class PasswordHashingError extends VorionError {
    code: string;
    statusCode: number;
    constructor(message: string, details?: Record<string, unknown>);
}
/**
 * Options for password hashing
 */
export interface HashOptions {
    /**
     * Preferred Argon2 variant.
     * @default 'argon2id'
     */
    type?: 'argon2id' | 'argon2i';
    /**
     * Memory cost in KiB.
     * @default 65536 (64 MiB)
     */
    memoryCost?: number;
    /**
     * Time cost (iterations).
     * @default 3
     */
    timeCost?: number;
    /**
     * Degree of parallelism.
     * @default 4
     */
    parallelism?: number;
    /**
     * Optional secret key for additional security (pepper).
     * Should be stored separately from the database.
     */
    secret?: Buffer;
}
/**
 * Options for password verification
 */
export interface VerifyOptions {
    /**
     * Optional secret key used during hashing (pepper).
     */
    secret?: Buffer;
}
/**
 * Options for rehash check
 */
export interface RehashOptions {
    /**
     * Minimum acceptable memory cost in KiB.
     * @default 65536
     */
    memoryCost?: number;
    /**
     * Minimum acceptable time cost.
     * @default 3
     */
    timeCost?: number;
    /**
     * Minimum acceptable parallelism.
     * @default 4
     */
    parallelism?: number;
}
/**
 * Hashes a password using Argon2id (or Argon2i as fallback).
 *
 * Uses OWASP-recommended settings by default:
 * - Memory: 64 MiB (65536 KiB)
 * - Time: 3 iterations
 * - Parallelism: 4
 *
 * @param password - The plaintext password to hash
 * @param options - Optional hashing configuration
 * @returns The encoded Argon2 hash string
 * @throws {PasswordHashingError} If hashing fails
 *
 * @example
 * ```typescript
 * // Basic usage
 * const hash = await hashPassword('user-password');
 *
 * // With custom options
 * const hash = await hashPassword('user-password', {
 *   memoryCost: 131072, // 128 MiB
 *   timeCost: 4,
 *   parallelism: 4,
 * });
 *
 * // With pepper (secret key)
 * const pepper = Buffer.from(process.env.PASSWORD_PEPPER!, 'hex');
 * const hash = await hashPassword('user-password', { secret: pepper });
 * ```
 */
export declare function hashPassword(password: string, options?: HashOptions): Promise<string>;
/**
 * Verifies a password against a stored Argon2 hash.
 *
 * Uses timing-safe comparison internally (provided by argon2 library).
 *
 * @param password - The plaintext password to verify
 * @param hash - The stored Argon2 hash to verify against
 * @param options - Optional verification configuration
 * @returns `true` if the password matches, `false` otherwise
 *
 * @example
 * ```typescript
 * const isValid = await verifyPassword('user-input', storedHash);
 * if (isValid) {
 *   // Password is correct
 * }
 *
 * // With pepper (must match the pepper used during hashing)
 * const pepper = Buffer.from(process.env.PASSWORD_PEPPER!, 'hex');
 * const isValid = await verifyPassword('user-input', storedHash, { secret: pepper });
 * ```
 */
export declare function verifyPassword(password: string, hash: string, options?: VerifyOptions): Promise<boolean>;
/**
 * Checks if a hash needs to be rehashed due to outdated parameters.
 *
 * A hash should be rehashed when:
 * - It uses parameters below the current minimum thresholds
 * - It uses an older Argon2 version
 * - It uses Argon2d (not recommended for password hashing)
 *
 * @param hash - The stored Argon2 hash to check
 * @param options - Optional configuration for minimum acceptable parameters
 * @returns `true` if the hash should be rehashed, `false` otherwise
 *
 * @example
 * ```typescript
 * // Check with default OWASP settings
 * if (needsRehash(storedHash)) {
 *   // After verifying password, rehash with new settings
 *   const newHash = await hashPassword(password);
 *   // Store newHash in database
 * }
 *
 * // Check with custom thresholds
 * if (needsRehash(storedHash, { memoryCost: 131072 })) {
 *   // Hash uses less than 128 MiB memory
 * }
 * ```
 */
export declare function needsRehash(hash: string, options?: RehashOptions): boolean;
/**
 * Default Argon2 configuration (OWASP-recommended)
 */
export declare const DEFAULT_ARGON2_CONFIG: {
    /** Memory cost in KiB (64 MiB = 65536 KiB) */
    readonly memoryCost: 65536;
    /** Time cost (iterations) */
    readonly timeCost: 3;
    /** Degree of parallelism */
    readonly parallelism: 4;
    /** Output hash length in bytes */
    readonly hashLength: 32;
};
/**
 * Minimum acceptable Argon2 configuration
 */
export declare const MINIMUM_ARGON2_CONFIG: {
    readonly memoryCost: 65536;
    readonly timeCost: 3;
    readonly parallelism: 4;
};
export { Argon2Type };
//# sourceMappingURL=password-hashing.d.ts.map