@zudojs/crypto 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Cryptographic primitives for hashing, authenticated encryption, password hashing, digital signatures, key derivation, opaque tokens, and secure random generation. Everything is backed by `node:crypto` through a swappable provider.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-crypto](https://zudojs.oyinlola.site/docs/packages-crypto) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-crypto.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -42,8 +48,8 @@ const sessionToken = await generateToken({ bytes: 32, prefix: "sess_" });
 
 - Hashing: SHA-256/384/512 and SHA3-256/384/512, HMAC (keys of at least 16 bytes)
 - Authenticated encryption: AES-256-GCM with strict IV (12 bytes) and tag (16 bytes) validation, plus a versioned string envelope
-- Password hashing: scrypt (default, OWASP parameters) and PBKDF2-HMAC (provider level), versioned self-describing encoding, bounded parameters on verification
-- Key derivation: PBKDF2 (sha256/384/512, 600 000 iterations by default) and scrypt (cost, block size, parallelization, memory bound)
+- Password hashing: scrypt (default N=2^14, r=8, p=5 — the OWASP row for that N) and PBKDF2-HMAC (provider level), versioned self-describing encoding, bounded parameters on verification. New hashes must use a cost of at least `PASSWORD_HASH.SCRYPT.MIN_COST` (16 384); older stored hashes with a smaller cost still verify. Key derivation (`deriveScrypt`) keeps p=1 by default, so derived keys do not change
+- Key derivation: PBKDF2 (sha256/384/512, 600 000 iterations by default) and scrypt (cost, block size, parallelization, memory bound); every work factor and the output length are capped by `PASSWORD_HASH.LIMITS`, so a value read from configuration cannot request unbounded CPU or memory
 - Digital signatures: Ed25519, RSA-SHA256/384/512, ECDSA-SHA256/384/512; the algorithm label is bound to the key type
 - Secure random: unbiased integers up to 2^48, UUID v4, bytes, alphabets, numeric codes
 - Opaque tokens (API keys, sessions, refresh, CSRF, OTP) with SHA-256 storage hashes

package/dist/cryptoConstants/cryptoConstants.security.d.ts

@@ -1,10 +1,14 @@
 /**
  * Password hashing constants.
  *
- * Defaults follow current OWASP Password Storage Cheat Sheet guidance:
- * scrypt N=2^14, r=8, p=1 (minimum) and PBKDF2-HMAC-SHA256 with 600 000
- * iterations. `LIMITS` bounds parameters that are read back from stored
- * hashes so that a tampered or foreign record cannot force unbounded work.
+ * Defaults follow the OWASP Password Storage Cheat Sheet: scrypt N=2^14,
+ * r=8, p=5 (OWASP's N=2^14 row; p=1 is only adequate at N=2^17) and
+ * PBKDF2-HMAC-SHA256 with 600 000 iterations. `LIMITS` bounds parameters
+ * that are read back from stored hashes so that a tampered or foreign
+ * record cannot force unbounded work.
+ *
+ * New hashes are held to `SCRYPT.MIN_COST`; verification still accepts
+ * older stored hashes down to `LIMITS.MIN_SCRYPT_COST`.
  */
 export declare const PASSWORD_HASH: Readonly<{
     readonly SALT_BYTES: 16;
@@ -12,7 +16,15 @@ export declare const PASSWORD_HASH: Readonly<{
     readonly SCRYPT: Readonly<{
         COST: 16384;
         BLOCK_SIZE: 8;
+        /**
+         * Default `p` for key derivation (`deriveScrypt`). Left at 1: changing
+         * it would silently change every key derived with default options.
+         */
         PARALLELIZATION: 1;
+        /** Default `p` for new *password hashes* (OWASP N=2^14, r=8, p=5). */
+        PASSWORD_PARALLELIZATION: 5;
+        /** Floor on the cost of *new* hashes; `LIMITS.MIN_SCRYPT_COST` bounds verification. */
+        MIN_COST: 16384;
     }>;
     readonly PBKDF2: Readonly<{
         ITERATIONS: 600000;
@@ -41,6 +53,14 @@ export declare const PASSWORD_HASH: Readonly<{
          */
         MAX_SCRYPT_MEMORY_BYTES: number;
         MAX_PBKDF2_ITERATIONS: 10000000;
+        /**
+         * Upper bound on the output length of `derivePbkdf2` / `deriveScrypt`
+         * (and the provider's `deriveKey`). PBKDF2 cost scales linearly with
+         * the number of output blocks, so an unbounded `keyLength` multiplies
+         * the iteration count by an attacker-chosen factor. Password hashes
+         * are bounded separately by `MAX_KEY_BYTES`.
+         */
+        MAX_DERIVED_KEY_BYTES: 1024;
     }>;
 }>;
 /**

package/dist/cryptoConstants/cryptoConstants.security.js

@@ -2,10 +2,14 @@ import { TimeMs } from "@zudojs/constants";
 /**
  * Password hashing constants.
  *
- * Defaults follow current OWASP Password Storage Cheat Sheet guidance:
- * scrypt N=2^14, r=8, p=1 (minimum) and PBKDF2-HMAC-SHA256 with 600 000
- * iterations. `LIMITS` bounds parameters that are read back from stored
- * hashes so that a tampered or foreign record cannot force unbounded work.
+ * Defaults follow the OWASP Password Storage Cheat Sheet: scrypt N=2^14,
+ * r=8, p=5 (OWASP's N=2^14 row; p=1 is only adequate at N=2^17) and
+ * PBKDF2-HMAC-SHA256 with 600 000 iterations. `LIMITS` bounds parameters
+ * that are read back from stored hashes so that a tampered or foreign
+ * record cannot force unbounded work.
+ *
+ * New hashes are held to `SCRYPT.MIN_COST`; verification still accepts
+ * older stored hashes down to `LIMITS.MIN_SCRYPT_COST`.
  */
 export const PASSWORD_HASH = Object.freeze({
     SALT_BYTES: 16,
@@ -13,7 +17,15 @@ export const PASSWORD_HASH = Object.freeze({
     SCRYPT: Object.freeze({
         COST: 16_384,
         BLOCK_SIZE: 8,
+        /**
+         * Default `p` for key derivation (`deriveScrypt`). Left at 1: changing
+         * it would silently change every key derived with default options.
+         */
         PARALLELIZATION: 1,
+        /** Default `p` for new *password hashes* (OWASP N=2^14, r=8, p=5). */
+        PASSWORD_PARALLELIZATION: 5,
+        /** Floor on the cost of *new* hashes; `LIMITS.MIN_SCRYPT_COST` bounds verification. */
+        MIN_COST: 16_384,
     }),
     PBKDF2: Object.freeze({
         ITERATIONS: 600_000,
@@ -42,6 +54,14 @@ export const PASSWORD_HASH = Object.freeze({
          */
         MAX_SCRYPT_MEMORY_BYTES: 1024 * 1024 * 1024,
         MAX_PBKDF2_ITERATIONS: 10_000_000,
+        /**
+         * Upper bound on the output length of `derivePbkdf2` / `deriveScrypt`
+         * (and the provider's `deriveKey`). PBKDF2 cost scales linearly with
+         * the number of output blocks, so an unbounded `keyLength` multiplies
+         * the iteration count by an attacker-chosen factor. Password hashes
+         * are bounded separately by `MAX_KEY_BYTES`.
+         */
+        MAX_DERIVED_KEY_BYTES: 1024,
     }),
 });
 /**

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.validate.d.ts

@@ -1,9 +1,20 @@
 /**
  * Validates PBKDF2 key derivation options.
+ *
+ * Both floors and ceilings are enforced: `iterations` is bounded by
+ * `PASSWORD_HASH.LIMITS.MAX_PBKDF2_ITERATIONS` and `keyLength` by
+ * `PASSWORD_HASH.LIMITS.MAX_DERIVED_KEY_BYTES`, so a work factor read from
+ * configuration cannot request unbounded CPU time.
  */
 export declare function validatePbkdf2Options(iterations: number, keyLength: number, salt: Uint8Array, digest?: unknown): void;
 /**
  * Validates scrypt key derivation options.
+ *
+ * `cost`, `blockSize` and `parallelization` are bounded by
+ * `PASSWORD_HASH.LIMITS`, and `128 * cost * blockSize` (the scrypt working
+ * memory) by `MAX_SCRYPT_MEMORY_BYTES`. Without these ceilings the memory
+ * "bound" passed to the provider was derived from the very parameters it
+ * was meant to bound, so a cost of 2^30 allocated terabytes.
  */
 export declare function validateScryptOptions(keyLength: number, cost: number, blockSize: number, parallelization: number, salt: Uint8Array, maxMemory?: number): void;
 //# sourceMappingURL=cryptoKeyDerivation.validate.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.validate.js

@@ -1,15 +1,24 @@
 import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { isPbkdf2Digest } from "../cryptoProvider/cryptoProvider.type.js";
+const LIMITS = PASSWORD_HASH.LIMITS;
 /**
  * Validates PBKDF2 key derivation options.
+ *
+ * Both floors and ceilings are enforced: `iterations` is bounded by
+ * `PASSWORD_HASH.LIMITS.MAX_PBKDF2_ITERATIONS` and `keyLength` by
+ * `PASSWORD_HASH.LIMITS.MAX_DERIVED_KEY_BYTES`, so a work factor read from
+ * configuration cannot request unbounded CPU time.
  */
 export function validatePbkdf2Options(iterations, keyLength, salt, digest = "sha256") {
     if (!Number.isInteger(iterations) ||
-        iterations < PASSWORD_HASH.PBKDF2.MIN_ITERATIONS) {
-        throw new RangeError(`PBKDF2 iterations must be at least ${PASSWORD_HASH.PBKDF2.MIN_ITERATIONS}.`);
+        iterations < PASSWORD_HASH.PBKDF2.MIN_ITERATIONS ||
+        iterations > LIMITS.MAX_PBKDF2_ITERATIONS) {
+        throw new RangeError(`PBKDF2 iterations must be an integer between ${PASSWORD_HASH.PBKDF2.MIN_ITERATIONS} and ${LIMITS.MAX_PBKDF2_ITERATIONS}.`);
     }
-    if (!Number.isInteger(keyLength) || keyLength < 16) {
-        throw new RangeError("PBKDF2 keyLength must be at least 16 bytes.");
+    if (!Number.isInteger(keyLength) ||
+        keyLength < 16 ||
+        keyLength > LIMITS.MAX_DERIVED_KEY_BYTES) {
+        throw new RangeError(`PBKDF2 keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`);
     }
     if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
         throw new RangeError("PBKDF2 salt must be at least 16 bytes.");
@@ -20,19 +29,37 @@ export function validatePbkdf2Options(iterations, keyLength, salt, digest = "sha
 }
 /**
  * Validates scrypt key derivation options.
+ *
+ * `cost`, `blockSize` and `parallelization` are bounded by
+ * `PASSWORD_HASH.LIMITS`, and `128 * cost * blockSize` (the scrypt working
+ * memory) by `MAX_SCRYPT_MEMORY_BYTES`. Without these ceilings the memory
+ * "bound" passed to the provider was derived from the very parameters it
+ * was meant to bound, so a cost of 2^30 allocated terabytes.
  */
 export function validateScryptOptions(keyLength, cost, blockSize, parallelization, salt, maxMemory) {
-    if (!Number.isInteger(keyLength) || keyLength < 16) {
-        throw new RangeError("scrypt keyLength must be at least 16 bytes.");
+    if (!Number.isInteger(keyLength) ||
+        keyLength < 16 ||
+        keyLength > LIMITS.MAX_DERIVED_KEY_BYTES) {
+        throw new RangeError(`scrypt keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`);
     }
-    if (!Number.isInteger(cost) || cost < 2 || (cost & (cost - 1)) !== 0) {
-        throw new RangeError("scrypt cost must be a power of two greater than or equal to 2.");
+    if (!Number.isInteger(cost) ||
+        cost < 2 ||
+        cost > LIMITS.MAX_SCRYPT_COST ||
+        (cost & (cost - 1)) !== 0) {
+        throw new RangeError(`scrypt cost must be a power of two between 2 and ${LIMITS.MAX_SCRYPT_COST}.`);
     }
-    if (!Number.isInteger(blockSize) || blockSize <= 0) {
-        throw new RangeError("scrypt blockSize must be a positive integer.");
+    if (!Number.isInteger(blockSize) ||
+        blockSize <= 0 ||
+        blockSize > LIMITS.MAX_SCRYPT_BLOCK_SIZE) {
+        throw new RangeError(`scrypt blockSize must be an integer between 1 and ${LIMITS.MAX_SCRYPT_BLOCK_SIZE}.`);
     }
-    if (!Number.isInteger(parallelization) || parallelization <= 0) {
-        throw new RangeError("scrypt parallelization must be a positive integer.");
+    if (!Number.isInteger(parallelization) ||
+        parallelization <= 0 ||
+        parallelization > LIMITS.MAX_SCRYPT_PARALLELIZATION) {
+        throw new RangeError(`scrypt parallelization must be an integer between 1 and ${LIMITS.MAX_SCRYPT_PARALLELIZATION}.`);
+    }
+    if (128 * cost * blockSize > LIMITS.MAX_SCRYPT_MEMORY_BYTES) {
+        throw new RangeError(`scrypt cost * blockSize exceeds the memory bound of ${LIMITS.MAX_SCRYPT_MEMORY_BYTES} bytes.`);
     }
     if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
         throw new RangeError("scrypt salt must be at least 16 bytes.");

package/dist/cryptoPassword/cryptoPassword.core.js

@@ -3,6 +3,7 @@ import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { assertPassword, validateParameters, } from "./cryptoPassword.validate.js";
 import { decodePasswordHash, PASSWORD_FORMAT_VERSION, } from "./cryptoPassword.codec.js";
+import { assertNewHashCost } from "./cryptoPassword.helper.js";
 /**
  * Hashes a password using scrypt.
  *
@@ -16,7 +17,8 @@ export async function hashPassword(password, options = {}) {
     const keyBytes = options.keyBytes ?? PASSWORD_HASH.KEY_BYTES;
     const cost = options.cost ?? PASSWORD_HASH.SCRYPT.COST;
     const blockSize = options.blockSize ?? PASSWORD_HASH.SCRYPT.BLOCK_SIZE;
-    const parallelization = options.parallelization ?? PASSWORD_HASH.SCRYPT.PARALLELIZATION;
+    const parallelization = options.parallelization ?? PASSWORD_HASH.SCRYPT.PASSWORD_PARALLELIZATION;
+    assertNewHashCost(cost);
     validateParameters({
         saltBytes,
         keyBytes,

package/dist/cryptoPassword/cryptoPassword.helper.d.ts

@@ -11,4 +11,15 @@ export declare function isPasswordHash(encoded: string): boolean;
  * Returns whether a password meets the basic requirements.
  */
 export declare function isValidPassword(password: string, minimumLength?: number): boolean;
+/**
+ * Refuses an scrypt cost below `PASSWORD_HASH.SCRYPT.MIN_COST` for a *new*
+ * password hash.
+ *
+ * `LIMITS.MIN_SCRYPT_COST` (2) only bounds what verification accepts, so
+ * older stored hashes stay verifiable; minting a new hash with `cost: 2`
+ * produced a hash that is effectively free to crack.
+ *
+ * @throws {RangeError} when `cost` is below the floor.
+ */
+export declare function assertNewHashCost(cost: number): void;
 //# sourceMappingURL=cryptoPassword.helper.d.ts.map

package/dist/cryptoPassword/cryptoPassword.helper.js

@@ -10,7 +10,7 @@ export function getDefaultPasswordHashOptions() {
         keyBytes: PASSWORD_HASH.KEY_BYTES,
         cost: PASSWORD_HASH.SCRYPT.COST,
         blockSize: PASSWORD_HASH.SCRYPT.BLOCK_SIZE,
-        parallelization: PASSWORD_HASH.SCRYPT.PARALLELIZATION,
+        parallelization: PASSWORD_HASH.SCRYPT.PASSWORD_PARALLELIZATION,
     };
 }
 /**
@@ -31,4 +31,19 @@ export function isPasswordHash(encoded) {
 export function isValidPassword(password, minimumLength = PASSWORD_MINIMUM_DEFAULT_LENGTH) {
     return typeof password === "string" && password.length >= minimumLength;
 }
+/**
+ * Refuses an scrypt cost below `PASSWORD_HASH.SCRYPT.MIN_COST` for a *new*
+ * password hash.
+ *
+ * `LIMITS.MIN_SCRYPT_COST` (2) only bounds what verification accepts, so
+ * older stored hashes stay verifiable; minting a new hash with `cost: 2`
+ * produced a hash that is effectively free to crack.
+ *
+ * @throws {RangeError} when `cost` is below the floor.
+ */
+export function assertNewHashCost(cost) {
+    if (typeof cost === "number" && cost < PASSWORD_HASH.SCRYPT.MIN_COST) {
+        throw new RangeError(`scrypt cost for a new password hash must be at least ${PASSWORD_HASH.SCRYPT.MIN_COST}.`);
+    }
+}
 //# sourceMappingURL=cryptoPassword.helper.js.map

package/dist/node/nodeCryptoProvider/operations/nodeCryptoProvider.derivation.js

@@ -2,10 +2,20 @@ import { isPbkdf2Digest } from "../../../cryptoProvider/cryptoProvider.type.js";
 import { pbkdf2, scrypt } from "node:crypto";
 import { toBytes } from "../nodeCryptoProvider.helper.js";
 import { keyDerivationError } from "../../../cryptoErrors/cryptoErrors.helper.js";
+import { PASSWORD_HASH } from "../../../cryptoConstants/cryptoConstants.security.js";
 /** Hard floors applied at the provider boundary. */
 const PROVIDER_MIN_SALT_BYTES = 16;
 const PROVIDER_MIN_KEY_BYTES = 16;
 const PROVIDER_MIN_PBKDF2_ITERATIONS = 1_000;
+/**
+ * Hard ceilings applied at the provider boundary.
+ *
+ * The provider is reachable directly (`provider.deriveKey`) and through
+ * custom wrappers, so the same `PASSWORD_HASH.LIMITS` that bound stored
+ * password hashes are enforced here too. Without them the scrypt memory
+ * bound was computed from the requested cost, which is no bound at all.
+ */
+const PROVIDER_LIMITS = PASSWORD_HASH.LIMITS;
 const DEFAULT_PBKDF2_ITERATIONS = 600_000;
 const DEFAULT_SCRYPT_COST = 16_384;
 const DEFAULT_SCRYPT_BLOCK_SIZE = 8;
@@ -27,8 +37,10 @@ function validateCommon(options, algorithm) {
     if (!(salt instanceof Uint8Array) || salt.byteLength < PROVIDER_MIN_SALT_BYTES) {
         throw keyDerivationError(`Salt must be at least ${PROVIDER_MIN_SALT_BYTES} bytes.`, algorithm);
     }
-    if (!Number.isInteger(keyLength) || keyLength < PROVIDER_MIN_KEY_BYTES) {
-        throw keyDerivationError(`keyLength must be an integer of at least ${PROVIDER_MIN_KEY_BYTES}.`, algorithm);
+    if (!Number.isInteger(keyLength) ||
+        keyLength < PROVIDER_MIN_KEY_BYTES ||
+        keyLength > PROVIDER_LIMITS.MAX_DERIVED_KEY_BYTES) {
+        throw keyDerivationError(`keyLength must be an integer between ${PROVIDER_MIN_KEY_BYTES} and ${PROVIDER_LIMITS.MAX_DERIVED_KEY_BYTES}.`, algorithm);
     }
     return { password, salt, keyLength };
 }
@@ -39,8 +51,9 @@ export async function deriveKey(options) {
             const iterations = options.iterations ?? DEFAULT_PBKDF2_ITERATIONS;
             const digest = options.digest ?? "sha256";
             if (!Number.isInteger(iterations) ||
-                iterations < PROVIDER_MIN_PBKDF2_ITERATIONS) {
-                throw keyDerivationError(`PBKDF2 iterations must be an integer of at least ${PROVIDER_MIN_PBKDF2_ITERATIONS}.`, "pbkdf2");
+                iterations < PROVIDER_MIN_PBKDF2_ITERATIONS ||
+                iterations > PROVIDER_LIMITS.MAX_PBKDF2_ITERATIONS) {
+                throw keyDerivationError(`PBKDF2 iterations must be an integer between ${PROVIDER_MIN_PBKDF2_ITERATIONS} and ${PROVIDER_LIMITS.MAX_PBKDF2_ITERATIONS}.`, "pbkdf2");
             }
             if (!isPbkdf2Digest(digest)) {
                 throw keyDerivationError(`Unsupported PBKDF2 digest: ${String(digest)}.`, "pbkdf2");
@@ -66,14 +79,24 @@ export async function deriveKey(options) {
             const N = options.memoryCost ?? DEFAULT_SCRYPT_COST;
             const r = options.blockSize ?? DEFAULT_SCRYPT_BLOCK_SIZE;
             const p = options.parallelism ?? DEFAULT_SCRYPT_PARALLELISM;
-            if (!Number.isInteger(N) || N < 2 || (N & (N - 1)) !== 0) {
-                throw keyDerivationError("scrypt cost must be a power of two greater than or equal to 2.", "scrypt");
+            if (!Number.isInteger(N) ||
+                N < 2 ||
+                N > PROVIDER_LIMITS.MAX_SCRYPT_COST ||
+                (N & (N - 1)) !== 0) {
+                throw keyDerivationError(`scrypt cost must be a power of two between 2 and ${PROVIDER_LIMITS.MAX_SCRYPT_COST}.`, "scrypt");
+            }
+            if (!Number.isInteger(r) ||
+                r <= 0 ||
+                r > PROVIDER_LIMITS.MAX_SCRYPT_BLOCK_SIZE) {
+                throw keyDerivationError(`scrypt blockSize must be an integer between 1 and ${PROVIDER_LIMITS.MAX_SCRYPT_BLOCK_SIZE}.`, "scrypt");
             }
-            if (!Number.isInteger(r) || r <= 0) {
-                throw keyDerivationError("scrypt blockSize must be a positive integer.", "scrypt");
+            if (!Number.isInteger(p) ||
+                p <= 0 ||
+                p > PROVIDER_LIMITS.MAX_SCRYPT_PARALLELIZATION) {
+                throw keyDerivationError(`scrypt parallelism must be an integer between 1 and ${PROVIDER_LIMITS.MAX_SCRYPT_PARALLELIZATION}.`, "scrypt");
             }
-            if (!Number.isInteger(p) || p <= 0) {
-                throw keyDerivationError("scrypt parallelism must be a positive integer.", "scrypt");
+            if (128 * N * r > PROVIDER_LIMITS.MAX_SCRYPT_MEMORY_BYTES) {
+                throw keyDerivationError(`scrypt cost * blockSize exceeds the memory bound of ${PROVIDER_LIMITS.MAX_SCRYPT_MEMORY_BYTES} bytes.`, "scrypt");
             }
             const maxmem = options.maxMemory ?? defaultScryptMaxMemory(N, r, p);
             if (!Number.isInteger(maxmem) || maxmem <= 0) {

package/dist/node/nodeCryptoProvider/operations/nodeCryptoProvider.password.d.ts

@@ -3,9 +3,10 @@ import type { CryptoInput, PasswordHashProviderOptions } from "../../../cryptoPr
  * Hashes a password with scrypt (default) or PBKDF2 and returns the
  * self-describing, versioned encoding produced by `encodePasswordHash`.
  *
- * The encoded string is validated against `PASSWORD_HASH.LIMITS`, so the
- * provider refuses insecure parameters (short salts, tiny work factors)
- * instead of producing a hash that can never be verified.
+ * The encoded string is validated against `PASSWORD_HASH.LIMITS`, and a
+ * scrypt cost below `PASSWORD_HASH.SCRYPT.MIN_COST` (or PBKDF2 iterations
+ * below `PBKDF2.MIN_ITERATIONS`) is refused, so the provider does not mint
+ * hashes with short salts or tiny work factors.
  */
 export declare function hashPassword(password: CryptoInput, options?: PasswordHashProviderOptions): Promise<string>;
 /**

package/dist/node/nodeCryptoProvider/operations/nodeCryptoProvider.password.js

@@ -4,15 +4,17 @@ import { timingSafeEqual } from "../../../compare/compare.helper.js";
 import { CryptoAlgorithm } from "../../../cryptoConstants/cryptoConstants.type.js";
 import { PASSWORD_HASH } from "../../../cryptoConstants/cryptoConstants.security.js";
 import { PASSWORD_FORMAT_VERSION, decodePasswordHash, encodePasswordHash, pbkdf2PasswordAlgorithm, } from "../../../cryptoPassword/cryptoPassword.codec.js";
+import { assertNewHashCost } from "../../../cryptoPassword/cryptoPassword.helper.js";
 import { deriveKey } from "./nodeCryptoProvider.derivation.js";
 import { keyDerivationError } from "../../../cryptoErrors/cryptoErrors.helper.js";
 /**
  * Hashes a password with scrypt (default) or PBKDF2 and returns the
  * self-describing, versioned encoding produced by `encodePasswordHash`.
  *
- * The encoded string is validated against `PASSWORD_HASH.LIMITS`, so the
- * provider refuses insecure parameters (short salts, tiny work factors)
- * instead of producing a hash that can never be verified.
+ * The encoded string is validated against `PASSWORD_HASH.LIMITS`, and a
+ * scrypt cost below `PASSWORD_HASH.SCRYPT.MIN_COST` (or PBKDF2 iterations
+ * below `PBKDF2.MIN_ITERATIONS`) is refused, so the provider does not mint
+ * hashes with short salts or tiny work factors.
  */
 export async function hashPassword(password, options) {
     const algorithm = options?.algorithm ?? "scrypt";
@@ -23,7 +25,8 @@ export async function hashPassword(password, options) {
         case "scrypt": {
             const cost = options?.memoryCost ?? PASSWORD_HASH.SCRYPT.COST;
             const blockSize = options?.blockSize ?? PASSWORD_HASH.SCRYPT.BLOCK_SIZE;
-            const parallelization = options?.parallelism ?? PASSWORD_HASH.SCRYPT.PARALLELIZATION;
+            const parallelization = options?.parallelism ?? PASSWORD_HASH.SCRYPT.PASSWORD_PARALLELIZATION;
+            assertNewHashCost(cost);
             // Validate before deriving so invalid parameters fail fast.
             const placeholder = new Uint8Array(keyBytes);
             encodePasswordHash({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/crypto",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Cryptographic primitives for hashing, encryption, tokens, and secure random generation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,10 +23,14 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"