@zudojs/crypto 1.2.0 → 1.3.1

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/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,4 +1,5 @@
 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";
@@ -13,6 +14,8 @@ import { assertNewHashCost } from "./cryptoPassword.helper.js";
 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;
@@ -58,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/crypto",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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.1.0",
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0"
   },
   "license": "MIT",
   "author": {
@@ -33,7 +33,7 @@
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "hashing",
     "security"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-crypto",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },