/***************************************************************************
 * XyPriss Security - Advanced Hyper-Modular Security Framework
 *
 * @author NEHONIX (Nehonix-Team - https://github.com/Nehonix-Team)
 * @license Nehonix Open Source License (NOSL)
 *
 * Copyright (c) 2025 NEHONIX. All rights reserved.
 ****************************************************************************/
import type { PasswordManagerOptions, BreachCheckResult, PassphraseOptions, PasswordGenerateOptions, PasswordStrengthResult } from "../types/PasswordManagerOptions";
/***************************************************************************
 * ### PasswordManager
 *
 * A configurable, instance-based password manager.
 * Unlike the static `Password` class, `PasswordManager` is instantiated
 * once with all options pre-configured, so callers only need to pass
 * the raw password string at call time.
 *
 * This is the recommended pattern for large-scale projects:
 * configure once in a dedicated file, export the instance, and reuse
 * everywhere without repeating options.
 *
 * @example
 * // config/security.ts
 * export const passwords = new PasswordManager({
 *   algorithm: "argon2id",
 *   memoryCost: 65536,
 *   parallelism: 4,
 *   iterations: 3,
 *   pepper: process.env.PASSWORD_PEPPER,
 * });
 *
 * // anywhere in the app:
 * const hash       = await passwords.hash("user-raw-password");
 * const valid      = await passwords.verify("user-raw-password", hash);
 * const temp       = passwords.generate({ length: 24, symbols: true });
 * const passphrase = passwords.generatePassphrase({ wordCount: 5 });
 * const pin        = passwords.generatePin(6);
 * const info       = passwords.strength("MyP@ss1!");
 * const breach     = await passwords.isBreached("hunter2");
 * const stale      = passwords.needsRehash(storedHash);
 */
