@zudojs/crypto 0.1.0 → 1.0.0

package/dist/cryptoProvider/types/cryptoKeyDerivation.type.d.ts

@@ -1,22 +1,58 @@
-import type { KeyDerivationAlgorithm, CryptoInput } from "../cryptoProvider.type.js";
+import type { KeyDerivationAlgorithm, CryptoInput, Pbkdf2Digest } from "../cryptoProvider.type.js";
+import type { CryptoAlgorithm } from "../../cryptoConstants/cryptoConstants.type.js";
+/**
+ * Algorithm labels produced by the public key derivation helpers.
+ *
+ * These are the values actually present on `DerivedKeyResult.algorithm`.
+ */
+export type DerivedKeyAlgorithm = CryptoAlgorithm.PBKDF2_SHA256 | CryptoAlgorithm.PBKDF2_SHA384 | CryptoAlgorithm.PBKDF2_SHA512 | CryptoAlgorithm.SCRYPT;
 /**
  * Result of a key derivation operation.
  */
 export interface DerivedKeyResult {
     readonly key: Uint8Array;
     readonly salt: Uint8Array;
-    readonly algorithm: KeyDerivationAlgorithm;
+    readonly algorithm: DerivedKeyAlgorithm;
+    /** Digest used by PBKDF2; absent for scrypt. */
+    readonly digest?: Pbkdf2Digest;
 }
 /**
- * Options for key derivation.
+ * Options for provider-level key derivation.
  */
 export interface DeriveKeyOptions {
     readonly password: CryptoInput;
     readonly salt: Uint8Array;
     readonly algorithm: KeyDerivationAlgorithm;
     readonly keyLength?: number;
+    /** PBKDF2 iteration count. */
     readonly iterations?: number;
+    /** PBKDF2 digest (default sha256). */
+    readonly digest?: Pbkdf2Digest;
+    /** scrypt cost parameter N. */
+    readonly memoryCost?: number;
+    /** scrypt block size parameter r. */
+    readonly blockSize?: number;
+    /** scrypt parallelization parameter p. */
+    readonly parallelism?: number;
+    /** scrypt memory upper bound in bytes (default derived from N, r, p). */
+    readonly maxMemory?: number;
+}
+/**
+ * Options for provider-level password hashing.
+ */
+export interface PasswordHashProviderOptions {
+    readonly algorithm?: KeyDerivationAlgorithm;
+    /** scrypt cost N. */
     readonly memoryCost?: number;
+    /** PBKDF2 iteration count. */
+    readonly timeCost?: number;
+    /** PBKDF2 digest (default sha256). */
+    readonly digest?: Pbkdf2Digest;
+    /** scrypt block size r. */
+    readonly blockSize?: number;
+    /** scrypt parallelization p. */
     readonly parallelism?: number;
+    readonly keyBytes?: number;
+    readonly salt?: Uint8Array;
 }
 //# sourceMappingURL=cryptoKeyDerivation.type.d.ts.map

package/dist/cryptoProvider/types/cryptoSignature.type.d.ts

@@ -1,18 +1,18 @@
-import type { SignatureAlgorithm } from "../cryptoProvider.type.js";
+import type { CryptoInput, SignatureAlgorithm } from "../cryptoProvider.type.js";
 /**
  * Options for signing.
  */
 export interface SignOptions {
-    readonly key: Uint8Array;
-    readonly data: Uint8Array;
+    readonly key: CryptoInput;
+    readonly data: CryptoInput;
     readonly algorithm?: SignatureAlgorithm;
 }
 /**
  * Options for verification.
  */
 export interface VerifyOptions {
-    readonly key: Uint8Array;
-    readonly data: Uint8Array;
+    readonly key: CryptoInput;
+    readonly data: CryptoInput;
     readonly signature: Uint8Array;
     readonly algorithm?: SignatureAlgorithm;
 }

package/dist/cryptoProvider/types/index.d.ts

