@zudojs/crypto 0.1.0 → 1.1.0

package/dist/cryptoFactory/cryptoFactory.core.d.ts

@@ -1,26 +1,47 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import { CryptoService } from "../cryptoService/cryptoService.core.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import type { CryptoKey } from "../cryptoKey/cryptoKey.type.js";
+import type { PasswordHashResult } from "../cryptoPassword/cryptoPassword.type.js";
 import type { PasswordHashOptions } from "./cryptoFactory.password.js";
 import type { CryptoEncoding } from "./cryptoFactory.encoding.js";
+import type { TokenEncoding } from "../cryptoToken/cryptoToken.core.js";
 /**
  * Configuration used to create a CryptoFactory.
  */
 export interface CryptoFactoryOptions {
     readonly defaultKeyAlgorithm?: CryptoAlgorithm;
+    /** Default scrypt parameters; per-call options are merged on top. */
     readonly password?: PasswordHashOptions;
-    readonly encoding?: CryptoEncoding;
+    /** Default binary encoding for tokens and `encode`/`decode`. */
+    readonly encoding?: TokenEncoding;
+    /** Provider used for every operation. */
+    readonly provider?: CryptoProvider;
 }
 /**
  * Central factory for constructing and accessing crypto services.
+ *
+ * Options are deep-copied on construction, so later mutation of the
+ * caller's option objects cannot change the factory's behaviour.
  */
 export declare class CryptoFactory {
     private readonly options;
+    private readonly configuredProvider;
     private readonly service;
     constructor(options?: CryptoFactoryOptions);
+    private get provider();
     /** Returns the configured crypto service. */
     getService(): CryptoService;
-    /** Generates a key using the configured default algorithm. */
+    /**
+     * Returns the provider backing this factory (the process-wide default
+     * when none was configured).
+     */
+    getProvider(): CryptoProvider;
+    /**
+     * Generates a symmetric key using the configured default algorithm.
+     *
+     * Asymmetric algorithms are rejected.
+     */
     createKey(algorithm?: CryptoAlgorithm): Promise<CryptoKey>;
     /** Generates a secure opaque token. */
     createToken(bytes?: number, prefix?: string): Promise<string>;
@@ -38,16 +59,20 @@ export declare class CryptoFactory {
     createCsrfToken(): Promise<string>;
     /** Generates a numeric one-time password. */
     createOtp(digits?: number): Promise<string>;
-    /** Hashes a password using the configured password options. */
-    createPasswordHash(password: string, options?: PasswordHashOptions): Promise<import("../index.js").PasswordHashResult>;
+    /**
+     * Hashes a password using the configured password options.
+     *
+     * Per-call options are layered on top of the configured defaults.
+     */
+    createPasswordHash(password: string, options?: PasswordHashOptions): Promise<PasswordHashResult>;
     /** Verifies a password against a stored hash. */
     verifyPassword(password: string, encodedHash: string): Promise<boolean>;
     /** Encodes bytes using the configured default encoding. */
     encode(value: Uint8Array, encoding?: CryptoEncoding): string;
     /** Decodes binary data using the configured default encoding. */
     decode(value: string, encoding?: CryptoEncoding): Uint8Array;
-    /** Returns the factory configuration. */
-    getOptions(): Readonly<CryptoFactoryOptions>;
+    /** Returns a frozen copy of the factory configuration. */
+    getOptions(): Readonly<Required<Omit<CryptoFactoryOptions, "provider">>>;
 }
 /**
  * Creates a configured CryptoFactory.
@@ -55,6 +80,12 @@ export declare class CryptoFactory {
 export declare function createCryptoFactory(options?: CryptoFactoryOptions): CryptoFactory;
 /**
  * Default application crypto factory.
+ *
+ * Construction is trivial (no provider is created until first use).
  */
 export declare const cryptoFactory: CryptoFactory;
+/**
+ * Returns the default application crypto factory.
+ */
+export declare function getCryptoFactory(): CryptoFactory;
 //# sourceMappingURL=cryptoFactory.core.d.ts.map

package/dist/cryptoFactory/cryptoFactory.core.js

@@ -1,78 +1,97 @@
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 import { CryptoService, createCryptoService, } from "../cryptoService/cryptoService.core.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
-import { generateCryptoKey } from "../cryptoKey/cryptoKey.factory.js";
+import { generateCryptoKey, defaultKeyLength, } from "../cryptoKey/cryptoKey.factory.js";
+import { assertBinaryEncoding } from "../cryptoEncoding/cryptoEncoding.core.js";
 import { factoryCreateToken, factoryCreateApiKey, factoryCreateSessionToken, factoryCreateRefreshToken, factoryCreateVerificationToken, factoryCreatePasswordResetToken, factoryCreateCsrfToken, factoryCreateOtp, } from "./cryptoFactory.token.js";
 import { factoryCreatePasswordHash, factoryVerifyPassword, } from "./cryptoFactory.password.js";
 import { factoryEncode, factoryDecode } from "./cryptoFactory.encoding.js";
 /**
  * Central factory for constructing and accessing crypto services.
+ *
+ * Options are deep-copied on construction, so later mutation of the
+ * caller's option objects cannot change the factory's behaviour.
  */
 export class CryptoFactory {
     options;
+    configuredProvider;
     service;
     constructor(options = {}) {
+        const encoding = options.encoding ?? "base64url";
+        assertBinaryEncoding(encoding);
+        this.configuredProvider = options.provider;
         this.options = Object.freeze({
-            ...options,
             defaultKeyAlgorithm: options.defaultKeyAlgorithm ?? CryptoAlgorithm.AES_256_GCM,
-            encoding: options.encoding ?? "base64url",
+            password: Object.freeze({ ...(options.password ?? {}) }),
+            encoding,
         });
-        this.service = createCryptoService();
+        this.service = createCryptoService({ provider: options.provider });
+    }
+    get provider() {
+        return this.configuredProvider ?? getDefaultCryptoProvider();
     }
     /** Returns the configured crypto service. */
     getService() {
         return this.service;
     }
-    /** Generates a key using the configured default algorithm. */
+    /**
+     * Returns the provider backing this factory (the process-wide default
+     * when none was configured).
+     */
+    getProvider() {
+        return this.provider;
+    }
+    /**
+     * Generates a symmetric key using the configured default algorithm.
+     *
+     * Asymmetric algorithms are rejected.
+     */
     async createKey(algorithm = this.options.defaultKeyAlgorithm) {
-        const length = algorithm.includes("256")
-            ? 32
-            : algorithm.includes("384")
-                ? 48
-                : algorithm.includes("512")
-                    ? 64
-                    : 32;
-        return generateCryptoKey(length, { algorithm, extractable: true });
+        return generateCryptoKey(defaultKeyLength(algorithm), { algorithm, extractable: true }, this.provider);
     }
     /** Generates a secure opaque token. */
     async createToken(bytes = 32, prefix) {
-        return factoryCreateToken(bytes, prefix, this.options
-            .encoding);
+        return factoryCreateToken(bytes, prefix, this.options.encoding, this.provider);
     }
     /** Generates an API key. */
     async createApiKey() {
-        return factoryCreateApiKey();
+        return factoryCreateApiKey(this.provider);
     }
     /** Generates a session token. */
     async createSessionToken() {
-        return factoryCreateSessionToken();
+        return factoryCreateSessionToken(this.provider);
     }
     /** Generates a refresh token. */
     async createRefreshToken() {
-        return factoryCreateRefreshToken();
+        return factoryCreateRefreshToken(this.provider);
     }
     /** Generates an email or account verification token. */
     async createVerificationToken() {
-        return factoryCreateVerificationToken();
+        return factoryCreateVerificationToken(this.provider);
     }
     /** Generates a password reset token. */
     async createPasswordResetToken() {
-        return factoryCreatePasswordResetToken();
+        return factoryCreatePasswordResetToken(this.provider);
     }
     /** Generates a CSRF token. */
     async createCsrfToken() {
-        return factoryCreateCsrfToken();
+        return factoryCreateCsrfToken(this.provider);
     }
     /** Generates a numeric one-time password. */
     async createOtp(digits = 6) {
-        return factoryCreateOtp(digits);
+        return factoryCreateOtp(digits, this.provider);
     }
-    /** Hashes a password using the configured password options. */
+    /**
+     * Hashes a password using the configured password options.
+     *
+     * Per-call options are layered on top of the configured defaults.
+     */
     async createPasswordHash(password, options) {
-        return factoryCreatePasswordHash(password, options ?? this.options.password);
+        return factoryCreatePasswordHash(password, { ...this.options.password, ...options }, this.provider);
     }
     /** Verifies a password against a stored hash. */
     async verifyPassword(password, encodedHash) {
-        return factoryVerifyPassword(password, encodedHash);
+        return factoryVerifyPassword(password, encodedHash, this.provider);
     }
     /** Encodes bytes using the configured default encoding. */
     encode(value, encoding = this.options.encoding) {
@@ -82,13 +101,12 @@ export class CryptoFactory {
     decode(value, encoding = this.options.encoding) {
         return factoryDecode(value, encoding);
     }
-    /** Returns the factory configuration. */
+    /** Returns a frozen copy of the factory configuration. */
     getOptions() {
         return Object.freeze({
-            ...this.options,
-            password: this.options.password
-                ? Object.freeze({ ...this.options.password })
-                : undefined,
+            defaultKeyAlgorithm: this.options.defaultKeyAlgorithm,
+            encoding: this.options.encoding,
+            password: Object.freeze({ ...this.options.password }),
         });
     }
 }
@@ -100,6 +118,14 @@ export function createCryptoFactory(options = {}) {
 }
 /**
  * Default application crypto factory.
+ *
+ * Construction is trivial (no provider is created until first use).
  */
 export const cryptoFactory = createCryptoFactory();
+/**
+ * Returns the default application crypto factory.
+ */
+export function getCryptoFactory() {
+    return cryptoFactory;
+}
 //# sourceMappingURL=cryptoFactory.core.js.map

package/dist/cryptoFactory/cryptoFactory.password.d.ts

@@ -1,5 +1,6 @@
-import type { PasswordHashOptions } from "../cryptoPassword/cryptoPassword.type.js";
+import type { CryptoProvider } from "../cryptoProvider/index.js";
+import type { PasswordHashOptions, PasswordHashResult } from "../cryptoPassword/cryptoPassword.type.js";
 export type { PasswordHashOptions };
-export declare function factoryCreatePasswordHash(password: string, options?: PasswordHashOptions): Promise<import("../cryptoPassword/cryptoPassword.type.js").PasswordHashResult>;
-export declare function factoryVerifyPassword(password: string, encodedHash: string): Promise<boolean>;
+export declare function factoryCreatePasswordHash(password: string, options?: PasswordHashOptions, provider?: CryptoProvider): Promise<PasswordHashResult>;
+export declare function factoryVerifyPassword(password: string, encodedHash: string, provider?: CryptoProvider): Promise<boolean>;
 //# sourceMappingURL=cryptoFactory.password.d.ts.map

package/dist/cryptoFactory/cryptoFactory.password.js

@@ -1,8 +1,8 @@
 import { hashPassword, verifyPassword, } from "../cryptoPassword/cryptoPassword.core.js";
-export async function factoryCreatePasswordHash(password, options) {
-    return hashPassword(password, options);
+export async function factoryCreatePasswordHash(password, options, provider) {
+    return hashPassword(password, { ...options, provider });
 }
-export async function factoryVerifyPassword(password, encodedHash) {
-    return verifyPassword(password, encodedHash);
+export async function factoryVerifyPassword(password, encodedHash, provider) {
+    return verifyPassword(password, encodedHash, provider);
 }
 //# sourceMappingURL=cryptoFactory.password.js.map

package/dist/cryptoFactory/cryptoFactory.token.d.ts

@@ -1,10 +1,11 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { TokenEncoding } from "../cryptoToken/cryptoToken.core.js";
-export declare function factoryCreateToken(bytes?: number, prefix?: string, encoding?: TokenEncoding): Promise<string>;
-export declare function factoryCreateApiKey(): Promise<string>;
-export declare function factoryCreateSessionToken(): Promise<string>;
-export declare function factoryCreateRefreshToken(): Promise<string>;
-export declare function factoryCreateVerificationToken(): Promise<string>;
-export declare function factoryCreatePasswordResetToken(): Promise<string>;
-export declare function factoryCreateCsrfToken(): Promise<string>;
-export declare function factoryCreateOtp(digits?: number): Promise<string>;
+export declare function factoryCreateToken(bytes?: number, prefix?: string, encoding?: TokenEncoding, provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateApiKey(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateSessionToken(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateRefreshToken(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateVerificationToken(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreatePasswordResetToken(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateCsrfToken(provider?: CryptoProvider): Promise<string>;
+export declare function factoryCreateOtp(digits?: number, provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoFactory.token.d.ts.map

package/dist/cryptoFactory/cryptoFactory.token.js

@@ -1,30 +1,31 @@
 import { generateToken, generateApiKey, generateSessionToken, generateRefreshToken, generateVerificationToken, generatePasswordResetToken, generateCsrfToken, generateOtp, } from "../cryptoToken/cryptoToken.core.js";
-export async function factoryCreateToken(bytes = 32, prefix, encoding = "base64url") {
+export async function factoryCreateToken(bytes = 32, prefix, encoding = "base64url", provider) {
     return generateToken({
         bytes,
         encoding,
         prefix,
+        provider,
     });
 }
-export async function factoryCreateApiKey() {
-    return generateApiKey();
+export async function factoryCreateApiKey(provider) {
+    return generateApiKey(undefined, undefined, provider);
 }
-export async function factoryCreateSessionToken() {
-    return generateSessionToken();
+export async function factoryCreateSessionToken(provider) {
+    return generateSessionToken(undefined, provider);
 }
-export async function factoryCreateRefreshToken() {
-    return generateRefreshToken();
+export async function factoryCreateRefreshToken(provider) {
+    return generateRefreshToken(undefined, provider);
 }
-export async function factoryCreateVerificationToken() {
-    return generateVerificationToken();
+export async function factoryCreateVerificationToken(provider) {
+    return generateVerificationToken(undefined, provider);
 }
-export async function factoryCreatePasswordResetToken() {
-    return generatePasswordResetToken();
+export async function factoryCreatePasswordResetToken(provider) {
+    return generatePasswordResetToken(undefined, provider);
 }
-export async function factoryCreateCsrfToken() {
-    return generateCsrfToken();
+export async function factoryCreateCsrfToken(provider) {
+    return generateCsrfToken(undefined, provider);
 }
-export async function factoryCreateOtp(digits = 6) {
-    return generateOtp(digits);
+export async function factoryCreateOtp(digits = 6, provider) {
+    return generateOtp(digits, provider);
 }
 //# sourceMappingURL=cryptoFactory.token.js.map

package/dist/cryptoHash/cryptoHash.codec.d.ts

@@ -5,6 +5,8 @@ import type { HashEncoding } from "./cryptoHash.core.js";
 export declare function encodeDigest(digest: Uint8Array, encoding: HashEncoding): string;
 /**
  * Decodes a hash string into bytes.
+ *
+ * Input must be a non-empty, canonical encoding.
  */
 export declare function decodeDigest(digest: string, encoding?: HashEncoding): Uint8Array;
 //# sourceMappingURL=cryptoHash.codec.d.ts.map

package/dist/cryptoHash/cryptoHash.codec.js

@@ -1,37 +1,37 @@
+import { toHex, fromHex } from "../cryptoEncoding/encoding/cryptoEncoding.hex.js";
+import { toBase64, fromBase64, } from "../cryptoEncoding/encoding/cryptoEncoding.base64.js";
+import { toBase64Url, fromBase64Url, } from "../cryptoEncoding/encoding/cryptoEncoding.base64url.js";
 /**
  * Converts a hash result into its encoded representation.
  */
 export function encodeDigest(digest, encoding) {
-    const buffer = Buffer.from(digest);
     switch (encoding) {
         case "hex":
-            return buffer.toString("hex");
+            return toHex(digest);
         case "base64":
-            return buffer.toString("base64");
+            return toBase64(digest);
         case "base64url":
-            return buffer.toString("base64url");
+            return toBase64Url(digest);
         default:
             throw new TypeError(`Unsupported hash encoding: ${String(encoding)}.`);
     }
 }
 /**
  * Decodes a hash string into bytes.
+ *
+ * Input must be a non-empty, canonical encoding.
  */
 export function decodeDigest(digest, encoding = "hex") {
     if (typeof digest !== "string" || digest.length === 0) {
         throw new TypeError("Digest must be a non-empty string.");
     }
     switch (encoding) {
-        case "hex": {
-            if (!/^[0-9a-fA-F]+$/.test(digest) || digest.length % 2 !== 0) {
-                throw new TypeError("Invalid hexadecimal digest.");
-            }
-            return new Uint8Array(Buffer.from(digest, "hex"));
-        }
+        case "hex":
+            return fromHex(digest);
         case "base64":
-            return new Uint8Array(Buffer.from(digest, "base64"));
+            return fromBase64(digest);
         case "base64url":
-            return new Uint8Array(Buffer.from(digest, "base64url"));
+            return fromBase64Url(digest);
         default:
             throw new TypeError(`Unsupported hash encoding: ${String(encoding)}.`);
     }

package/dist/cryptoHash/cryptoHash.compare.d.ts

@@ -1,5 +1,7 @@
 /**
- * Performs a constant-time comparison of two digest strings.
+ * Performs a constant-time comparison of two digests.
+ *
+ * Alias of `timingSafeEqual` kept for API compatibility.
  */
 export declare function equalDigests(left: Uint8Array, right: Uint8Array): boolean;
 //# sourceMappingURL=cryptoHash.compare.d.ts.map

package/dist/cryptoHash/cryptoHash.compare.js

@@ -1,14 +1,10 @@
+import { timingSafeEqual } from "../compare/compare.helper.js";
 /**
- * Performs a constant-time comparison of two digest strings.
+ * Performs a constant-time comparison of two digests.
+ *
+ * Alias of `timingSafeEqual` kept for API compatibility.
  */
 export function equalDigests(left, right) {
-    if (left.byteLength !== right.byteLength) {
-        return false;
-    }
-    let difference = 0;
-    for (let index = 0; index < left.byteLength; index += 1) {
-        difference |= left[index] ^ right[index];
-    }
-    return difference === 0;
+    return timingSafeEqual(left, right);
 }
 //# sourceMappingURL=cryptoHash.compare.js.map

package/dist/cryptoHash/cryptoHash.core.d.ts

@@ -1,19 +1,23 @@
-import type { HashAlgorithm } from "../cryptoProvider/index.js";
+import type { CryptoProvider, HashAlgorithm, CryptoInput } from "../cryptoProvider/index.js";
 import type { HashResult, HashEncoding } from "../cryptoProvider/types/cryptoHash.type.js";
 export type { HashResult, HashEncoding, } from "../cryptoProvider/types/cryptoHash.type.js";
 /**
  * Converts supported input data into bytes.
  */
-export type HashInput = string | Uint8Array | ArrayBuffer;
+export type HashInput = CryptoInput;
 /**
  * Options for hashing data.
  */
 export interface HashOptions {
     readonly algorithm?: HashAlgorithm;
     readonly encoding?: HashEncoding;
+    readonly provider?: CryptoProvider;
 }
 /**
  * Hashes arbitrary data using a cryptographic hash algorithm.
+ *
+ * Only the SHA-2 and SHA-3 family is accepted; weak digests such as md5
+ * or sha1 are rejected at runtime even when passed as plain strings.
  */
 export declare function hash(input: HashInput, options?: HashOptions): Promise<HashResult>;
 //# sourceMappingURL=cryptoHash.core.d.ts.map

package/dist/cryptoHash/cryptoHash.core.js

@@ -1,11 +1,18 @@
-import { createNodeCryptoProvider } from "../node/index.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { isHashAlgorithmName } from "../cryptoProvider/cryptoProvider.type.js";
 import { encodeDigest } from "./cryptoHash.codec.js";
-const provider = createNodeCryptoProvider();
 /**
  * Hashes arbitrary data using a cryptographic hash algorithm.
+ *
+ * Only the SHA-2 and SHA-3 family is accepted; weak digests such as md5
+ * or sha1 are rejected at runtime even when passed as plain strings.
  */
 export async function hash(input, options = {}) {
     const algorithm = options.algorithm ?? "sha256";
+    if (!isHashAlgorithmName(algorithm)) {
+        throw new TypeError(`Unsupported hash algorithm: ${String(algorithm)}.`);
+    }
+    const provider = options.provider ?? getDefaultCryptoProvider();
     const digest = await provider.hash(algorithm, input);
     const encoding = options.encoding ?? "hex";
     return Object.freeze({

package/dist/cryptoHash/cryptoHmac.core.d.ts

@@ -1,19 +1,22 @@
-import type { HmacAlgorithm, HashEncoding } from "../cryptoProvider/index.js";
+import type { CryptoProvider, HmacAlgorithm, HashEncoding } from "../cryptoProvider/index.js";
 import type { HashInput } from "./cryptoHash.core.js";
 /**
  * Calculates a keyed HMAC.
+ *
+ * The key must be at least `KEY_SIZE.MIN_HMAC_KEY_BYTES` (16) bytes so
+ * that a missing or empty secret cannot silently produce forgeable tags.
  */
-export declare function hmac(input: HashInput, key: Uint8Array, algorithm?: HmacAlgorithm, encoding?: HashEncoding): Promise<string>;
+export declare function hmac(input: HashInput, key: Uint8Array, algorithm?: HmacAlgorithm, encoding?: HashEncoding, provider?: CryptoProvider): Promise<string>;
 /**
  * Calculates a SHA-256 HMAC.
  */
-export declare function hmacSha256(input: HashInput, key: Uint8Array, encoding?: HashEncoding): Promise<string>;
+export declare function hmacSha256(input: HashInput, key: Uint8Array, encoding?: HashEncoding, provider?: CryptoProvider): Promise<string>;
 /**
  * Calculates a SHA-384 HMAC.
  */
-export declare function hmacSha384(input: HashInput, key: Uint8Array, encoding?: HashEncoding): Promise<string>;
+export declare function hmacSha384(input: HashInput, key: Uint8Array, encoding?: HashEncoding, provider?: CryptoProvider): Promise<string>;
 /**
  * Calculates a SHA-512 HMAC.
  */
-export declare function hmacSha512(input: HashInput, key: Uint8Array, encoding?: HashEncoding): Promise<string>;
+export declare function hmacSha512(input: HashInput, key: Uint8Array, encoding?: HashEncoding, provider?: CryptoProvider): Promise<string>;
 //# sourceMappingURL=cryptoHmac.core.d.ts.map

package/dist/cryptoHash/cryptoHmac.core.js

@@ -1,29 +1,42 @@
-import { createNodeCryptoProvider } from "../node/index.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { isHmacAlgorithmName } from "../cryptoProvider/cryptoProvider.type.js";
+import { KEY_SIZE } from "../cryptoConstants/cryptoConstants.type.js";
 import { encodeDigest } from "./cryptoHash.codec.js";
-const provider = createNodeCryptoProvider();
 /**
  * Calculates a keyed HMAC.
+ *
+ * The key must be at least `KEY_SIZE.MIN_HMAC_KEY_BYTES` (16) bytes so
+ * that a missing or empty secret cannot silently produce forgeable tags.
  */
-export async function hmac(input, key, algorithm = "sha256", encoding = "hex") {
+export async function hmac(input, key, algorithm = "sha256", encoding = "hex", provider = getDefaultCryptoProvider()) {
+    if (!isHmacAlgorithmName(algorithm)) {
+        throw new TypeError(`Unsupported HMAC algorithm: ${String(algorithm)}.`);
+    }
+    if (!(key instanceof Uint8Array)) {
+        throw new TypeError("HMAC key must be a Uint8Array.");
+    }
+    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.`);
+    }
     const digest = await provider.hmac(algorithm, key, input);
     return encodeDigest(digest, encoding);
 }
 /**
  * Calculates a SHA-256 HMAC.
  */
-export async function hmacSha256(input, key, encoding = "hex") {
-    return hmac(input, key, "sha256", encoding);
+export async function hmacSha256(input, key, encoding = "hex", provider) {
+    return hmac(input, key, "sha256", encoding, provider);
 }
 /**
  * Calculates a SHA-384 HMAC.
  */
-export async function hmacSha384(input, key, encoding = "hex") {
-    return hmac(input, key, "sha384", encoding);
+export async function hmacSha384(input, key, encoding = "hex", provider) {
+    return hmac(input, key, "sha384", encoding, provider);
 }
 /**
  * Calculates a SHA-512 HMAC.
  */
-export async function hmacSha512(input, key, encoding = "hex") {
-    return hmac(input, key, "sha512", encoding);
+export async function hmacSha512(input, key, encoding = "hex", provider) {
+    return hmac(input, key, "sha512", encoding, provider);
 }
 //# sourceMappingURL=cryptoHmac.core.js.map

package/dist/cryptoKey/cryptoKey.factory.d.ts

@@ -1,17 +1,44 @@
 import type { CryptoProvider } from "../cryptoProvider/index.js";
+import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import type { CryptoKey, CryptoKeyOptions } from "./cryptoKey.type.js";
+/**
+ * Domain-separation label used for key fingerprints.
+ *
+ * Fingerprints are `HMAC-SHA256(label, keyBytes)` rather than a bare hash
+ * of the key so that they cannot be confused with any other digest of the
+ * same bytes. They are only safe to expose for keys with at least 128 bits
+ * of entropy, which `createCryptoKey` enforces by length; a fingerprint of
+ * a low-entropy key is still an offline brute-force oracle.
+ */
+export declare const CRYPTO_KEY_FINGERPRINT_LABEL = "zudojs-crypto-key-fingerprint-v1";
+/**
+ * Returns the required key length (in bytes) for an algorithm, or a
+ * minimum when any length above it is acceptable.
+ */
+export declare function expectedKeyLength(algorithm: CryptoAlgorithm): {
+    readonly exact?: number;
+    readonly minimum: number;
+};
 /**
  * Creates a cryptographic key from raw bytes.
  *
+ * The key length is validated against the declared algorithm (exactly 32
+ * bytes for AES-256-GCM, at least 16 bytes for HMAC and derived keys).
  * Hashing and key-id generation are delegated to the supplied provider.
  */
 export declare function createCryptoKey(bytes: Uint8Array, options: CryptoKeyOptions, provider?: CryptoProvider): Promise<CryptoKey>;
 /**
- * Generates a cryptographically secure random key.
+ * Generates a cryptographically secure random symmetric key.
  *
- * Randomness is delegated to the supplied provider.
+ * Only symmetric algorithms (AES-GCM, HMAC, KDF outputs) are accepted:
+ * random bytes are not a usable Ed25519 key, so asymmetric algorithms are
+ * rejected. Use `generateEd25519KeyPair` for signing keys.
  */
 export declare function generateCryptoKey(length: number, options: CryptoKeyOptions, provider?: CryptoProvider): Promise<CryptoKey>;
+/**
+ * Returns the default key length in bytes for a symmetric algorithm.
+ */
+export declare function defaultKeyLength(algorithm: CryptoAlgorithm): number;
 /**
  * Returns a defensive copy of a key's bytes.
  *