@zudojs/crypto 0.0.1 → 1.0.0

package/dist/cryptoPassword/cryptoPassword.core.d.ts

@@ -1,10 +1,24 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { PasswordHashOptions, PasswordHashResult } from "./cryptoPassword.type.js";
 /**
- * Hashes a password using the configured algorithm.
+ * Options for `hashPassword` including an optional provider override.
  */
-export declare function hashPassword(password: string, options?: PasswordHashOptions): Promise<PasswordHashResult>;
+export interface HashPasswordOptions extends PasswordHashOptions {
+    readonly provider?: CryptoProvider;
+}
+/**
+ * Hashes a password using scrypt.
+ *
+ * `saltBytes` and `keyBytes` are honoured, and the returned `salt`/`hash`
+ * are exactly the values inside `encoded`.
+ */
+export declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<PasswordHashResult>;
 /**
  * Verifies a password against an encoded password hash.
+ *
+ * Returns false (never throws) for wrong passwords and for malformed,
+ * foreign or out-of-bounds hash strings. A non-string or over-long
+ * password also yields false.
  */
-export declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+export declare function verifyPassword(password: string, encoded: string, provider?: CryptoProvider): Promise<boolean>;
 //# sourceMappingURL=cryptoPassword.core.d.ts.map

package/dist/cryptoPassword/cryptoPassword.core.js

@@ -1,23 +1,22 @@
-import { createNodeCryptoProvider } from "../node/index.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
+import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { assertPassword, validateParameters, } from "./cryptoPassword.validate.js";
 import { decodePasswordHash, PASSWORD_FORMAT_VERSION, } from "./cryptoPassword.codec.js";