@@ -7,6 +7,6 @@
 export type { HashResult, HashEncoding } from "./cryptoHash.type.js";
 export type { EncryptedData, EncryptOptions, DecryptOptions, } from "./cryptoCipher.type.js";
 export type { SignOptions, VerifyOptions } from "./cryptoSignature.type.js";
-export type { DerivedKeyResult, DeriveKeyOptions, } from "./cryptoKeyDerivation.type.js";
+export type { DerivedKeyResult, DerivedKeyAlgorithm, DeriveKeyOptions, PasswordHashProviderOptions, } from "./cryptoKeyDerivation.type.js";
 export type { RandomTokenOptions } from "./cryptoRandom.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cryptoRandom/cryptoRandom.choice.d.ts

@@ -1,14 +1,17 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Generates a cryptographically secure random boolean.
  */
-export declare function randomBoolean(): Promise<boolean>;
+export declare function randomBoolean(provider?: CryptoProvider): Promise<boolean>;
 /**
  * Generates a random value from a collection.
+ *
+ * A single-element collection returns that element.
  */
-export declare function randomChoice<T>(values: readonly T[]): Promise<T>;
+export declare function randomChoice<T>(values: readonly T[], provider?: CryptoProvider): Promise<T>;
 /**
  * Fills an existing Uint8Array with cryptographically secure
  * random bytes.
  */
-export declare function fillRandomBytes(target: Uint8Array): Promise<Uint8Array>;
+export declare function fillRandomBytes(target: Uint8Array, provider?: CryptoProvider): Promise<Uint8Array>;
 //# sourceMappingURL=cryptoRandom.choice.d.ts.map

package/dist/cryptoRandom/cryptoRandom.choice.js

@@ -1,16 +1,17 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-const provider = createNodeCryptoProvider();
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 /**
  * Generates a cryptographically secure random boolean.
  */