export declare class PasswordManager {
    private readonly algo;
    private readonly memoryCost;
    private readonly iterations;
    private readonly parallelism;
    private readonly pepper;
    private readonly strengthOptions?;
    /** Cached wordlist for the strength method (preloaded if checkDictionary is enabled) */
    private readonly cachedStrengthWordlist?;
    /** Lazy cache for passphrase wordlists to avoid repeated disk reads */
    private passphraseWordlistCache;
    constructor(options?: PasswordManagerOptions);
    /**
     * Hashes a password using the instance's pre-configured options.
     *
     * @param password - The plain-text password to hash.
     * @param overrides - Optional per-call overrides for any constructor option.
     * @returns The encoded hash string, ready to be stored.
     */
    hash(password: string, overrides?: Partial<PasswordManagerOptions>): Promise<string>;
    /**
     * Verifies a plain-text password against a stored hash.
     *
     * @param password - The password to verify.
     * @param hash - The stored hash to compare against.
     * @param overrides - Optional per-call override for the pepper.
     * @returns `true` if the password matches the hash, `false` otherwise.
     */
    verify(password: string, hash: string, overrides?: Pick<PasswordManagerOptions, "pepper">): Promise<boolean>;
    /**
     * Checks if a string is a valid XyPriss hash, optionally matching
     * this manager's current algorithm.
     *
     * @param hash - The string to check.
     * @param strict - If `true`, only returns `true` if the hash matches the manager's algorithm.
     * @returns `true` if it's a valid hash, `false` otherwise.
     */
    isHashed(hash: string, strict?: boolean): boolean;
    /**
     * Generates a cryptographically secure random password matching the given
     * criteria, with **guaranteed character-type coverage**.
     *
     * Security properties:
     * - Every enabled character type appears **at least once** in the output.
     * - `extra` characters are **injected at cryptographically random positions**
     *   rather than appended, ensuring they don't cluster at the end.
     * - The final array is **Fisher-Yates shuffled** via `Random.Int` to remove
     *   any positional bias introduced during construction.
     * - `length` is clamped to [8, 512] to prevent misuse.
     * - Throws `RangeError` if no character type is enabled (empty charset).
     *
     * @param options - Character set and length configuration.
     * @returns A plain-text randomly generated password string.
     *
     * @example
     * const pwd = passwords.generate({ length: 24, symbols: true });
     */
    generate(options?: PasswordGenerateOptions): string;
    /**
     * Generates a **memorable, high-entropy passphrase** using a curated
     * 256-word list (similar to Diceware / EFF methodology).
     *
     * Entropy: `log2(256^wordCount)` = `8 * wordCount` bits minimum.
     * With 5 words: ~40 bits base + number suffix ≈ 53 bits total.
     * With 6 words: ~48 bits base + number suffix ≈ 61 bits total.
     *
     * Security note: word selection uses `Random.Int` which must be backed
     * by a CSPRNG (e.g. `crypto.randomInt`).
     *
     * @param options - Passphrase configuration.
     * @returns A plain-text passphrase string.
     *
     * @example
     * passwords.generatePassphrase({ wordCount: 5, separator: "-" });
     * // → "Bold-Cave-Iron-Jump-Warm-4827"
     */
    generatePassphrase(options?: PassphraseOptions): string;
    /**
     * Generates a cryptographically secure numeric PIN.
     *
     * Each digit is drawn independently from the full [0-9] range.
     * The PIN is **zero-padded** to the requested length and returned as a
     * string to preserve leading zeros (e.g. "0472").
     *
     * @param length - Number of digits. Must be between 4 and 32. @default 6
     * @returns A plain-text numeric PIN string.
     *
     * @example
     * passwords.generatePin(6); // → "047291"
     */
    generatePin(length?: number): string;
    /**
     * Evaluates the strength of a password and returns a detailed report.
     *
     * The score is computed from multiple orthogonal criteria:
     * - Length (up to 30 points)
     * - Character variety (up to 50 points)
     * - Absence of repetitions and sequences (up to 20 points deducted)
     *
     * @param password - The password to evaluate.
     * @returns A `PasswordStrengthResult` with score, label, and actionable suggestions.
     *
     * @example
     * const info = passwords.strength("MyP@ssw0rd!");
     * console.log(info.score, info.label); // 82 "strong"
     */
    strength(password: string): PasswordStrengthResult;
    /**
     * Checks whether a password has appeared in a publicly known data breach
     * using the **HaveIBeenPwned Pwned Passwords API v3** with **k-anonymity**.
     *
     * The full password is **never transmitted**. Only the first 5 characters of
     * its SHA-1 hex digest are sent over the network; the remainder of the
     * matching is performed locally.
     *
     * @param password - The plain-text password to check.
     * @returns A `BreachCheckResult` indicating breach status and occurrence count.
     * @throws If the network request fails or returns an unexpected status code.
     *
     * @example
     * const result = await passwords.isBreached("hunter2");
     * if (result.breached) {
     *   console.warn(`Password found ${result.occurrences} times in breach databases.`);
     * }
     */
    isBreached(password: string): Promise<BreachCheckResult>;
    /**
     * Determines whether a stored hash was produced with weaker parameters than
     * the instance's current configuration (e.g. after a security upgrade).
     *
     * Supports Argon2id hash strings in the PHC string format:
     * `$argon2id$v=19$m=<mem>,t=<iter>,p=<par>$<salt>$<hash>`
     *
     * For other algorithms, returns `false` (no opinion) so the caller can
     * decide on a case-by-case basis.
     *
     * @param hash - The stored hash string to inspect.
     * @returns `true` if the hash should be re-hashed on next successful login.
     *
     * @example
     * if (passwords.needsRehash(user.passwordHash)) {
     *   user.passwordHash = await passwords.hash(rawPassword);
     *   await user.save();
     * }
     */
    needsRehash(hash: string): boolean;
    /**
     * Validates and normalizes a raw password string before hashing.
     *
     * Checks performed:
     * - Not empty or whitespace-only.
     * - Minimum length of 8 characters.
     * - Maximum length of 1024 characters (DoS guard against bcrypt-style
     *   long-password attacks on other algorithms).
     * - Unicode NFC normalization (prevents homoglyph bypass attacks).
     *
     * @param password - The raw password string from user input.
     * @returns The NFC-normalized password, ready for hashing.
     * @throws `TypeError` if the input is not a string.
     * @throws `RangeError` if the password fails length validation.
     *
     * @example
     * const normalized = passwords.sanitizeInput(req.body.password);
     * const hash = await passwords.hash(normalized);
     */
    sanitizeInput(password: unknown): string;
    /**
     * Returns a summary of the instance's current configuration.
     * The `pepper` is intentionally omitted from the output.
     */
    getConfig(): {
        algorithm: string;
        memoryCost: number;
        iterations: number;
        parallelism: number;
    };
}
//# sourceMappingURL=PasswordManager.d.ts.map