@zudojs/crypto 1.1.0 → 1.3.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/cryptoCipher/cryptoCipher.core.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertProviderCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { AES_GCM } from "../cryptoConstants/cryptoConstants.type.js";
 import { CryptoOperation } from "@zudojs/errors";
 import { cipherError } from "../cryptoErrors/cryptoErrors.helper.js";
@@ -10,6 +11,7 @@ export async function encrypt(plaintext, key, options = {}) {
         throw cipherError(`AES-256-GCM iv must be ${AES_GCM.IV_BYTES} bytes.`, CryptoOperation.ENCRYPT, "aes-256-gcm");
     }
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertProviderCapability(provider, "encryption", CryptoOperation.ENCRYPT);
     const encrypted = await provider.encrypt({
         key,
         plaintext,
@@ -37,6 +39,7 @@ export async function decrypt(ciphertext, key, iv, authTag, aad, provider = getD
         authTag.byteLength !== AES_GCM.AUTH_TAG_BYTES) {
         throw cipherError(`AES-256-GCM authentication tag must be ${AES_GCM.AUTH_TAG_BYTES} bytes.`, CryptoOperation.DECRYPT, "aes-256-gcm");
     }
+    assertProviderCapability(provider, "encryption", CryptoOperation.DECRYPT);
     return provider.decrypt({
         key,
         encrypted: {

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/cryptoHash/cryptoHash.core.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertHashCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { isHashAlgorithmName } from "../cryptoProvider/cryptoProvider.type.js";
 import { encodeDigest } from "./cryptoHash.codec.js";
 /**
@@ -13,6 +14,7 @@ export async function hash(input, options = {}) {
         throw new TypeError(`Unsupported hash algorithm: ${String(algorithm)}.`);
     }
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertHashCapability(provider);
     const digest = await provider.hash(algorithm, input);
     const encoding = options.encoding ?? "hex";
     return Object.freeze({

package/dist/cryptoHash/cryptoHmac.core.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertHmacCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { isHmacAlgorithmName } from "../cryptoProvider/cryptoProvider.type.js";
 import { KEY_SIZE } from "../cryptoConstants/cryptoConstants.type.js";
 import { encodeDigest } from "./cryptoHash.codec.js";
@@ -18,6 +19,7 @@ export async function hmac(input, key, algorithm = "sha256", encoding = "hex", p
     if (key.byteLength < KEY_SIZE.MIN_HMAC_KEY_BYTES) {
         throw new RangeError(`HMAC key must be at least ${KEY_SIZE.MIN_HMAC_KEY_BYTES} bytes.`);
     }
+    assertHmacCapability(provider);
     const digest = await provider.hmac(algorithm, key, input);
     return encodeDigest(digest, encoding);
 }

package/dist/cryptoKey/cryptoKey.factory.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertHmacCapability, assertRandomCapability, } from "../cryptoProvider/cryptoProvider.capability.js";
 import { encode } from "../cryptoEncoding/cryptoEncoding.core.js";
 import { CryptoOperation } from "@zudojs/errors";
 import { keyError } from "../cryptoErrors/cryptoErrors.helper.js";
@@ -58,6 +59,8 @@ function validateKeyBytes(bytes, algorithm) {
  * Hashing and key-id generation are delegated to the supplied provider.
  */
 export async function createCryptoKey(bytes, options, provider = getDefaultCryptoProvider()) {
+    assertHmacCapability(provider);
+    assertRandomCapability(provider);
     validateKeyBytes(bytes, options.algorithm);
     const keyBytes = new Uint8Array(bytes);
     const digest = await provider.hmac("sha256", CRYPTO_KEY_FINGERPRINT_LABEL, keyBytes);
@@ -90,6 +93,7 @@ export async function generateCryptoKey(length, options, provider = getDefaultCr
     if (!Number.isInteger(length) || length <= 0) {
         throw new RangeError("Cryptographic key length must be a positive integer.");
     }
+    assertRandomCapability(provider);
     const bytes = await provider.randomBytes(length);
     return createCryptoKey(bytes, options, provider);
 }

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.core.js

@@ -1,4 +1,6 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { CryptoOperation } from "@zudojs/errors";
+import { assertProviderCapability, assertRandomCapability, } from "../cryptoProvider/cryptoProvider.capability.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { validatePbkdf2Options, validateScryptOptions, } from "./cryptoKeyDerivation.validate.js";
@@ -20,6 +22,8 @@ function pbkdf2Label(digest) {
  */
 export async function derivePbkdf2(password, options = {}) {
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertProviderCapability(provider, "keyDerivation", CryptoOperation.KEY_DERIVATION);
+    assertRandomCapability(provider);
     const iterations = options.iterations ?? PASSWORD_HASH.PBKDF2.ITERATIONS;
     const keyLength = options.keyLength ?? 32;
     const digest = options.digest ?? "sha256";
@@ -49,6 +53,8 @@ export async function derivePbkdf2(password, options = {}) {
  */
 export async function deriveScrypt(password, options = {}) {
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertProviderCapability(provider, "keyDerivation", CryptoOperation.KEY_DERIVATION);
+    assertRandomCapability(provider);
     const keyLength = options.keyLength ?? 32;
     const cost = options.cost ?? PASSWORD_HASH.SCRYPT.COST;
     const blockSize = options.blockSize ?? PASSWORD_HASH.SCRYPT.BLOCK_SIZE;

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.salt.js

@@ -1,8 +1,10 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 /**
  * Creates a random salt.
  */
 export async function generateSalt(length = 16, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     if (!Number.isInteger(length) || length < 16) {
         throw new RangeError("Salt length must be an integer of at least 16 bytes.");
     }

package/dist/cryptoPassword/cryptoPassword.core.js

@@ -1,8 +1,10 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertPasswordHashingCapability, assertRandomCapability, } from "../cryptoProvider/cryptoProvider.capability.js";
 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.
  *
@@ -12,11 +14,14 @@ import { decodePasswordHash, PASSWORD_FORMAT_VERSION, } from "./cryptoPassword.c
 export async function hashPassword(password, options = {}) {
     assertPassword(password);
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertPasswordHashingCapability(provider);
+    assertRandomCapability(provider);
     const saltBytes = options.saltBytes ?? PASSWORD_HASH.SALT_BYTES;
     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,
@@ -56,6 +61,7 @@ export async function hashPassword(password, options = {}) {
  * password also yields false.
  */
 export async function verifyPassword(password, encoded, provider = getDefaultCryptoProvider()) {
+    assertPasswordHashingCapability(provider);
     try {
         assertPassword(password);
         return await provider.verifyPassword(password, encoded);

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/cryptoProvider/cryptoProvider.capability.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Capability checks for a crypto provider.
+ *
+ * `CryptoCapabilities` is required on every provider, but nothing read it:
+ * a provider declaring `signing: false` still had `sign` called, and a
+ * provider that only implements part of the interface only failed once the
+ * missing method was reached — as a bare `TypeError` from deep inside an
+ * unrelated operation. Both are checked here instead, so an unsupported
+ * operation is refused by name at the boundary.
+ *
+ * @module cryptoProvider/cryptoProvider.capability
+ */
+import { CryptoOperation } from "@zudojs/errors";
+import type { CryptoProvider } from "./cryptoProvider.core.js";
+import type { CryptoCapabilities } from "./cryptoProvider.type.js";
+/**
+ * Throws unless the provider declares the capability an operation needs.
+ *
+ * A missing or malformed `capabilities` object fails the same way a `false`
+ * flag does: a provider that cannot describe itself is not one a
+ * secret-handling path should call blind.
+ *
+ * @param provider - The provider about to be used.
+ * @param capability - The capability the operation requires.
+ * @param operation - The operation being attempted, for the error.
+ * @throws {CryptoError} when the capability is not declared.
+ */
+export declare function assertProviderCapability(provider: CryptoProvider, capability: keyof CryptoCapabilities, operation: CryptoOperation): void;
+/**
+ * Throws unless the provider declares `random`. @see assertProviderCapability
+ *
+ * Every helper that draws bytes — tokens, salts, ids, nonces — calls this, so
+ * the operation name is fixed in one place rather than at each call site.
+ */
+export declare function assertRandomCapability(provider: CryptoProvider): void;
+/** Throws unless the provider declares `hash`. @see assertProviderCapability */
+export declare function assertHashCapability(provider: CryptoProvider): void;
+/** Throws unless the provider declares `hmac`. @see assertProviderCapability */
+export declare function assertHmacCapability(provider: CryptoProvider): void;
+/**
+ * Throws unless the provider declares `passwordHashing`.
+ *
+ * `verifyPassword` answers `false` for anything wrong with the password, so a
+ * provider that cannot hash would read as "wrong password" forever. That is a
+ * configuration failure, and it throws.
+ */
+export declare function assertPasswordHashingCapability(provider: CryptoProvider): void;
+//# sourceMappingURL=cryptoProvider.capability.d.ts.map

package/dist/cryptoProvider/cryptoProvider.capability.js

@@ -0,0 +1,68 @@
+/**
+ * Capability checks for a crypto provider.
+ *
+ * `CryptoCapabilities` is required on every provider, but nothing read it:
+ * a provider declaring `signing: false` still had `sign` called, and a
+ * provider that only implements part of the interface only failed once the
+ * missing method was reached — as a bare `TypeError` from deep inside an
+ * unrelated operation. Both are checked here instead, so an unsupported
+ * operation is refused by name at the boundary.
+ *
+ * @module cryptoProvider/cryptoProvider.capability
+ */
+import { CryptoError, CryptoOperation, ErrorCode } from "@zudojs/errors";
+/** The provider's reported name, without trusting it to be a string. */
+function providerName(provider) {
+    return typeof provider.name === "string" && provider.name.length > 0
+        ? provider.name
+        : "unnamed";
+}
+/**
+ * Throws unless the provider declares the capability an operation needs.
+ *
+ * A missing or malformed `capabilities` object fails the same way a `false`
+ * flag does: a provider that cannot describe itself is not one a
+ * secret-handling path should call blind.
+ *
+ * @param provider - The provider about to be used.
+ * @param capability - The capability the operation requires.
+ * @param operation - The operation being attempted, for the error.
+ * @throws {CryptoError} when the capability is not declared.
+ */
+export function assertProviderCapability(provider, capability, operation) {
+    const capabilities = provider.capabilities;
+    if (typeof capabilities !== "object" ||
+        capabilities === null ||
+        capabilities[capability] !== true) {
+        throw new CryptoError(`Crypto provider "${providerName(provider)}" does not support ` +
+            `${capability}: the "${operation}" operation was refused.`, { code: ErrorCode.CRYPTO, operation });
+    }
+}
+/**
+ * Throws unless the provider declares `random`. @see assertProviderCapability
+ *
+ * Every helper that draws bytes — tokens, salts, ids, nonces — calls this, so
+ * the operation name is fixed in one place rather than at each call site.
+ */
+export function assertRandomCapability(provider) {
+    assertProviderCapability(provider, "random", CryptoOperation.RANDOM);
+}
+/** Throws unless the provider declares `hash`. @see assertProviderCapability */
+export function assertHashCapability(provider) {
+    assertProviderCapability(provider, "hash", CryptoOperation.HASH);
+}
+/** Throws unless the provider declares `hmac`. @see assertProviderCapability */
+export function assertHmacCapability(provider) {
+    assertProviderCapability(provider, "hmac", CryptoOperation.HASH);
+}
+/**
+ * Throws unless the provider declares `passwordHashing`.
+ *
+ * `verifyPassword` answers `false` for anything wrong with the password, so a
+ * provider that cannot hash would read as "wrong password" forever. That is a
+ * configuration failure, and it throws.
+ */
+export function assertPasswordHashingCapability(provider) {
+    assertProviderCapability(provider, "passwordHashing", CryptoOperation.KEY_DERIVATION);
+}
+//# sourceMappingURL=cryptoProvider.capability.js.map

package/dist/cryptoProvider/cryptoProvider.default.d.ts

@@ -1,4 +1,18 @@
 import type { CryptoProvider } from "./cryptoProvider.core.js";
+/** Every method a `CryptoProvider` must implement. */
+export declare const CRYPTO_PROVIDER_METHODS: readonly ["randomBytes", "randomInt", "randomUUID", "hash", "hmac", "encrypt", "decrypt", "sign", "verify", "deriveKey", "hashPassword", "verifyPassword"];
+/**
+ * Throws unless `provider` is a complete {@link CryptoProvider}.
+ *
+ * Installing `{}` as the process-wide default used to succeed and then fail
+ * at the first `randomHex(16)` with a `TypeError` — arbitrarily far from the
+ * call that caused it. Every method and every capability flag is checked
+ * here, at install time.
+ *
+ * @param provider - The candidate provider.
+ * @throws {CryptoError} when a method or a capability flag is missing.
+ */
+export declare function assertCryptoProvider(provider: CryptoProvider): asserts provider is CryptoProvider;
 /**
  * Returns the process-wide default crypto provider, creating the Node
  * provider lazily on first use.
@@ -9,6 +23,13 @@ export declare function getDefaultCryptoProvider(): CryptoProvider;
  *
  * Every module-level helper (hash, encrypt, hashPassword, generateToken,
  * ...) that is not given an explicit provider uses this one.
+ *
+ * The provider is checked here rather than at first use: installing a partial
+ * object succeeded and then failed much later, inside whichever operation
+ * happened to reach the missing method first.
+ *
+ * @param provider - The provider to install process-wide.
+ * @throws {CryptoError} when a method or a capability flag is missing.
  */
 export declare function setDefaultCryptoProvider(provider: CryptoProvider): void;
 /**

package/dist/cryptoProvider/cryptoProvider.default.js

@@ -1,4 +1,60 @@
+import { CryptoError, CryptoOperation, ErrorCode } from "@zudojs/errors";
 import { createNodeCryptoProvider } from "../node/nodeCryptoProvider/nodeCryptoProvider.factory.js";
+/** Every method a `CryptoProvider` must implement. */
+export const CRYPTO_PROVIDER_METHODS = Object.freeze([
+    "randomBytes",
+    "randomInt",
+    "randomUUID",
+    "hash",
+    "hmac",
+    "encrypt",
+    "decrypt",
+    "sign",
+    "verify",
+    "deriveKey",
+    "hashPassword",
+    "verifyPassword",
+]);
+/** Every capability flag a `CryptoProvider` must declare. */
+const CRYPTO_CAPABILITY_FLAGS = Object.freeze([
+    "hash",
+    "hmac",
+    "encryption",
+    "signing",
+    "random",
+    "passwordHashing",
+    "keyDerivation",
+]);
+/**
+ * Throws unless `provider` is a complete {@link CryptoProvider}.
+ *
+ * Installing `{}` as the process-wide default used to succeed and then fail
+ * at the first `randomHex(16)` with a `TypeError` — arbitrarily far from the
+ * call that caused it. Every method and every capability flag is checked
+ * here, at install time.
+ *
+ * @param provider - The candidate provider.
+ * @throws {CryptoError} when a method or a capability flag is missing.
+ */
+export function assertCryptoProvider(provider) {
+    const candidate = provider;
+    for (const method of CRYPTO_PROVIDER_METHODS) {
+        if (typeof candidate[method] !== "function") {
+            throw new CryptoError(`Crypto provider is missing the "${method}" method: a provider must ` +
+                `implement all ${CRYPTO_PROVIDER_METHODS.length} operations.`, { code: ErrorCode.CRYPTO, operation: CryptoOperation.UNKNOWN });
+        }
+    }
+    const capabilities = candidate.capabilities;
+    if (typeof capabilities !== "object" || capabilities === null) {
+        throw new CryptoError("Crypto provider is missing its `capabilities` declaration.", { code: ErrorCode.CRYPTO, operation: CryptoOperation.UNKNOWN });
+    }
+    const flags = capabilities;
+    for (const flag of CRYPTO_CAPABILITY_FLAGS) {
+        if (typeof flags[flag] !== "boolean") {
+            throw new CryptoError(`Crypto provider capability "${flag}" must be a boolean.`, { code: ErrorCode.CRYPTO, operation: CryptoOperation.UNKNOWN });
+        }
+    }
+}
 let defaultProvider;
 /**
  * Returns the process-wide default crypto provider, creating the Node
@@ -15,11 +71,19 @@ export function getDefaultCryptoProvider() {
  *
  * Every module-level helper (hash, encrypt, hashPassword, generateToken,
  * ...) that is not given an explicit provider uses this one.
+ *
+ * The provider is checked here rather than at first use: installing a partial
+ * object succeeded and then failed much later, inside whichever operation
+ * happened to reach the missing method first.
+ *
+ * @param provider - The provider to install process-wide.
+ * @throws {CryptoError} when a method or a capability flag is missing.
  */
 export function setDefaultCryptoProvider(provider) {
     if (typeof provider !== "object" || provider === null) {
         throw new TypeError("Crypto provider must be an object.");
     }
+    assertCryptoProvider(provider);
     defaultProvider = provider;
 }
 /**

package/dist/cryptoProvider/index.d.ts

@@ -10,6 +10,7 @@ export type { CryptoProvider } from "./cryptoProvider.core.js";
 export type { CryptoCapabilities, HashAlgorithm, HmacAlgorithm, Pbkdf2Digest, EncryptionAlgorithm, SignatureAlgorithm, KeyDerivationAlgorithm, EncodingFormat, CryptoInput, } from "./cryptoProvider.type.js";
 export { isHashAlgorithmName, isHmacAlgorithmName, isPbkdf2Digest, isSignatureAlgorithmName, } from "./cryptoProvider.type.js";
 export type { RandomProvider, HashProvider, HmacProvider, EncryptionProvider, SigningProvider, KeyDerivationProvider, PasswordProvider, } from "./cryptoProvider.interface.js";
-export { getDefaultCryptoProvider, setDefaultCryptoProvider, resetDefaultCryptoProvider, } from "./cryptoProvider.default.js";
+export { getDefaultCryptoProvider, setDefaultCryptoProvider, resetDefaultCryptoProvider, assertCryptoProvider, CRYPTO_PROVIDER_METHODS, } from "./cryptoProvider.default.js";
+export { assertProviderCapability, assertRandomCapability, assertHashCapability, assertHmacCapability, assertPasswordHashingCapability, } from "./cryptoProvider.capability.js";
 export * from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cryptoProvider/index.js

@@ -1,4 +1,5 @@
 export { isHashAlgorithmName, isHmacAlgorithmName, isPbkdf2Digest, isSignatureAlgorithmName, } from "./cryptoProvider.type.js";
-export { getDefaultCryptoProvider, setDefaultCryptoProvider, resetDefaultCryptoProvider, } from "./cryptoProvider.default.js";
+export { getDefaultCryptoProvider, setDefaultCryptoProvider, resetDefaultCryptoProvider, assertCryptoProvider, CRYPTO_PROVIDER_METHODS, } from "./cryptoProvider.default.js";
+export { assertProviderCapability, assertRandomCapability, assertHashCapability, assertHmacCapability, assertPasswordHashingCapability, } from "./cryptoProvider.capability.js";
 export * from "./types/index.js";
 //# sourceMappingURL=index.js.map

package/dist/cryptoRandom/cryptoRandom.choice.js

@@ -1,8 +1,10 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 /**
  * Generates a cryptographically secure random boolean.
  */
 export async function randomBoolean(provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     return (await provider.randomInt(0, 2)) === 1;
 }
 /**
@@ -11,6 +13,7 @@ export async function randomBoolean(provider = getDefaultCryptoProvider()) {
  * A single-element collection returns that element.
  */
 export async function randomChoice(values, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     if (!Array.isArray(values) || values.length === 0) {
         throw new RangeError("Cannot choose from an empty collection.");
     }
@@ -21,6 +24,7 @@ export async function randomChoice(values, provider = getDefaultCryptoProvider()
  * random bytes.
  */
 export async function fillRandomBytes(target, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     if (!(target instanceof Uint8Array)) {
         throw new TypeError("target must be a Uint8Array.");
     }

package/dist/cryptoRandom/cryptoRandom.core.js

@@ -1,8 +1,10 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 /**
  * Generates cryptographically secure random bytes.
  */
 export async function randomBytesSecure(length, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     return provider.randomBytes(length);
 }
 /**
@@ -14,6 +16,7 @@ export async function randomBytesSecure(length, provider = getDefaultCryptoProvi
  * Ranges up to 2^48 are supported; a range of one value returns `min`.
  */
 export async function randomInteger(min, max, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     return provider.randomInt(min, max);
 }
 /**
@@ -21,12 +24,14 @@ export async function randomInteger(min, max, provider = getDefaultCryptoProvide
  * from zero up to, but excluding, max.
  */
 export async function randomIntegerBelow(max, provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     return provider.randomInt(0, max);
 }
 /**
  * Generates a random UUID v4.
  */
 export async function randomUuid(provider = getDefaultCryptoProvider()) {
+    assertRandomCapability(provider);
     return provider.randomUUID();
 }
 //# sourceMappingURL=cryptoRandom.core.js.map

package/dist/cryptoRandom/cryptoRandom.string.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 function assertLength(length, name = "length") {
     if (!Number.isInteger(length) || length <= 0) {
         throw new RangeError(`${name} must be a positive integer.`);
@@ -9,6 +10,7 @@ function assertLength(length, name = "length") {
  */
 export async function randomHex(length, provider = getDefaultCryptoProvider()) {
     assertLength(length);
+    assertRandomCapability(provider);
     const bytes = await provider.randomBytes(Math.ceil(length / 2));
     return Buffer.from(bytes).toString("hex").slice(0, length);
 }
@@ -17,6 +19,7 @@ export async function randomHex(length, provider = getDefaultCryptoProvider()) {
  */
 export async function randomBase64(byteLength, provider = getDefaultCryptoProvider()) {
     assertLength(byteLength, "byteLength");
+    assertRandomCapability(provider);
     const bytes = await provider.randomBytes(byteLength);
     return Buffer.from(bytes).toString("base64");
 }
@@ -25,6 +28,7 @@ export async function randomBase64(byteLength, provider = getDefaultCryptoProvid
  */
 export async function randomBase64Url(byteLength, provider = getDefaultCryptoProvider()) {
     assertLength(byteLength, "byteLength");
+    assertRandomCapability(provider);
     const bytes = await provider.randomBytes(byteLength);
     return Buffer.from(bytes).toString("base64url");
 }
@@ -59,6 +63,7 @@ export async function randomAlphanumeric(length, provider = getDefaultCryptoProv
  */
 export async function randomFromAlphabet(length, alphabet, provider = getDefaultCryptoProvider()) {
     assertLength(length);
+    assertRandomCapability(provider);
     if (typeof alphabet !== "string" || alphabet.length === 0) {
         throw new RangeError("alphabet must not be empty.");
     }

package/dist/cryptoService/cryptoService.core.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { generateCryptoKey, defaultKeyLength, } from "../cryptoKey/cryptoKey.factory.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import { CryptoOperation } from "@zudojs/errors";
@@ -52,6 +53,7 @@ export class CryptoService {
         if (!Number.isInteger(length) || length <= 0) {
             throw new TypeError("Random byte length must be a positive integer.");
         }
+        assertRandomCapability(this.provider);
         try {
             return await this.provider.randomBytes(length);
         }

package/dist/cryptoService/operations/cryptoService.hash.js

@@ -1,7 +1,9 @@
 import { getDefaultCryptoProvider } from "../../cryptoProvider/cryptoProvider.default.js";
+import { assertHashCapability } from "../../cryptoProvider/cryptoProvider.capability.js";
 import { encode } from "../../cryptoEncoding/cryptoEncoding.core.js";
 import { hashError, rethrowAsCryptoError, } from "../../cryptoErrors/cryptoErrors.helper.js";
 export async function serviceHash(value, provider = getDefaultCryptoProvider()) {
+    assertHashCapability(provider);
     try {
         return await provider.hash("sha256", value);
     }

package/dist/cryptoSignature/cryptoSignature.core.js

@@ -1,9 +1,12 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { CryptoOperation } from "@zudojs/errors";
+import { assertProviderCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 /**
  * Signs arbitrary data using a private key (PEM text, DER bytes or KeyObject).
  */
 export async function sign(data, privateKey, options = {}) {
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertProviderCapability(provider, "signing", CryptoOperation.SIGN);
     return provider.sign({
         key: privateKey,
         data,
@@ -18,6 +21,7 @@ export async function sign(data, privateKey, options = {}) {
  */
 export async function verify(data, signature, publicKey, options = {}) {
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertProviderCapability(provider, "signing", CryptoOperation.VERIFY_SIGNATURE);
     return provider.verify({
         key: publicKey,
         data,

package/dist/cryptoToken/cryptoToken.core.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { randomInteger } from "../cryptoRandom/cryptoRandom.core.js";
 import { assertBinaryEncoding } from "../cryptoEncoding/cryptoEncoding.core.js";
 import { RANDOM, TOKEN, TOKEN_PREFIX, } from "../cryptoConstants/cryptoConstants.token.js";
@@ -20,6 +21,7 @@ export async function generateToken(options = {}) {
         throw new TypeError("Token prefix must be a string.");
     }
     const provider = options.provider ?? getDefaultCryptoProvider();
+    assertRandomCapability(provider);
     const raw = await provider.randomBytes(bytes);
     const token = Buffer.from(raw).toString(encoding);
     return options.prefix ? `${options.prefix}${token}` : token;

package/dist/cryptoToken/cryptoToken.hash.js

@@ -1,4 +1,5 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { assertHashCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { encode } from "../cryptoEncoding/cryptoEncoding.core.js";
 import { isHex } from "../cryptoEncoding/encoding/cryptoEncoding.hex.js";
 import { timingSafeEqual } from "../compare/compare.helper.js";
@@ -9,6 +10,7 @@ import { timingSafeEqual } from "../compare/compare.helper.js";
  */
 export async function hashToken(token, provider = getDefaultCryptoProvider()) {
     assertToken(token);
+    assertHashCapability(provider);
     const digest = await provider.hash("sha256", token);
     return encode(digest, "hex");
 }
@@ -17,6 +19,7 @@ export async function hashToken(token, provider = getDefaultCryptoProvider()) {
  */
 export async function hashTokenBase64Url(token, provider = getDefaultCryptoProvider()) {
     assertToken(token);
+    assertHashCapability(provider);
     const digest = await provider.hash("sha256", token);
     return encode(digest, "base64url");
 }

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.3.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.1",
+    "@zudojs/errors": "1.2.0"
   },
   "license": "MIT",
   "author": {