-export async function randomBoolean() {
+export async function randomBoolean(provider = getDefaultCryptoProvider()) {
     return (await provider.randomInt(0, 2)) === 1;
 }
 /**
  * Generates a random value from a collection.
+ *
+ * A single-element collection returns that element.
  */
-export async function randomChoice(values) {
-    if (values.length === 0) {
+export async function randomChoice(values, provider = getDefaultCryptoProvider()) {
+    if (!Array.isArray(values) || values.length === 0) {
         throw new RangeError("Cannot choose from an empty collection.");
     }
     return values[await provider.randomInt(0, values.length)];
@@ -19,10 +20,13 @@ export async function randomChoice(values) {
  * Fills an existing Uint8Array with cryptographically secure
  * random bytes.
  */
-export async function fillRandomBytes(target) {
+export async function fillRandomBytes(target, provider = getDefaultCryptoProvider()) {
     if (!(target instanceof Uint8Array)) {
         throw new TypeError("target must be a Uint8Array.");
     }
+    if (target.byteLength === 0) {
+        return target;
+    }
     const bytes = await provider.randomBytes(target.byteLength);
     target.set(bytes);
     return target;

package/dist/cryptoRandom/cryptoRandom.core.d.ts

@@ -1,21 +1,24 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Generates cryptographically secure random bytes.
  */
-export declare function randomBytesSecure(length: number): Promise<Uint8Array>;
+export declare function randomBytesSecure(length: number, provider?: CryptoProvider): Promise<Uint8Array>;
 /**
- * Generates a cryptographically secure random integer.
+ * Generates a cryptographically secure, uniformly distributed integer.
  *
  * The returned value is in the range:
  * min <= value < max
+ *
+ * Ranges up to 2^48 are supported; a range of one value returns `min`.
  */
-export declare function randomInteger(min: number, max: number): Promise<number>;
+export declare function randomInteger(min: number, max: number, provider?: CryptoProvider): Promise<number>;
 /**
  * Generates a cryptographically secure random integer
  * from zero up to, but excluding, max.
  */
-export declare function randomIntegerBelow(max: number): Promise<number>;
+export declare function randomIntegerBelow(max: number, provider?: CryptoProvider): Promise<number>;
 /**
  * Generates a random UUID v4.
  */
-export declare function randomUuid(): Promise<string>;
+export declare function randomUuid(provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoRandom.core.d.ts.map

package/dist/cryptoRandom/cryptoRandom.core.js

@@ -1,31 +1,32 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-const provider = createNodeCryptoProvider();
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 /**
  * Generates cryptographically secure random bytes.
  */
-export async function randomBytesSecure(length) {
+export async function randomBytesSecure(length, provider = getDefaultCryptoProvider()) {
     return provider.randomBytes(length);
 }
 /**
- * Generates a cryptographically secure random integer.
+ * Generates a cryptographically secure, uniformly distributed integer.
  *
  * The returned value is in the range:
  * min <= value < max
+ *
+ * Ranges up to 2^48 are supported; a range of one value returns `min`.
  */
-export async function randomInteger(min, max) {
+export async function randomInteger(min, max, provider = getDefaultCryptoProvider()) {
     return provider.randomInt(min, max);
 }
 /**
  * Generates a cryptographically secure random integer
  * from zero up to, but excluding, max.
  */
-export async function randomIntegerBelow(max) {
+export async function randomIntegerBelow(max, provider = getDefaultCryptoProvider()) {
     return provider.randomInt(0, max);
 }
 /**
  * Generates a random UUID v4.
  */
-export async function randomUuid() {
+export async function randomUuid(provider = getDefaultCryptoProvider()) {
     return provider.randomUUID();
 }
 //# sourceMappingURL=cryptoRandom.core.js.map

package/dist/cryptoRandom/cryptoRandom.string.d.ts

@@ -1,35 +1,37 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Generates a cryptographically secure random hexadecimal string.
  */
-export declare function randomHex(length: number): Promise<string>;
+export declare function randomHex(length: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a cryptographically secure random base64 string.
  */
-export declare function randomBase64(byteLength: number): Promise<string>;
+export declare function randomBase64(byteLength: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a cryptographically secure URL-safe random string.
  */
-export declare function randomBase64Url(byteLength: number): Promise<string>;
+export declare function randomBase64Url(byteLength: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a random token suitable for use as an opaque identifier.
  *
  * The returned token contains only URL-safe characters.
  */
-export declare function randomToken(byteLength?: number): Promise<string>;
+export declare function randomToken(byteLength?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a random numeric code.
  *
- * Leading zeroes are preserved.
+ * Leading zeroes are preserved. Each digit is drawn uniformly.
  */
-export declare function randomNumericCode(length?: number): Promise<string>;
+export declare function randomNumericCode(length?: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates a random alphanumeric token.
  */
-export declare function randomAlphanumeric(length: number): Promise<string>;
+export declare function randomAlphanumeric(length: number, provider?: CryptoProvider): Promise<string>;
 /**
  * Generates random characters from a caller-provided alphabet.
  *
- * The alphabet must not be empty.
+ * `length` counts Unicode code points (so astral characters count once),
+ * the alphabet must not be empty, and each character is drawn uniformly.
  */
-export declare function randomFromAlphabet(length: number, alphabet: string): Promise<string>;
+export declare function randomFromAlphabet(length: number, alphabet: string, provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoRandom.string.d.ts.map

package/dist/cryptoRandom/cryptoRandom.string.js

@@ -1,23 +1,30 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-const provider = createNodeCryptoProvider();
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+function assertLength(length, name = "length") {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new RangeError(`${name} must be a positive integer.`);
+    }
+}
 /**
  * Generates a cryptographically secure random hexadecimal string.
  */
-export async function randomHex(length) {
+export async function randomHex(length, provider = getDefaultCryptoProvider()) {
+    assertLength(length);
     const bytes = await provider.randomBytes(Math.ceil(length / 2));
     return Buffer.from(bytes).toString("hex").slice(0, length);
 }
 /**
  * Generates a cryptographically secure random base64 string.
  */
-export async function randomBase64(byteLength) {
+export async function randomBase64(byteLength, provider = getDefaultCryptoProvider()) {
+    assertLength(byteLength, "byteLength");
     const bytes = await provider.randomBytes(byteLength);
     return Buffer.from(bytes).toString("base64");
 }
 /**
  * Generates a cryptographically secure URL-safe random string.
  */
-export async function randomBase64Url(byteLength) {
+export async function randomBase64Url(byteLength, provider = getDefaultCryptoProvider()) {
+    assertLength(byteLength, "byteLength");
     const bytes = await provider.randomBytes(byteLength);
     return Buffer.from(bytes).toString("base64url");
 }
@@ -26,49 +33,41 @@ export async function randomBase64Url(byteLength) {
  *
  * The returned token contains only URL-safe characters.
  */
-export async function randomToken(byteLength = 32) {
-    return randomBase64Url(byteLength);
+export async function randomToken(byteLength = 32, provider) {
+    return randomBase64Url(byteLength, provider);
 }
 /**
  * Generates a random numeric code.
  *
- * Leading zeroes are preserved.
+ * Leading zeroes are preserved. Each digit is drawn uniformly.
  */
-export async function randomNumericCode(length = 6) {
-    let result = "";
-    while (result.length < length) {
-        const value = await provider.randomInt(0, 1_000_000);
-        result += String(value).padStart(6, "0");
-    }
-    return result.slice(0, length);
+export async function randomNumericCode(length = 6, provider = getDefaultCryptoProvider()) {
+    assertLength(length);
+    return randomFromAlphabet(length, "0123456789", provider);
 }
 /**
  * Generates a random alphanumeric token.
  */
-export async function randomAlphanumeric(length) {
-    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-    let result = "";
-    while (result.length < length) {
-        const index = await provider.randomInt(0, alphabet.length);
-        result += alphabet[index];
-    }
-    return result;
+export async function randomAlphanumeric(length, provider = getDefaultCryptoProvider()) {
+    return randomFromAlphabet(length, "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", provider);
 }
 /**
  * Generates random characters from a caller-provided alphabet.
  *
- * The alphabet must not be empty.
+ * `length` counts Unicode code points (so astral characters count once),
+ * the alphabet must not be empty, and each character is drawn uniformly.
  */
-export async function randomFromAlphabet(length, alphabet) {
-    if (alphabet.length === 0) {
+export async function randomFromAlphabet(length, alphabet, provider = getDefaultCryptoProvider()) {
+    assertLength(length);
+    if (typeof alphabet !== "string" || alphabet.length === 0) {
         throw new RangeError("alphabet must not be empty.");
     }
     const characters = Array.from(alphabet);
-    let result = "";
+    const result = [];
     while (result.length < length) {
         const index = await provider.randomInt(0, characters.length);
-        result += characters[index];
+        result.push(characters[index]);
     }
-    return result;
+    return result.join("");
 }
 //# sourceMappingURL=cryptoRandom.string.js.map

package/dist/cryptoService/cryptoService.core.d.ts

@@ -1,29 +1,61 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
+import { type CipherOptions, type CipherResult } from "./operations/cryptoService.cipher.js";
+import { type PasswordHashOptions, type PasswordHashResult } from "./operations/cryptoService.password.js";
+import { type Pbkdf2Options, type ScryptOptions, type DerivedKeyResult } from "./cryptoService.derivation.js";
+import { type TokenOptions } from "./operations/cryptoService.token.js";
+import { type CryptoEncoding } from "./cryptoService.encoding.js";
 import type { CryptoKey as ZudojsCryptoKey } from "../cryptoKey/cryptoKey.type.js";
+/**
+ * Options for constructing a CryptoService.
+ */
+export interface CryptoServiceOptions {
+    /** Provider used for every operation (defaults to the process-wide default). */
+    readonly provider?: CryptoProvider;
+}
 /**
  * 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 declare class CryptoService {
-    /** Generates a cryptographic key. */
+    private readonly configuredProvider;
+    constructor(options?: CryptoServiceOptions);
+    /**
+     * 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(): CryptoProvider;
+    private get provider();
+    /**
+     * 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.
+     */
     generateKey(algorithm?: CryptoAlgorithm): Promise<ZudojsCryptoKey>;
     /** Generates random bytes. */
     randomBytes(length?: number): Promise<Uint8Array>;
     /** Encrypts data using the supplied key. */
-    encrypt(plaintext: Uint8Array, key: Uint8Array, options?: import("./operations/cryptoService.cipher.js").CipherOptions): Promise<import("./operations/cryptoService.cipher.js").CipherResult>;
+    encrypt(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions): Promise<CipherResult>;
     /** Decrypts data using the supplied key. */
     decrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
     /** Hashes arbitrary data with SHA-256. */
     hash(value: string | Uint8Array): Promise<Uint8Array>;
     /** Hashes arbitrary data and returns hexadecimal output. */
     hashHex(value: string | Uint8Array): Promise<string>;
-    /** Hashes a password using the configured algorithm. */
-    hashPassword(password: string, options?: import("./operations/cryptoService.password.js").PasswordHashOptions): Promise<import("./operations/cryptoService.password.js").PasswordHashResult>;
+    /** Hashes a password using scrypt. */
+    hashPassword(password: string, options?: PasswordHashOptions): Promise<PasswordHashResult>;
     /** Verifies a password against a stored password hash. */
     verifyPassword(password: string, encodedHash: string): Promise<boolean>;
     /** Derives a cryptographic key from password material. */
-    deriveKey(password: string | Uint8Array, algorithm: CryptoAlgorithm, options?: import("./cryptoService.derivation.js").Pbkdf2Options | import("./cryptoService.derivation.js").ScryptOptions): Promise<import("./cryptoService.derivation.js").DerivedKeyResult>;
+    deriveKey(password: string | Uint8Array, algorithm: CryptoAlgorithm, options?: Pbkdf2Options | ScryptOptions): Promise<DerivedKeyResult>;
     /** Generates a cryptographically secure opaque token. */
-    generateToken(options?: import("./operations/cryptoService.token.js").TokenOptions): Promise<string>;
+    generateToken(options?: TokenOptions): Promise<string>;
     /** Generates a secure one-time password. */
     generateOtp(digits?: number): Promise<string>;
     /** Hashes an opaque token before database storage. */
@@ -31,16 +63,22 @@ export declare class CryptoService {
     /** Verifies an opaque token against its stored hash. */
     verifyToken(token: string, expectedHash: string): Promise<boolean>;
     /** Encodes binary data. */
-    encode(value: Uint8Array, encoding?: import("./cryptoService.encoding.js").CryptoEncoding): string;
+    encode(value: Uint8Array, encoding?: CryptoEncoding): string;
     /** Decodes encoded binary data. */
-    decode(value: string, encoding?: import("./cryptoService.encoding.js").CryptoEncoding): Uint8Array;
+    decode(value: string, encoding?: CryptoEncoding): Uint8Array;
 }
 /**
  * Creates a new CryptoService instance.
  */
-export declare function createCryptoService(): CryptoService;
+export declare function createCryptoService(options?: CryptoServiceOptions): CryptoService;
 /**
  * Default crypto service instance.
+ *
+ * Construction is trivial (no provider is created until first use).
  */
 export declare const cryptoService: CryptoService;
+/**
+ * Returns the default crypto service instance.
+ */
+export declare function getCryptoService(): CryptoService;
 //# sourceMappingURL=cryptoService.core.d.ts.map

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