@zudojs/crypto 0.1.0 → 1.1.0

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

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