xypriss-security 2.0.9 → 2.1.1

package/README.md

@@ -1,15 +1,14 @@
 # XyPriss Security
 
-XyPriss Security is an enterprise-grade cryptographic framework for **Bun** and **Node.js**. It utilizes a high-performance Go-based core engine via native FFI (Foreign Function Interface) to provide military-grade security with sub-millisecond overhead across all major JavaScript environments.
+XyPriss Security is an enterprise-grade cryptographic framework for TypeScript / JavaScript environments. It utilizes a high-performance Go-based core engine compiled as a static, dependency-free CLI binary to provide military-grade security with absolute cross-platform reliability.
 
 ## Core Principles
 
-- **Performance**: Optimized atomic FFI calls bypass the overhead of standard JavaScript cryptographic implementations.
-- **Cross-Runtime**: First-class support for both Bun (`bun:ffi`) and Node.js (`koffi`), automatically detecting the host environment.
+- **Performance**: Optimized execution using lightweight process spawning, bypassing the overhead of standard JavaScript cryptographic implementations without the complexity of CGO.
+- **Universal Portability**: Zero native compilation required. Statically linked pure Go binaries run flawlessly on Linux, Windows, and macOS (amd64/arm64) via a unified interface.
 - **Modern Standards**: Native support for AES-256-GCM, Argon2id, PBKDF2, HKDF, and Post-Quantum algorithms (Kyber-768).
-
 - **Security by Default**: Automatic memory sanitization and secure key derivation patterns.
-- **Zero-Config Native Performance**: Automatically builds the Go core from source or downloads pre-built binaries for your platform during installation.
+- **Zero-Config Installation**: Automatically downloads the exact pre-built binary for your platform during installation (no local Go toolchain required).
 
 ## Documentation
 
@@ -74,12 +73,15 @@ XyPriss uses Argon2id by default, providing superior resistance to GPU/ASIC crac
 ```typescript
 import { pm } from "xypriss-security"; // 'pm' is an alias for PasswordManager
 
-const hash = await pm.hash("user-password-123", {
-  memoryCost: 65536, // 64MB
+// 1. Configure once per app
+const passwords = new pm({
+  memoryCost: 65536, // 64MiB
   parallelism: 4,
 });
 
-const isValid = await pm.verify("user-password-123", hash);
+// 2. Use everywhere
+const hash = await passwords.hash("user-password-123");
+const isValid = await passwords.verify("user-password-123", hash);
 ```
 
 ### Ultra-Fast Secure Caching (UFSIMC)

package/dist/src/components/index.d.ts

@@ -1,7 +1,7 @@
 /***************************************************************************
  * XyPriss Security - Modular Component Registry
  *
- * @author NEHONIX (iDevo - https://github.com/iDevo-ll)
+ * @author NEHONIX (Nehonix-Team - https://github.com/Nehonix-Team)
  * @license Nehonix Open Source License (NOSL)
  ****************************************************************************/
 export * from "./cache";

package/dist/src/components/index.js

@@ -2,7 +2,7 @@
 /***************************************************************************
  * XyPriss Security - Modular Component Registry
  *
- * @author NEHONIX (iDevo - https://github.com/iDevo-ll)
+ * @author NEHONIX (Nehonix-Team - https://github.com/Nehonix-Team)
  * @license Nehonix Open Source License (NOSL)
  ****************************************************************************/
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {

package/dist/src/core/PasswordManager.d.ts

@@ -0,0 +1,205 @@
+/***************************************************************************
+ * 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;
+    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>;
+    /**
+     * 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

package/dist/src/core/PasswordManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PasswordManager.d.ts","sourceRoot":"","sources":["../../../src/core/PasswordManager.ts"],"names":[],"mappings":"AAAA;;;;;;;8EAO8E;AAY9E,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAIzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,OAAO,GAAE,sBAA2B;IAUhD;;;;;;OAMG;IACU,IAAI,CACf,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAAC,MAAM,CAAC;IAYlB;;;;;;;OAOG;IACU,MAAM,CACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAM,GACrD,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;;;;;;;;;;;;;;OAkBG;IACI,QAAQ,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM;IA6E9D;;;;;;;;;;;;;;;;;OAiBG;IACI,kBAAkB,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM;IAsDlE;;;;;;;;;;;;OAYG;IACI,WAAW,CAAC,MAAM,GAAE,MAAU,GAAG,MAAM;IAgB9C;;;;;;;;;;;;;;OAcG;IACI,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB;IA4FzD;;;;;;;;;;;;;;;;;OAiBG;IACU,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyCrE;;;;;;;;;;;;;;;;;;OAkBG;IACI,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAczC;;;;;;;;;;;;;;;;;;OAkBG;IACI,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM;IAiC/C;;;OAGG;IACI,SAAS,IAAI;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB;CAQF"}