@zudojs/crypto 0.1.0 → 1.1.0

package/dist/cryptoService/cryptoService.core.js

@@ -1,83 +1,107 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-import { generateCryptoKey } from "../cryptoKey/cryptoKey.factory.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { generateCryptoKey, defaultKeyLength, } from "../cryptoKey/cryptoKey.factory.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
-import { createCryptoError } from "@zudojs/errors";
+import { CryptoOperation } from "@zudojs/errors";
+import { operationError, rethrowAsCryptoError, } from "../cryptoErrors/cryptoErrors.helper.js";
 import { serviceEncrypt, serviceDecrypt, } from "./operations/cryptoService.cipher.js";
 import { serviceHash, serviceHashHex, } from "./operations/cryptoService.hash.js";
 import { serviceHashPassword, serviceVerifyPassword, } from "./operations/cryptoService.password.js";
-import { serviceDeriveKey } from "./cryptoService.derivation.js";
+import { serviceDeriveKey, } from "./cryptoService.derivation.js";
 import { serviceGenerateToken, serviceGenerateOtp, serviceHashToken, serviceVerifyToken, } from "./operations/cryptoService.token.js";
-import { serviceEncode, serviceDecode } from "./cryptoService.encoding.js";
-const provider = createNodeCryptoProvider();
+import { serviceEncode, serviceDecode, } from "./cryptoService.encoding.js";
 /**
  * High-level service facade for cryptographic operations.
+ *
+ * Every failure is surfaced as a `CryptoError` whose `cause` holds the
+ * underlying error, so misconfiguration (wrong key length, invalid
+ * option) can be distinguished from environmental failures.
  */
 export class CryptoService {
-    /** Generates a cryptographic key. */
+    configuredProvider;
+    constructor(options = {}) {
+        this.configuredProvider = options.provider;
+    }
+    /**
+     * Returns the provider backing this service.
+     *
+     * When none was configured, the process-wide default is resolved on
+     * each call, so `setDefaultCryptoProvider` also affects this service.
+     */
+    getProvider() {
+        return this.configuredProvider ?? getDefaultCryptoProvider();
+    }
+    get provider() {
+        return this.getProvider();
+    }
+    /**
+     * Generates a random symmetric key sized for the algorithm.
+     *
+     * Asymmetric algorithms are rejected: random bytes are not a usable
+     * signing key. Use `generateEd25519KeyPair` for those.
+     */
     async generateKey(algorithm = CryptoAlgorithm.AES_256_GCM) {
-        const length = algorithm.includes("256")
-            ? 32
-            : algorithm.includes("384")
-                ? 48
-                : algorithm.includes("512")
-                    ? 64
-                    : 32;
-        return generateCryptoKey(length, { algorithm, extractable: true });
+        try {
+            return await generateCryptoKey(defaultKeyLength(algorithm), { algorithm, extractable: true }, this.provider);
+        }
+        catch (error) {
+            return rethrowAsCryptoError(error, (cause) => operationError("Key generation failed.", CryptoOperation.KEY_GENERATION, cause));
+        }
     }
     /** Generates random bytes. */
     async randomBytes(length = 32) {
-        if (!Number.isInteger(length) || length <= 0)
+        if (!Number.isInteger(length) || length <= 0) {
             throw new TypeError("Random byte length must be a positive integer.");
+        }
         try {
-            return await provider.randomBytes(length);
+            return await this.provider.randomBytes(length);
         }
-        catch {
-            throw createCryptoError("Failed to generate random bytes.", {});
+        catch (error) {
+            return rethrowAsCryptoError(error, (cause) => operationError("Failed to generate random bytes.", CryptoOperation.RANDOM, cause));
         }
     }
     /** Encrypts data using the supplied key. */
     async encrypt(plaintext, key, options) {
-        return serviceEncrypt(plaintext, key, options);
+        return serviceEncrypt(plaintext, key, options, this.provider);
     }
     /** Decrypts data using the supplied key. */
     async decrypt(ciphertext, key, iv, authTag, aad) {
-        return serviceDecrypt(ciphertext, key, iv, authTag, aad);
+        return serviceDecrypt(ciphertext, key, iv, authTag, aad, this.provider);
     }
     /** Hashes arbitrary data with SHA-256. */
     async hash(value) {
-        return serviceHash(value);
+        return serviceHash(value, this.provider);
     }
     /** Hashes arbitrary data and returns hexadecimal output. */
     async hashHex(value) {
-        return serviceHashHex(value);
+        return serviceHashHex(value, this.provider);
     }
-    /** Hashes a password using the configured algorithm. */
+    /** Hashes a password using scrypt. */
     async hashPassword(password, options) {
-        return serviceHashPassword(password, options);
+        return serviceHashPassword(password, options, this.provider);
     }
     /** Verifies a password against a stored password hash. */
     async verifyPassword(password, encodedHash) {
-        return serviceVerifyPassword(password, encodedHash);
+        return serviceVerifyPassword(password, encodedHash, this.provider);
     }
     /** Derives a cryptographic key from password material. */
     async deriveKey(password, algorithm, options) {
-        return serviceDeriveKey(password, algorithm, options);
+        return serviceDeriveKey(password, algorithm, options, this.provider);
     }
     /** Generates a cryptographically secure opaque token. */
     async generateToken(options) {
-        return serviceGenerateToken(options);
+        return serviceGenerateToken(options, this.provider);
     }
     /** Generates a secure one-time password. */
     async generateOtp(digits = 6) {
-        return serviceGenerateOtp(digits);
+        return serviceGenerateOtp(digits, this.provider);
     }
     /** Hashes an opaque token before database storage. */
     async hashToken(token) {
-        return serviceHashToken(token);
+        return serviceHashToken(token, this.provider);
     }
     /** Verifies an opaque token against its stored hash. */
     async verifyToken(token, expectedHash) {
-        return serviceVerifyToken(token, expectedHash);
+        return serviceVerifyToken(token, expectedHash, this.provider);
     }
     /** Encodes binary data. */
     encode(value, encoding = "base64url") {
@@ -91,11 +115,19 @@ export class CryptoService {
 /**
  * Creates a new CryptoService instance.
  */
-export function createCryptoService() {
-    return new CryptoService();
+export function createCryptoService(options = {}) {
+    return new CryptoService(options);
 }
 /**
  * Default crypto service instance.
+ *
+ * Construction is trivial (no provider is created until first use).
  */
 export const cryptoService = createCryptoService();
+/**
+ * Returns the default crypto service instance.
+ */
+export function getCryptoService() {
+    return cryptoService;
+}
 //# sourceMappingURL=cryptoService.core.js.map

package/dist/cryptoService/cryptoService.derivation.d.ts

@@ -1,6 +1,6 @@
-import type { DerivedKeyResult } from "../cryptoProvider/index.js";
+import type { CryptoProvider, DerivedKeyResult } from "../cryptoProvider/index.js";
 import type { Pbkdf2Options, ScryptOptions } from "../cryptoKeyDerivation/cryptoKeyDerivation.type.js";
-import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
+import type { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 export type { DerivedKeyResult, Pbkdf2Options, ScryptOptions };
-export declare function serviceDeriveKey(password: string | Uint8Array, algorithm: CryptoAlgorithm, options?: Pbkdf2Options | ScryptOptions): Promise<DerivedKeyResult>;
+export declare function serviceDeriveKey(password: string | Uint8Array, algorithm: CryptoAlgorithm, options?: Pbkdf2Options | ScryptOptions, provider?: CryptoProvider): Promise<DerivedKeyResult>;
 //# sourceMappingURL=cryptoService.derivation.d.ts.map

package/dist/cryptoService/cryptoService.derivation.js

@@ -1,12 +1,14 @@
 import { deriveKey } from "../cryptoKeyDerivation/cryptoKeyDerivation.core.js";
-import { cryptoKeyDerivationError } from "@zudojs/errors";
-import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
-export async function serviceDeriveKey(password, algorithm, options) {
+import { keyDerivationError, rethrowAsCryptoError, } from "../cryptoErrors/cryptoErrors.helper.js";
+export async function serviceDeriveKey(password, algorithm, options, provider) {
     try {
-        return await deriveKey(password, algorithm, options);
+        return await deriveKey(password, algorithm, {
+            ...options,
+            provider: options?.provider ?? provider,
+        });
     }
-    catch {
-        throw cryptoKeyDerivationError("Key derivation failed.", algorithm);
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => keyDerivationError("Key derivation failed.", algorithm, cause));
     }
 }
 //# sourceMappingURL=cryptoService.derivation.js.map

package/dist/cryptoService/cryptoService.encoding.js

@@ -1,19 +1,20 @@
 import { encode, decode } from "../cryptoEncoding/cryptoEncoding.core.js";
-import { createCryptoError } from "@zudojs/errors";
+import { CryptoOperation } from "@zudojs/errors";
+import { operationError, rethrowAsCryptoError, } from "../cryptoErrors/cryptoErrors.helper.js";
 export function serviceEncode(value, encoding = "base64url") {
     try {
         return encode(value, encoding);
     }
-    catch {
-        throw createCryptoError("Crypto encoding failed.", {});
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("Crypto encoding failed.", CryptoOperation.ENCODE, cause));
     }
 }
 export function serviceDecode(value, encoding = "base64url") {
     try {
         return decode(value, encoding);
     }
-    catch {
-        throw createCryptoError("Crypto decoding failed.", {});
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("Crypto decoding failed.", CryptoOperation.DECODE, cause));
     }
 }
 //# sourceMappingURL=cryptoService.encoding.js.map

package/dist/cryptoService/index.d.ts

@@ -3,9 +3,5 @@
  *
  * High-level cryptographic service interface.
  */
-export * from "./cryptoService.core.js";
-export { serviceEncrypt, serviceDecrypt, } from "./operations/cryptoService.cipher.js";
-export { serviceHash, serviceHashHex, } from "./operations/cryptoService.hash.js";
-export { serviceHashPassword, serviceVerifyPassword, } from "./operations/cryptoService.password.js";
-export { serviceGenerateToken, serviceGenerateOtp, serviceHashToken, serviceVerifyToken, } from "./operations/cryptoService.token.js";
+export { CryptoService, createCryptoService, cryptoService, getCryptoService, type CryptoServiceOptions, } from "./cryptoService.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cryptoService/index.js

@@ -3,9 +3,5 @@
  *
  * High-level cryptographic service interface.
  */
-export * from "./cryptoService.core.js";
-export { serviceEncrypt, serviceDecrypt, } from "./operations/cryptoService.cipher.js";
-export { serviceHash, serviceHashHex, } from "./operations/cryptoService.hash.js";
-export { serviceHashPassword, serviceVerifyPassword, } from "./operations/cryptoService.password.js";
-export { serviceGenerateToken, serviceGenerateOtp, serviceHashToken, serviceVerifyToken, } from "./operations/cryptoService.token.js";
+export { CryptoService, createCryptoService, cryptoService, getCryptoService, } from "./cryptoService.core.js";
 //# sourceMappingURL=index.js.map

package/dist/cryptoService/operations/cryptoService.cipher.d.ts

@@ -1,5 +1,6 @@
+import type { CryptoProvider } from "../../cryptoProvider/index.js";
 import type { CipherOptions, CipherResult } from "../../cryptoCipher/cryptoCipher.core.js";
 export type { CipherOptions, CipherResult };
-export declare function serviceEncrypt(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions): Promise<CipherResult>;
-export declare function serviceDecrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+export declare function serviceEncrypt(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions, provider?: CryptoProvider): Promise<CipherResult>;
+export declare function serviceDecrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array, provider?: CryptoProvider): Promise<Uint8Array>;
 //# sourceMappingURL=cryptoService.cipher.d.ts.map

package/dist/cryptoService/operations/cryptoService.cipher.js

@@ -1,19 +1,23 @@
 import { encrypt, decrypt } from "../../cryptoCipher/cryptoCipher.core.js";
-import { cryptoCipherError, CryptoOperation } from "@zudojs/errors";
-export async function serviceEncrypt(plaintext, key, options) {
+import { CryptoOperation } from "@zudojs/errors";
+import { cipherError, rethrowAsCryptoError, } from "../../cryptoErrors/cryptoErrors.helper.js";
+export async function serviceEncrypt(plaintext, key, options, provider) {
     try {
-        return await encrypt(plaintext, key, options);
+        return await encrypt(plaintext, key, {
+            ...options,
+            provider: options?.provider ?? provider,
+        });
     }
-    catch {
-        throw cryptoCipherError("Encryption failed.", CryptoOperation.ENCRYPT);
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => cipherError("Encryption failed.", CryptoOperation.ENCRYPT, "aes-256-gcm", cause));
     }
 }
-export async function serviceDecrypt(ciphertext, key, iv, authTag, aad) {
+export async function serviceDecrypt(ciphertext, key, iv, authTag, aad, provider) {
     try {
-        return await decrypt(ciphertext, key, iv, authTag, aad);
+        return await decrypt(ciphertext, key, iv, authTag, aad, provider);
     }
-    catch {
-        throw cryptoCipherError("Decryption failed.", CryptoOperation.DECRYPT);
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => cipherError("Decryption failed.", CryptoOperation.DECRYPT, "aes-256-gcm", cause));
     }
 }
 //# sourceMappingURL=cryptoService.cipher.js.map

package/dist/cryptoService/operations/cryptoService.hash.d.ts

@@ -1,3 +1,4 @@
-export declare function serviceHash(value: string | Uint8Array): Promise<Uint8Array>;
-export declare function serviceHashHex(value: string | Uint8Array): Promise<string>;
+import type { CryptoProvider } from "../../cryptoProvider/index.js";
+export declare function serviceHash(value: string | Uint8Array, provider?: CryptoProvider): Promise<Uint8Array>;
+export declare function serviceHashHex(value: string | Uint8Array, provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoService.hash.d.ts.map

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

@@ -1,16 +1,15 @@
-import { createNodeCryptoProvider } from "../../node/index.js";
+import { getDefaultCryptoProvider } from "../../cryptoProvider/cryptoProvider.default.js";
 import { encode } from "../../cryptoEncoding/cryptoEncoding.core.js";
-import { cryptoHashError } from "@zudojs/errors";
-const provider = createNodeCryptoProvider();
-export async function serviceHash(value) {
+import { hashError, rethrowAsCryptoError, } from "../../cryptoErrors/cryptoErrors.helper.js";
+export async function serviceHash(value, provider = getDefaultCryptoProvider()) {
     try {
         return await provider.hash("sha256", value);
     }
-    catch {
-        throw cryptoHashError("Hashing failed.", "sha256");
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => hashError("Hashing failed.", "sha256", cause));
     }
 }
-export async function serviceHashHex(value) {
-    return encode(await serviceHash(value), "hex");
+export async function serviceHashHex(value, provider) {
+    return encode(await serviceHash(value, provider), "hex");
 }
 //# sourceMappingURL=cryptoService.hash.js.map

package/dist/cryptoService/operations/cryptoService.password.d.ts

@@ -1,5 +1,10 @@
+import type { CryptoProvider } from "../../cryptoProvider/index.js";
 import type { PasswordHashOptions, PasswordHashResult } from "../../cryptoPassword/cryptoPassword.type.js";
 export type { PasswordHashOptions, PasswordHashResult };
-export declare function serviceHashPassword(password: string, options?: PasswordHashOptions): Promise<PasswordHashResult>;
-export declare function serviceVerifyPassword(password: string, encodedHash: string): Promise<boolean>;
+export declare function serviceHashPassword(password: string, options?: PasswordHashOptions, provider?: CryptoProvider): Promise<PasswordHashResult>;
+/**
+ * Verifies a password. Wrong passwords and malformed hashes yield false;
+ * non-string arguments are programmer errors and throw.
+ */
+export declare function serviceVerifyPassword(password: string, encodedHash: string, provider?: CryptoProvider): Promise<boolean>;
 //# sourceMappingURL=cryptoService.password.d.ts.map

package/dist/cryptoService/operations/cryptoService.password.js

@@ -1,19 +1,30 @@
 import { hashPassword, verifyPassword, } from "../../cryptoPassword/cryptoPassword.core.js";
-import { createCryptoError } from "@zudojs/errors";
-export async function serviceHashPassword(password, options) {
+import { CryptoOperation } from "@zudojs/errors";
+import { operationError, rethrowAsCryptoError, } from "../../cryptoErrors/cryptoErrors.helper.js";
+export async function serviceHashPassword(password, options, provider) {
     try {
-        return await hashPassword(password, options);
+        return await hashPassword(password, { ...options, provider });
     }
-    catch {
-        throw createCryptoError("Password hashing failed.", {});
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("Password hashing failed.", CryptoOperation.KEY_DERIVATION, cause));
     }
 }
-export async function serviceVerifyPassword(password, encodedHash) {
+/**
+ * Verifies a password. Wrong passwords and malformed hashes yield false;
+ * non-string arguments are programmer errors and throw.
+ */
+export async function serviceVerifyPassword(password, encodedHash, provider) {
+    if (typeof password !== "string") {
+        throw new TypeError("Password must be a string.");
+    }
+    if (typeof encodedHash !== "string") {
+        throw new TypeError("Encoded password hash must be a string.");
+    }
     try {
-        return await verifyPassword(password, encodedHash);
+        return await verifyPassword(password, encodedHash, provider);
     }
-    catch {
-        return false;
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("Password verification failed.", CryptoOperation.VERIFY_HASH, cause));
     }
 }
 //# sourceMappingURL=cryptoService.password.js.map

package/dist/cryptoService/operations/cryptoService.token.d.ts

@@ -1,7 +1,12 @@
+import type { CryptoProvider } from "../../cryptoProvider/index.js";
 import type { TokenOptions, TokenEncoding } from "../../cryptoToken/cryptoToken.core.js";
 export type { TokenOptions, TokenEncoding };
-export declare function serviceGenerateToken(options?: TokenOptions): Promise<string>;
-export declare function serviceGenerateOtp(digits?: number): Promise<string>;
-export declare function serviceHashToken(token: string): Promise<string>;
-export declare function serviceVerifyToken(token: string, expectedHash: string): Promise<boolean>;
+export declare function serviceGenerateToken(options?: TokenOptions, provider?: CryptoProvider): Promise<string>;
+export declare function serviceGenerateOtp(digits?: number, provider?: CryptoProvider): Promise<string>;
+export declare function serviceHashToken(token: string, provider?: CryptoProvider): Promise<string>;
+/**
+ * Verifies a token against its stored hash. Mismatches and malformed
+ * hashes yield false; non-string arguments throw.
+ */
+export declare function serviceVerifyToken(token: string, expectedHash: string, provider?: CryptoProvider): Promise<boolean>;
 //# sourceMappingURL=cryptoService.token.d.ts.map

package/dist/cryptoService/operations/cryptoService.token.js

@@ -1,36 +1,50 @@
 import { generateToken, generateOtp, } from "../../cryptoToken/cryptoToken.core.js";
 import { hashToken, verifyTokenHash, } from "../../cryptoToken/cryptoToken.hash.js";
-import { createCryptoError, cryptoHashError } from "@zudojs/errors";
-export async function serviceGenerateToken(options) {
+import { CryptoOperation } from "@zudojs/errors";
+import { hashError, operationError, rethrowAsCryptoError, } from "../../cryptoErrors/cryptoErrors.helper.js";
+export async function serviceGenerateToken(options, provider) {
     try {
-        return await generateToken(options);
+        return await generateToken({
+            ...options,
+            provider: options?.provider ?? provider,
+        });
     }
-    catch {
-        throw createCryptoError("Token generation failed.", {});
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("Token generation failed.", CryptoOperation.RANDOM, cause));
     }
 }
-export async function serviceGenerateOtp(digits = 6) {
+export async function serviceGenerateOtp(digits = 6, provider) {
     try {
-        return await generateOtp(digits);
+        return await generateOtp(digits, provider);
     }
-    catch {
-        throw createCryptoError("OTP generation failed.", {});
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => operationError("OTP generation failed.", CryptoOperation.RANDOM, cause));
     }
 }
-export async function serviceHashToken(token) {
+export async function serviceHashToken(token, provider) {
     try {
-        return await hashToken(token);
+        return await hashToken(token, provider);
     }
-    catch {
-        throw cryptoHashError("Token hashing failed.", "sha256");
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => hashError("Token hashing failed.", "sha256", cause));
     }
 }
-export async function serviceVerifyToken(token, expectedHash) {
+/**
+ * Verifies a token against its stored hash. Mismatches and malformed
+ * hashes yield false; non-string arguments throw.
+ */
+export async function serviceVerifyToken(token, expectedHash, provider) {
+    if (typeof token !== "string") {
+        throw new TypeError("Token must be a string.");
+    }
+    if (typeof expectedHash !== "string") {
+        throw new TypeError("Expected token hash must be a string.");
+    }
     try {
-        return await verifyTokenHash(token, expectedHash);
+        return await verifyTokenHash(token, expectedHash, provider);
     }
-    catch {
-        return false;
+    catch (error) {
+        return rethrowAsCryptoError(error, (cause) => hashError("Token verification failed.", "sha256", cause));
     }
 }
 //# sourceMappingURL=cryptoService.token.js.map

package/dist/cryptoSignature/cryptoSignature.core.d.ts

@@ -1,17 +1,25 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { CryptoInput } from "../cryptoProvider/index.js";
 import type { SignatureAlgorithm } from "../cryptoProvider/index.js";
 /**
- * Supported signature algorithms.
+ * Signature options.
+ *
+ * The algorithm binds the key type: RSA algorithms require RSA keys,
+ * ECDSA algorithms require EC keys and `ed25519` requires an Ed25519 key.
  */
 export type SignatureOptions = {
     readonly algorithm?: SignatureAlgorithm;
+    readonly provider?: CryptoProvider;
 };
 /**
- * Signs arbitrary data using a private key.
+ * Signs arbitrary data using a private key (PEM text, DER bytes or KeyObject).
  */
 export declare function sign(data: Uint8Array, privateKey: CryptoInput, options?: SignatureOptions): Promise<Uint8Array>;
 /**
  * Verifies a signature using a public key.
+ *
+ * Returns false for malformed keys or signatures; throws only when the
+ * algorithm is unsupported or incompatible with the key type.
  */
 export declare function verify(data: Uint8Array, signature: Uint8Array, publicKey: CryptoInput, options?: SignatureOptions): Promise<boolean>;
 /**

package/dist/cryptoSignature/cryptoSignature.core.js

@@ -1,9 +1,9 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-const provider = createNodeCryptoProvider();
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 /**
- * Signs arbitrary data using a private key.
+ * 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();
     return provider.sign({
         key: privateKey,
         data,
@@ -12,8 +12,12 @@ export async function sign(data, privateKey, options = {}) {
 }
 /**
  * Verifies a signature using a public key.
+ *
+ * Returns false for malformed keys or signatures; throws only when the
+ * algorithm is unsupported or incompatible with the key type.
  */
 export async function verify(data, signature, publicKey, options = {}) {
+    const provider = options.provider ?? getDefaultCryptoProvider();
     return provider.verify({
         key: publicKey,
         data,

package/dist/cryptoToken/cryptoToken.core.d.ts

@@ -1,3 +1,4 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Supported token encodings.
  */
@@ -9,47 +10,52 @@ export interface TokenOptions {
     readonly bytes?: number;
     readonly encoding?: TokenEncoding;
     readonly prefix?: string;
+    readonly provider?: CryptoProvider;
 }
 /**
  * Creates a cryptographically secure opaque token.
+ *
+ * The encoding is validated at runtime: only `hex`, `base64` and
+ * `base64url` are accepted, so a misconfigured `"utf8"` can never
+ * produce a lossy token.
  */
 export declare function generateToken(options?: TokenOptions): Promise<string>;
 /**
  * Generates a secure API key.
  */
-export declare function generateApiKey(prefix?: string, bytes?: number): Promise<string>;
+export declare function generateApiKey(prefix?: string, bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a secure session token.
  */
-export declare function generateSessionToken(bytes?: number): Promise<string>;
+export declare function generateSessionToken(bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a secure refresh token.
  */
-export declare function generateRefreshToken(bytes?: number): Promise<string>;
+export declare function generateRefreshToken(bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a secure verification token.
  */
-export declare function generateVerificationToken(bytes?: number): Promise<string>;
+export declare function generateVerificationToken(bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a secure password-reset token.
  */
-export declare function generatePasswordResetToken(bytes?: number): Promise<string>;
+export declare function generatePasswordResetToken(bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a secure CSRF token.
  */
-export declare function generateCsrfToken(bytes?: number): Promise<string>;
+export declare function generateCsrfToken(bytes?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a numeric one-time password.
  *
  * Leading zeroes are preserved.
  */
-export declare function generateOtp(digits?: number): Promise<string>;
+export declare function generateOtp(digits?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a short-lived email verification code.
  */
-export declare function generateEmailVerificationCode(digits?: number): Promise<string>;
+export declare function generateEmailVerificationCode(digits?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a short-lived login verification code.
  */
-export declare function generateLoginCode(digits?: number): Promise<string>;
+export declare function generateLoginCode(digits?: number, provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoToken.core.d.ts.map