@zudojs/crypto 1.0.0 → 1.1.0

package/README.md

@@ -43,7 +43,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
-- Key derivation: PBKDF2 (sha256/384/512, 600 000 iterations by default) and scrypt (cost, block size, parallelization, memory bound)
+- 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

@@ -41,6 +41,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

@@ -42,6 +42,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/crypto",
-  "version": "1.0.0",
+  "version": "1.1.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.0.1",
+    "@zudojs/errors": "1.0.1"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"