@zudojs/crypto 1.1.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,7 +48,7 @@ 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
+- 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

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;

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,

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.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.1.0",
+  "version": "1.2.0",
   "description": "Cryptographic primitives for hashing, encryption, tokens, and secure random generation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,8 +23,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0"
   },
   "license": "MIT",
   "author": {