-const provider = createNodeCryptoProvider();
 /**
- * Hashes a password using the configured algorithm.
+ * Hashes a password using scrypt.
+ *
+ * `saltBytes` and `keyBytes` are honoured, and the returned `salt`/`hash`
+ * are exactly the values inside `encoded`.
  */
 export async function hashPassword(password, options = {}) {
     assertPassword(password);
-    const algorithm = options.cost !== undefined ||
-        options.blockSize !== undefined ||
-        options.parallelization !== undefined
-        ? "scrypt"
-        : "scrypt";
-    const saltBytes = options.saltBytes ?? 16;
-    const keyBytes = options.keyBytes ?? 32;
-    const cost = options.cost ?? 16_384;
-    const blockSize = options.blockSize ?? 8;
-    const parallelization = options.parallelization ?? 1;
+    const provider = options.provider ?? getDefaultCryptoProvider();
+    const saltBytes = options.saltBytes ?? PASSWORD_HASH.SALT_BYTES;
+    const keyBytes = options.keyBytes ?? PASSWORD_HASH.KEY_BYTES;
+    const cost = options.cost ?? PASSWORD_HASH.SCRYPT.COST;
+    const blockSize = options.blockSize ?? PASSWORD_HASH.SCRYPT.BLOCK_SIZE;
+    const parallelization = options.parallelization ?? PASSWORD_HASH.SCRYPT.PARALLELIZATION;
     validateParameters({
         saltBytes,
         keyBytes,
@@ -31,26 +30,35 @@ export async function hashPassword(password, options = {}) {
         memoryCost: cost,
         blockSize,
         parallelism: parallelization,
+        keyBytes,
+        salt,
     });
-    const hash = decodePasswordHash(encoded).hash;
+    const decoded = decodePasswordHash(encoded);
+    if (decoded.algorithm !== CryptoAlgorithm.SCRYPT) {
+        throw new TypeError("Provider returned a non-scrypt password hash.");
+    }
     return Object.freeze({
         algorithm: CryptoAlgorithm.SCRYPT,
         version: PASSWORD_FORMAT_VERSION,
-        salt,
-        hash,
+        salt: decoded.salt,
+        hash: decoded.hash,
         encoded,
-        cost,
-        blockSize,
-        parallelization,
+        cost: decoded.cost,
+        blockSize: decoded.blockSize,
+        parallelization: decoded.parallelization,
     });
 }
 /**
  * Verifies a password against an encoded password hash.
+ *
+ * Returns false (never throws) for wrong passwords and for malformed,
+ * foreign or out-of-bounds hash strings. A non-string or over-long
+ * password also yields false.
  */
-export async function verifyPassword(password, encoded) {
+export async function verifyPassword(password, encoded, provider = getDefaultCryptoProvider()) {
     try {
         assertPassword(password);
-        return provider.verifyPassword(password, encoded);
+        return await provider.verifyPassword(password, encoded);
     }
     catch {
         return false;

package/dist/cryptoPassword/cryptoPassword.helper.js

@@ -1,3 +1,4 @@
+import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { decodePasswordHash } from "./cryptoPassword.codec.js";
 const PASSWORD_MINIMUM_DEFAULT_LENGTH = 8;
 /**
@@ -5,11 +6,11 @@ const PASSWORD_MINIMUM_DEFAULT_LENGTH = 8;
  */
 export function getDefaultPasswordHashOptions() {
     return {
-        saltBytes: 16,
-        keyBytes: 32,
-        cost: 16_384,
-        blockSize: 8,
-        parallelization: 1,
+        saltBytes: PASSWORD_HASH.SALT_BYTES,
+        keyBytes: PASSWORD_HASH.KEY_BYTES,
+        cost: PASSWORD_HASH.SCRYPT.COST,
+        blockSize: PASSWORD_HASH.SCRYPT.BLOCK_SIZE,
+        parallelization: PASSWORD_HASH.SCRYPT.PARALLELIZATION,
     };
 }
 /**

package/dist/cryptoPassword/cryptoPassword.type.d.ts

@@ -1,6 +1,7 @@
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
+import type { Pbkdf2Digest } from "../cryptoProvider/cryptoProvider.type.js";
 /**
- * Options used for password hashing.
+ * Options used for password hashing (scrypt).
  */
 export interface PasswordHashOptions {
     readonly saltBytes?: number;
@@ -11,9 +12,13 @@ export interface PasswordHashOptions {
 }
 /**
  * Result returned by password hashing.
+ *
+ * `salt` and `hash` are exactly the values encoded in `encoded`, so a
+ * record that stores them in separate columns can be re-encoded with
+ * `encodePasswordHash` and verified.
  */
 export interface PasswordHashResult {
-    readonly algorithm: CryptoAlgorithm;
+    readonly algorithm: CryptoAlgorithm.SCRYPT;
     readonly version: string;
     readonly salt: Uint8Array;
     readonly hash: Uint8Array;
@@ -23,15 +28,38 @@ export interface PasswordHashResult {
     readonly parallelization: number;
 }
 /**
- * Parameters encoded into a password hash.
+ * Parameters encoded into a scrypt password hash
+ * (`v1$scrypt$N$r$p$salt.hash`).
  */
-export interface PasswordHashParameters {
+export interface ScryptPasswordHashParameters {
     readonly version: string;
-    readonly algorithm: CryptoAlgorithm;
+    readonly algorithm: CryptoAlgorithm.SCRYPT;
     readonly salt: Uint8Array;
     readonly hash: Uint8Array;
     readonly cost: number;
     readonly blockSize: number;
     readonly parallelization: number;
 }
+/**
+ * Algorithm labels used for PBKDF2 password hashes.
+ */
+export type Pbkdf2PasswordAlgorithm = CryptoAlgorithm.PBKDF2_SHA256 | CryptoAlgorithm.PBKDF2_SHA384 | CryptoAlgorithm.PBKDF2_SHA512;
+/**
+ * Parameters encoded into a PBKDF2 password hash
+ * (`v1$pbkdf2-<digest>$iterations$salt.hash`).
+ */
+export interface Pbkdf2PasswordHashParameters {
+    readonly version: string;
+    readonly algorithm: Pbkdf2PasswordAlgorithm;
+    readonly digest: Pbkdf2Digest;
+    readonly salt: Uint8Array;
+    readonly hash: Uint8Array;
+    readonly iterations: number;
+}
+/**
+ * Parameters decoded from any supported password hash string.
+ *
+ * Discriminate on `algorithm` to access algorithm-specific fields.
+ */
+export type PasswordHashParameters = ScryptPasswordHashParameters | Pbkdf2PasswordHashParameters;
 //# sourceMappingURL=cryptoPassword.type.d.ts.map

package/dist/cryptoPassword/cryptoPassword.validate.d.ts

@@ -1,5 +1,7 @@
 /**
- * Validates the structural constraints of password hashing parameters.
+ * Validates the structural constraints of scrypt password hashing
+ * parameters, including upper bounds so that parameters read back from a
+ * stored hash cannot force unbounded CPU or memory usage.
  */
 export declare function validateParameters(parameters: {
     readonly saltBytes: number;
@@ -8,16 +10,25 @@ export declare function validateParameters(parameters: {
     readonly blockSize: number;
     readonly parallelization: number;
 }): void;
+/**
+ * Validates PBKDF2 password hashing parameters, including upper bounds.
+ */
+export declare function validatePbkdf2Parameters(parameters: {
+    readonly saltBytes: number;
+    readonly keyBytes: number;
+    readonly iterations: number;
+}): void;
 /**
  * Parses a string into a positive safe integer.
  */
 export declare function parsePositiveInteger(value: string, name: string): number;
 /**
- * Decodes a Base64URL string into bytes.
+ * Decodes a non-empty, canonical Base64URL string into bytes.
  */
 export declare function decodeBase64Url(value: string): Uint8Array;
 /**
- * Asserts that a value is a non-empty password string.
+ * Asserts that a value is a password string within the policy length
+ * bounds (non-empty, at most `PASSWORD_POLICY.MAX_LENGTH` code units).
  */
 export declare function assertPassword(password: string): void;
 //# sourceMappingURL=cryptoPassword.validate.d.ts.map

package/dist/cryptoPassword/cryptoPassword.validate.js

@@ -1,24 +1,54 @@
+import { PASSWORD_HASH, PASSWORD_POLICY, } from "../cryptoConstants/cryptoConstants.security.js";
+import { fromBase64Url } from "../cryptoEncoding/encoding/cryptoEncoding.base64url.js";
+const LIMITS = PASSWORD_HASH.LIMITS;
 /**
- * Validates the structural constraints of password hashing parameters.
+ * Validates the structural constraints of scrypt password hashing
+ * parameters, including upper bounds so that parameters read back from a
+ * stored hash cannot force unbounded CPU or memory usage.
  */
 export function validateParameters(parameters) {
-    if (!Number.isInteger(parameters.saltBytes) || parameters.saltBytes < 16) {
-        throw new RangeError("saltBytes must be an integer of at least 16.");
-    }
-    if (!Number.isInteger(parameters.keyBytes) || parameters.keyBytes < 16) {
-        throw new RangeError("keyBytes must be an integer of at least 16.");
-    }
+    validateSaltAndKeyBytes(parameters.saltBytes, parameters.keyBytes);
     if (!Number.isInteger(parameters.cost) ||
-        parameters.cost < 2 ||
+        parameters.cost < LIMITS.MIN_SCRYPT_COST ||
+        parameters.cost > LIMITS.MAX_SCRYPT_COST ||
         (parameters.cost & (parameters.cost - 1)) !== 0) {
-        throw new RangeError("cost must be a power of two greater than or equal to 2.");
+        throw new RangeError(`cost must be a power of two between ${LIMITS.MIN_SCRYPT_COST} and ${LIMITS.MAX_SCRYPT_COST}.`);
     }
-    if (!Number.isInteger(parameters.blockSize) || parameters.blockSize <= 0) {
-        throw new RangeError("blockSize must be a positive integer.");
+    if (!Number.isInteger(parameters.blockSize) ||
+        parameters.blockSize <= 0 ||
+        parameters.blockSize > LIMITS.MAX_SCRYPT_BLOCK_SIZE) {
+        throw new RangeError(`blockSize must be an integer between 1 and ${LIMITS.MAX_SCRYPT_BLOCK_SIZE}.`);
     }
     if (!Number.isInteger(parameters.parallelization) ||
-        parameters.parallelization <= 0) {
-        throw new RangeError("parallelization must be a positive integer.");
+        parameters.parallelization <= 0 ||
+        parameters.parallelization > LIMITS.MAX_SCRYPT_PARALLELIZATION) {
+        throw new RangeError(`parallelization must be an integer between 1 and ${LIMITS.MAX_SCRYPT_PARALLELIZATION}.`);
+    }
+    if (128 * parameters.cost * parameters.blockSize > LIMITS.MAX_SCRYPT_MEMORY_BYTES) {
+        throw new RangeError(`cost * blockSize exceeds the scrypt memory bound of ${LIMITS.MAX_SCRYPT_MEMORY_BYTES} bytes.`);
+    }
+}
+/**
+ * Validates PBKDF2 password hashing parameters, including upper bounds.
+ */
+export function validatePbkdf2Parameters(parameters) {
+    validateSaltAndKeyBytes(parameters.saltBytes, parameters.keyBytes);
+    if (!Number.isInteger(parameters.iterations) ||
+        parameters.iterations < PASSWORD_HASH.PBKDF2.MIN_ITERATIONS ||
+        parameters.iterations > LIMITS.MAX_PBKDF2_ITERATIONS) {
+        throw new RangeError(`iterations must be an integer between ${PASSWORD_HASH.PBKDF2.MIN_ITERATIONS} and ${LIMITS.MAX_PBKDF2_ITERATIONS}.`);
+    }
+}
+function validateSaltAndKeyBytes(saltBytes, keyBytes) {
+    if (!Number.isInteger(saltBytes) ||
+        saltBytes < LIMITS.MIN_SALT_BYTES ||
+        saltBytes > LIMITS.MAX_SALT_BYTES) {
+        throw new RangeError(`saltBytes must be an integer between ${LIMITS.MIN_SALT_BYTES} and ${LIMITS.MAX_SALT_BYTES}.`);
+    }
+    if (!Number.isInteger(keyBytes) ||
+        keyBytes < LIMITS.MIN_KEY_BYTES ||
+        keyBytes > LIMITS.MAX_KEY_BYTES) {
+        throw new RangeError(`keyBytes must be an integer between ${LIMITS.MIN_KEY_BYTES} and ${LIMITS.MAX_KEY_BYTES}.`);
     }
 }
 /**
@@ -35,19 +65,17 @@ export function parsePositiveInteger(value, name) {
     return parsed;
 }
 /**
- * Decodes a Base64URL string into bytes.
+ * Decodes a non-empty, canonical Base64URL string into bytes.
  */
 export function decodeBase64Url(value) {
-    if (value.length === 0 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    if (typeof value !== "string" || value.length === 0) {
         throw new TypeError("Invalid Base64URL value.");
     }
-    if (value.length % 4 === 1) {
-        throw new TypeError("Invalid Base64URL length.");
-    }
-    return new Uint8Array(Buffer.from(value, "base64url"));
+    return fromBase64Url(value);
 }
 /**
- * Asserts that a value is a non-empty password string.
+ * Asserts that a value is a password string within the policy length
+ * bounds (non-empty, at most `PASSWORD_POLICY.MAX_LENGTH` code units).
  */
 export function assertPassword(password) {
     if (typeof password !== "string") {
@@ -56,5 +84,8 @@ export function assertPassword(password) {
     if (password.length === 0) {
         throw new TypeError("Password cannot be empty.");
     }
+    if (password.length > PASSWORD_POLICY.MAX_LENGTH) {
+        throw new RangeError(`Password must not exceed ${PASSWORD_POLICY.MAX_LENGTH} characters.`);
+    }
 }
 //# sourceMappingURL=cryptoPassword.validate.js.map

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

@@ -0,0 +1,18 @@
+import type { CryptoProvider } from "./cryptoProvider.core.js";
+/**
+ * Returns the process-wide default crypto provider, creating the Node
+ * provider lazily on first use.
+ */
+export declare function getDefaultCryptoProvider(): CryptoProvider;
+/**
+ * Replaces the process-wide default crypto provider.
+ *
+ * Every module-level helper (hash, encrypt, hashPassword, generateToken,
+ * ...) that is not given an explicit provider uses this one.
+ */
+export declare function setDefaultCryptoProvider(provider: CryptoProvider): void;
+/**
+ * Restores the built-in Node provider as the default.
+ */
+export declare function resetDefaultCryptoProvider(): void;
+//# sourceMappingURL=cryptoProvider.default.d.ts.map

package/dist/cryptoProvider/cryptoProvider.default.js

@@ -0,0 +1,31 @@
+import { createNodeCryptoProvider } from "../node/nodeCryptoProvider/nodeCryptoProvider.factory.js";
+let defaultProvider;
+/**
+ * Returns the process-wide default crypto provider, creating the Node
+ * provider lazily on first use.
+ */
+export function getDefaultCryptoProvider() {
+    if (defaultProvider === undefined) {
+        defaultProvider = createNodeCryptoProvider();
+    }
+    return defaultProvider;
+}
+/**
+ * Replaces the process-wide default crypto provider.
+ *
+ * Every module-level helper (hash, encrypt, hashPassword, generateToken,
+ * ...) that is not given an explicit provider uses this one.
+ */
+export function setDefaultCryptoProvider(provider) {
+    if (typeof provider !== "object" || provider === null) {
+        throw new TypeError("Crypto provider must be an object.");
+    }
+    defaultProvider = provider;
+}
+/**
+ * Restores the built-in Node provider as the default.
+ */
+export function resetDefaultCryptoProvider() {
+    defaultProvider = undefined;
+}
+//# sourceMappingURL=cryptoProvider.default.js.map

package/dist/cryptoProvider/cryptoProvider.interface.d.ts

@@ -1,6 +1,7 @@
-import type { HashAlgorithm, HmacAlgorithm, SignatureAlgorithm, KeyDerivationAlgorithm, CryptoInput, CryptoCapabilities } from "./cryptoProvider.type.js";
-import type { EncryptedData } from "./types/cryptoCipher.type.js";
-import type { DeriveKeyOptions } from "./types/cryptoKeyDerivation.type.js";
+import type { HashAlgorithm, HmacAlgorithm, CryptoInput, CryptoCapabilities } from "./cryptoProvider.type.js";
+import type { EncryptedData, EncryptOptions, DecryptOptions } from "./types/cryptoCipher.type.js";
+import type { SignOptions, VerifyOptions } from "./types/cryptoSignature.type.js";
+import type { DeriveKeyOptions, PasswordHashProviderOptions } from "./types/cryptoKeyDerivation.type.js";
 /**
  * Provider for cryptographically secure random bytes.
  */
@@ -33,17 +34,8 @@ export interface HmacProvider {
 export interface EncryptionProvider {
     readonly name: string;
     readonly capabilities: CryptoCapabilities;
-    encrypt(options: {
-        key: CryptoInput;
-        plaintext: CryptoInput;
-        associatedData?: CryptoInput;
-        nonce?: Uint8Array;
-    }): Promise<EncryptedData>;
-    decrypt(options: {
-        key: CryptoInput;
-        encrypted: EncryptedData;
-        associatedData?: CryptoInput;
-    }): Promise<Uint8Array>;
+    encrypt(options: EncryptOptions): Promise<EncryptedData>;
+    decrypt(options: DecryptOptions): Promise<Uint8Array>;
 }
 /**
  * Provider for digital signing.
@@ -51,17 +43,8 @@ export interface EncryptionProvider {
 export interface SigningProvider {
     readonly name: string;
     readonly capabilities: CryptoCapabilities;
-    sign(options: {
-        key: CryptoInput;
-        data: CryptoInput;
-        algorithm?: SignatureAlgorithm;
-    }): Promise<Uint8Array>;
-    verify(options: {
-        key: CryptoInput;
-        data: CryptoInput;
-        signature: Uint8Array;
-        algorithm?: SignatureAlgorithm;
-    }): Promise<boolean>;
+    sign(options: SignOptions): Promise<Uint8Array>;
+    verify(options: VerifyOptions): Promise<boolean>;
 }
 /**
  * Provider for key derivation.
@@ -77,15 +60,7 @@ export interface KeyDerivationProvider {
 export interface PasswordProvider {
     readonly name: string;
     readonly capabilities: CryptoCapabilities;
-    hashPassword(password: CryptoInput, options?: {
-        algorithm?: KeyDerivationAlgorithm;
-        memoryCost?: number;
-        timeCost?: number;
-        blockSize?: number;
-        parallelism?: number;
-        keyBytes?: number;
-        salt?: Uint8Array;
-    }): Promise<string>;
+    hashPassword(password: CryptoInput, options?: PasswordHashProviderOptions): Promise<string>;
     verifyPassword(password: CryptoInput, hash: string): Promise<boolean>;
 }
 //# sourceMappingURL=cryptoProvider.interface.d.ts.map

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

@@ -6,24 +6,33 @@ export type HashAlgorithm = "sha256" | "sha384" | "sha512" | "sha3-256" | "sha3-
  * Supported HMAC algorithm identifiers.
  */
 export type HmacAlgorithm = "sha256" | "sha384" | "sha512";
+/**
+ * Supported PBKDF2 digest identifiers.
+ */
+export type Pbkdf2Digest = "sha256" | "sha384" | "sha512";
 /**
  * Supported encryption algorithm identifiers.
+ *
+ * Only AES-256-GCM is implemented.
  */
-export type EncryptionAlgorithm = "aes-256-gcm" | "chacha20-poly1305";
+export type EncryptionAlgorithm = "aes-256-gcm";
 /**
  * Supported signature algorithm identifiers.
  */
 export type SignatureAlgorithm = "ed25519" | "rsa-sha256" | "rsa-sha384" | "rsa-sha512" | "ecdsa-sha256" | "ecdsa-sha384" | "ecdsa-sha512";
 /**
- * Supported key derivation algorithm identifiers.
+ * Supported key derivation algorithm identifiers at the provider level.
  */
-export type KeyDerivationAlgorithm = "pbkdf2" | "scrypt" | "argon2id";
+export type KeyDerivationAlgorithm = "pbkdf2" | "scrypt";
 /**
  * Supported encoding formats.
  */
 export type EncodingFormat = "hex" | "base64" | "base64url" | "utf8";
 /**
  * Normalized cryptographic input.
+ *
+ * For keys, a `string` is interpreted as PEM text and a `Uint8Array` as
+ * either PEM text (when it starts with `-----BEGIN`) or DER bytes.
  */
 export type CryptoInput = string | Uint8Array | ArrayBuffer;
 /**
@@ -38,4 +47,24 @@ export interface CryptoCapabilities {
     readonly passwordHashing: boolean;
     readonly keyDerivation: boolean;
 }
+export declare const HASH_ALGORITHM_NAMES: ReadonlySet<string>;
+export declare const HMAC_ALGORITHM_NAMES: ReadonlySet<string>;
+export declare const PBKDF2_DIGEST_NAMES: ReadonlySet<string>;
+export declare const SIGNATURE_ALGORITHM_NAMES: ReadonlySet<string>;
+/**
+ * Returns whether a value names a supported hash algorithm.
+ */
+export declare function isHashAlgorithmName(value: unknown): value is HashAlgorithm;
+/**
+ * Returns whether a value names a supported HMAC algorithm.
+ */
+export declare function isHmacAlgorithmName(value: unknown): value is HmacAlgorithm;
+/**
+ * Returns whether a value names a supported PBKDF2 digest.
+ */
+export declare function isPbkdf2Digest(value: unknown): value is Pbkdf2Digest;
+/**
+ * Returns whether a value names a supported signature algorithm.
+ */
+export declare function isSignatureAlgorithmName(value: unknown): value is SignatureAlgorithm;
 //# sourceMappingURL=cryptoProvider.type.d.ts.map

package/dist/cryptoProvider/cryptoProvider.type.js

@@ -1,2 +1,41 @@
-export {};
+export const HASH_ALGORITHM_NAMES = new Set(["sha256", "sha384", "sha512", "sha3-256", "sha3-384", "sha3-512"]);
+export const HMAC_ALGORITHM_NAMES = new Set(["sha256", "sha384", "sha512"]);
+export const PBKDF2_DIGEST_NAMES = new Set([
+    "sha256",
+    "sha384",
+    "sha512",
+]);
+export const SIGNATURE_ALGORITHM_NAMES = new Set([
+    "ed25519",
+    "rsa-sha256",
+    "rsa-sha384",
+    "rsa-sha512",
+    "ecdsa-sha256",
+    "ecdsa-sha384",
+    "ecdsa-sha512",
+]);
+/**
+ * Returns whether a value names a supported hash algorithm.
+ */
+export function isHashAlgorithmName(value) {
+    return typeof value === "string" && HASH_ALGORITHM_NAMES.has(value);
+}
+/**
+ * Returns whether a value names a supported HMAC algorithm.
+ */
+export function isHmacAlgorithmName(value) {
+    return typeof value === "string" && HMAC_ALGORITHM_NAMES.has(value);
+}
+/**
+ * Returns whether a value names a supported PBKDF2 digest.
+ */
+export function isPbkdf2Digest(value) {
+    return typeof value === "string" && PBKDF2_DIGEST_NAMES.has(value);
+}
+/**
+ * Returns whether a value names a supported signature algorithm.
+ */
+export function isSignatureAlgorithmName(value) {
+    return typeof value === "string" && SIGNATURE_ALGORITHM_NAMES.has(value);
+}
 //# sourceMappingURL=cryptoProvider.type.js.map

package/dist/cryptoProvider/index.d.ts

@@ -3,10 +3,13 @@
  *
  * Provides capability-based provider interfaces for all
  * cryptographic operations, enabling testability and
- * runtime provider selection.
+ * runtime provider selection via `setDefaultCryptoProvider`
+ * or per-call `provider` options.
  */
 export type { CryptoProvider } from "./cryptoProvider.core.js";
-export type { CryptoCapabilities, HashAlgorithm, HmacAlgorithm, EncryptionAlgorithm, SignatureAlgorithm, KeyDerivationAlgorithm, EncodingFormat, CryptoInput, } from "./cryptoProvider.type.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 * from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cryptoProvider/index.js

@@ -1,2 +1,4 @@
+export { isHashAlgorithmName, isHmacAlgorithmName, isPbkdf2Digest, isSignatureAlgorithmName, } from "./cryptoProvider.type.js";
+export { getDefaultCryptoProvider, setDefaultCryptoProvider, resetDefaultCryptoProvider, } from "./cryptoProvider.default.js";
 export * from "./types/index.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,4 +1,4 @@
-import type { EncryptionAlgorithm } from "../cryptoProvider.type.js";
+import type { CryptoInput, EncryptionAlgorithm } from "../cryptoProvider.type.js";
 /**
  * Result of an encryption operation.
  */
@@ -10,19 +10,24 @@ export interface EncryptedData {
 }
 /**
  * Options for encryption.
+ *
+ * When `nonce` is supplied it must be exactly 12 bytes and MUST be unique
+ * per key: reusing a nonce under the same key with AES-GCM leaks the XOR
+ * of the plaintexts and allows authentication-key recovery. Omit it to
+ * have the provider draw a fresh random nonce.
  */
 export interface EncryptOptions {
-    readonly key: Uint8Array;
-    readonly plaintext: Uint8Array;
-    readonly associatedData?: Uint8Array;
+    readonly key: CryptoInput;
+    readonly plaintext: CryptoInput;
+    readonly associatedData?: CryptoInput;
     readonly nonce?: Uint8Array;
 }
 /**
  * Options for decryption.
  */
 export interface DecryptOptions {
-    readonly key: Uint8Array;
+    readonly key: CryptoInput;
     readonly encrypted: EncryptedData;
-    readonly associatedData?: Uint8Array;
+    readonly associatedData?: CryptoInput;
 }
 //# sourceMappingURL=cryptoCipher.type.d.ts.map