xypriss-security/dist/src/mods/PasswordMDict.d.ts

Advanced High-Performance Security Framework. Military-grade encryption, post-quantum resilience, and fortified data structures.

/***************************************************************************
 * 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.
 ****************************************************************************/
export declare const CHARSETS: {
    readonly uppercase: string;
    readonly lowercase: string;
    readonly numbers: string;
    readonly symbols: string;
    readonly similarChars: RegExp;
};
/** Minimum length enforced on every `generate()` call. */
export declare const MIN_GENERATE_LENGTH = 8;
/** Maximum length enforced on every `generate()` call. */
export declare const MAX_GENERATE_LENGTH = 512;
/**
 * Supported EFF wordlist variants.
 *
 * | Variant      | Dice | Words | Entropy/word |
 * |--------------|------|-------|--------------|
 * | `large`      | 5×d6 | 7 776 | ~12.9 bits   |
 * | `short1`     | 4×d6 | 1 296 | ~10.3 bits   |
 * | `short2`     | 4×d6 | 1 296 | ~10.3 bits   |
 */
export type EFFWordlistVariant = "large" | "short1" | "short2";
/**
 * Canonical filenames used by the EFF for each wordlist variant.
 * Match the files available at:
 *   https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt
 *   https://www.eff.org/files/2016/09/08/eff_short_wordlist_1.txt
 *   https://www.eff.org/files/2016/09/08/eff_short_wordlist_2_0.txt
 */
export declare const EFF_FILENAMES: Record<EFFWordlistVariant, string>;
/**
 * Options for `loadEFFWordlist`.
 */
export interface LoadWordlistOptions {
    /**
     * Directory that contains the EFF `.txt` files.
     * Resolved relative to `process.cwd()` if not absolute.
     * @default process.cwd()
     */
    dir?: string;
    /**
     * Wordlist variant to load.
     * @default "large"
     */
    variant?: EFFWordlistVariant;
    /**
     * Custom file path, taking precedence over `dir` + `variant`.
     * Use this to load any EFF-formatted wordlist from an arbitrary location.
     */
    filePath?: string;
}
/**
 * Parses a raw EFF `.txt` wordlist file and returns a deduplicated,
 * validated `readonly string[]` ready for use in `generatePassphrase()`.
 *
 * **Supported line formats (both are handled automatically):**
 * ```
 * # Numbered (dice-index prefix, tab-separated):
 * 11111\tabacus
 * 11112\tabrupt
 *
 * # Plain (one word per line):
 * abacus
 * abrupt
 * ```
 *
 * Lines that are empty, start with `#`, or produce a word of length < 2
 * after stripping are silently ignored.
 *
 * @param options - File location and variant configuration.
 * @returns A readonly array of lowercased, trimmed words.
 * @throws `Error` if the file cannot be read or yields fewer than 10 words.
 *
 * @example
 * // Load from ./wordlists/eff_large_wordlist.txt
 * const words = loadEFFWordlist({ dir: "./wordlists", variant: "large" });
 *
 * @example
 * // Load a custom EFF-format file
 * const words = loadEFFWordlist({ filePath: "/opt/security/my_words.txt" });
 */
export declare function loadEFFWordlist(options?: LoadWordlistOptions): readonly string[];
/**
 * Options for `getWordlist`.
 */
export interface GetWordlistOptions extends LoadWordlistOptions {
    /**
     * Whether to fall back to the built-in 256-word list if the external
     * file cannot be loaded.
     *
     * - `"silent"` — fall back without any output.
     * - `"warn"`   — print a `console.warn` before falling back.
     * - `false`    — rethrow the file load error (no fallback).
     *
     * @default "warn"
     */
    allowFallback?: "silent" | "warn" | false;
}
/**
 * Unified wordlist accessor: tries to load an EFF file, falls back to the
 * built-in list according to `allowFallback`.
 *
 * Use this function in `PasswordManager.generatePassphrase()` to stay
 * decoupled from both the file system and the hardcoded list.
 *
 * @param options - File location, variant, and fallback policy.
 * @returns A readonly array of words suitable for passphrase generation.
 *
 * @example
 * // Prefer the large EFF list; warn & fall back if absent
 * const words = getWordlist({ dir: "./assets/wordlists", variant: "large" });
 *
 * @example
 * // Never fall back — throw if the file is missing
 * const words = getWordlist({ filePath: "./eff_large_wordlist.txt", allowFallback: false });
 *
 * @example
 * // Only use the built-in list (no file needed)
 * const words = getWordlist({ allowFallback: "silent" });
 * // → returns FALLBACK_WORDLIST without attempting any file read
 */
export declare function getWordlist(options?: GetWordlistOptions): readonly string[];
//# sourceMappingURL=PasswordMDict.d.ts.map