@zudojs/crypto 0.1.0 → 1.1.0

package/dist/cryptoKey/cryptoKey.factory.js

@@ -1,29 +1,66 @@
-import { createNodeCryptoProvider } from "../node/index.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 import { encode } from "../cryptoEncoding/cryptoEncoding.core.js";
-let defaultProvider;
+import { CryptoOperation } from "@zudojs/errors";
+import { keyError } from "../cryptoErrors/cryptoErrors.helper.js";
+import { CryptoAlgorithm, AES_GCM, KEY_SIZE, } from "../cryptoConstants/cryptoConstants.type.js";
+import { isAeadAlgorithm, isHashAlgorithm, isKeyDerivationAlgorithm, isMacAlgorithm, isSymmetricKeyAlgorithm, } from "../cryptoConstants/cryptoConstants.guard.js";
 /**
- * Returns a lazily created default crypto provider.
+ * Domain-separation label used for key fingerprints.
  *
- * The provider abstraction keeps the key module free of direct
- * `node:crypto` usage while still allowing callers to inject their own.
+ * 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.
  */
-function getDefaultProvider() {
-    if (defaultProvider === undefined) {
-        defaultProvider = createNodeCryptoProvider();
+export const CRYPTO_KEY_FINGERPRINT_LABEL = "zudojs-crypto-key-fingerprint-v1";
+const MIN_SYMMETRIC_KEY_BYTES = KEY_SIZE.MIN_SYMMETRIC_KEY_BITS / 8;
+/**
+ * Returns the required key length (in bytes) for an algorithm, or a
+ * minimum when any length above it is acceptable.
+ */
+export function expectedKeyLength(algorithm) {
+    if (isAeadAlgorithm(algorithm)) {
+        return { exact: AES_GCM.KEY_BYTES, minimum: AES_GCM.KEY_BYTES };
+    }
+    if (isMacAlgorithm(algorithm) || isKeyDerivationAlgorithm(algorithm)) {
+        return { minimum: MIN_SYMMETRIC_KEY_BYTES };
+    }
+    if (algorithm === CryptoAlgorithm.ED25519) {
+        // Raw 32-byte seed or a DER/PEM encoded key.
+        return { minimum: KEY_SIZE.ED25519_BITS / 8 };
+    }
+    throw keyError(`Algorithm "${String(algorithm)}" does not use cryptographic keys.`, CryptoOperation.KEY_IMPORT, typeof algorithm === "string" ? algorithm : undefined);
+}
+function validateKeyBytes(bytes, algorithm) {
+    if (!(bytes instanceof Uint8Array)) {
+        throw keyError("Cryptographic key material must be a Uint8Array.", CryptoOperation.KEY_IMPORT, algorithm);
+    }
+    if (bytes.byteLength === 0) {
+        throw keyError("Cryptographic key cannot be empty.", CryptoOperation.KEY_IMPORT, algorithm);
+    }
+    if (isHashAlgorithm(algorithm)) {
+        throw keyError(`Hash algorithm "${algorithm}" does not use cryptographic keys.`, CryptoOperation.KEY_IMPORT, algorithm);
+    }
+    const { exact, minimum } = expectedKeyLength(algorithm);
+    if (exact !== undefined && bytes.byteLength !== exact) {
+        throw keyError(`Algorithm "${algorithm}" requires a ${exact}-byte key, received ${bytes.byteLength} bytes.`, CryptoOperation.KEY_IMPORT, algorithm);
+    }
+    if (bytes.byteLength < minimum) {
+        throw keyError(`Algorithm "${algorithm}" requires a key of at least ${minimum} bytes, received ${bytes.byteLength} bytes.`, CryptoOperation.KEY_IMPORT, algorithm);
     }
-    return defaultProvider;
 }
 /**
  * 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 async function createCryptoKey(bytes, options, provider = getDefaultProvider()) {
-    if (bytes.byteLength === 0) {
-        throw new TypeError("Cryptographic key cannot be empty.");
-    }
+export async function createCryptoKey(bytes, options, provider = getDefaultCryptoProvider()) {
+    validateKeyBytes(bytes, options.algorithm);
     const keyBytes = new Uint8Array(bytes);
-    const digest = await provider.hash("sha256", keyBytes);
+    const digest = await provider.hmac("sha256", CRYPTO_KEY_FINGERPRINT_LABEL, keyBytes);
     const fingerprint = encode(digest, "hex");
     const createdAt = Date.now();
     const keyId = options.keyId ?? `key_${await generateKeyId(provider)}`;
@@ -40,17 +77,44 @@ export async function createCryptoKey(bytes, options, provider = getDefaultProvi
     });
 }
 /**
- * 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 async function generateCryptoKey(length, options, provider = getDefaultProvider()) {
+export async function generateCryptoKey(length, options, provider = getDefaultCryptoProvider()) {
+    if (!isSymmetricKeyAlgorithm(options.algorithm)) {
+        throw keyError(`Random key generation is only supported for symmetric algorithms, not "${String(options.algorithm)}".`, CryptoOperation.KEY_GENERATION, typeof options.algorithm === "string" ? options.algorithm : undefined);
+    }
     if (!Number.isInteger(length) || length <= 0) {
         throw new RangeError("Cryptographic key length must be a positive integer.");
     }
     const bytes = await provider.randomBytes(length);
     return createCryptoKey(bytes, options, provider);
 }
+/**
+ * Returns the default key length in bytes for a symmetric algorithm.
+ */
+export function defaultKeyLength(algorithm) {
+    if (isAeadAlgorithm(algorithm)) {
+        return AES_GCM.KEY_BYTES;
+    }
+    switch (algorithm) {
+        case CryptoAlgorithm.HMAC_SHA256:
+        case CryptoAlgorithm.PBKDF2_SHA256:
+        case CryptoAlgorithm.SCRYPT:
+            return 32;
+        case CryptoAlgorithm.HMAC_SHA384:
+        case CryptoAlgorithm.PBKDF2_SHA384:
+            return 48;
+        case CryptoAlgorithm.HMAC_SHA512:
+        case CryptoAlgorithm.PBKDF2_SHA512:
+            return 64;
+        default:
+            throw keyError(`Random key generation is only supported for symmetric algorithms, not "${String(algorithm)}".`, CryptoOperation.KEY_GENERATION, typeof algorithm === "string" ? algorithm : undefined);
+    }
+}
 /**
  * Returns a defensive copy of a key's bytes.
  *
@@ -58,7 +122,7 @@ export async function generateCryptoKey(length, options, provider = getDefaultPr
  */
 export function exportCryptoKey(key) {
     if (!key.extractable) {
-        throw new Error(`Cryptographic key "${key.keyId}" is not extractable.`);
+        throw keyError(`Cryptographic key "${key.keyId}" is not extractable.`, CryptoOperation.KEY_EXPORT, key.algorithm);
     }
     return key.bytes();
 }

package/dist/cryptoKey/cryptoKey.utils.d.ts

@@ -1,9 +1,11 @@
 import type { CryptoKey } from "./cryptoKey.type.js";
 /**
- * Returns a stable SHA-256 fingerprint for a key.
+ * Returns the stable fingerprint of a key.
  *
- * The fingerprint can be used for identification without exposing
- * the secret key material.
+ * The fingerprint is `HMAC-SHA256(CRYPTO_KEY_FINGERPRINT_LABEL, keyBytes)`
+ * in hex. It can be used to identify a key without exposing the secret
+ * material, provided the key has at least 128 bits of entropy (which
+ * `createCryptoKey` enforces by minimum length).
  */
 export declare function getCryptoKeyFingerprint(key: CryptoKey): string;
 /**

package/dist/cryptoKey/cryptoKey.utils.js

@@ -1,8 +1,10 @@
 /**
- * Returns a stable SHA-256 fingerprint for a key.
+ * Returns the stable fingerprint of a key.
  *
- * The fingerprint can be used for identification without exposing
- * the secret key material.
+ * The fingerprint is `HMAC-SHA256(CRYPTO_KEY_FINGERPRINT_LABEL, keyBytes)`
+ * in hex. It can be used to identify a key without exposing the secret
+ * material, provided the key has at least 128 bits of entropy (which
+ * `createCryptoKey` enforces by minimum length).
  */
 export function getCryptoKeyFingerprint(key) {
     return key.fingerprint;

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.core.d.ts

@@ -2,11 +2,17 @@ import type { DerivedKeyResult } from "../cryptoProvider/index.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import type { Pbkdf2Options, ScryptOptions } from "./cryptoKeyDerivation.type.js";
 /**
- * Derives a key from a password using PBKDF2.
+ * Derives a key from a password using PBKDF2-HMAC.
+ *
+ * The digest option is honoured end to end and reflected in
+ * `result.algorithm` (`pbkdf2-sha256`, `pbkdf2-sha384` or `pbkdf2-sha512`).
  */
 export declare function derivePbkdf2(password: string | Uint8Array, options?: Pbkdf2Options): Promise<DerivedKeyResult>;
 /**
  * Derives a key using scrypt.
+ *
+ * `blockSize` and `maxMemory` are forwarded to the provider, so work
+ * factors above the default (e.g. N = 2^17) are usable.
  */
 export declare function deriveScrypt(password: string | Uint8Array, options?: ScryptOptions): Promise<DerivedKeyResult>;
 /**

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.core.js

@@ -1,50 +1,70 @@
-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 { validatePbkdf2Options, validateScryptOptions, } from "./cryptoKeyDerivation.validate.js";
-const provider = createNodeCryptoProvider();
+function pbkdf2Label(digest) {
+    switch (digest) {
+        case "sha256":
+            return CryptoAlgorithm.PBKDF2_SHA256;
+        case "sha384":
+            return CryptoAlgorithm.PBKDF2_SHA384;
+        case "sha512":
+            return CryptoAlgorithm.PBKDF2_SHA512;
+    }
+}
 /**
- * Derives a key from a password using PBKDF2.
+ * Derives a key from a password using PBKDF2-HMAC.
+ *
+ * The digest option is honoured end to end and reflected in
+ * `result.algorithm` (`pbkdf2-sha256`, `pbkdf2-sha384` or `pbkdf2-sha512`).
  */
 export async function derivePbkdf2(password, options = {}) {
-    const iterations = options.iterations ?? 310_000;
+    const provider = options.provider ?? getDefaultCryptoProvider();
+    const iterations = options.iterations ?? PASSWORD_HASH.PBKDF2.ITERATIONS;
     const keyLength = options.keyLength ?? 32;
+    const digest = options.digest ?? "sha256";
     const salt = options.salt ??
         new Uint8Array(await provider.randomBytes(options.saltLength ?? 16));
-    const digest = options.digest ?? "sha256";
-    validatePbkdf2Options(iterations, keyLength, salt);
+    validatePbkdf2Options(iterations, keyLength, salt, digest);
     const key = await provider.deriveKey({
         password,
         salt,
         algorithm: "pbkdf2",
         keyLength,
         iterations,
+        digest,
     });
     return Object.freeze({
-        algorithm: digest === "sha512"
-            ? CryptoAlgorithm.PBKDF2_SHA512
-            : CryptoAlgorithm.PBKDF2_SHA256,
+        algorithm: pbkdf2Label(digest),
+        digest,
         key,
         salt: new Uint8Array(salt),
     });
 }
 /**
  * Derives a key using scrypt.
+ *
+ * `blockSize` and `maxMemory` are forwarded to the provider, so work
+ * factors above the default (e.g. N = 2^17) are usable.
  */
 export async function deriveScrypt(password, options = {}) {
+    const provider = options.provider ?? getDefaultCryptoProvider();
     const keyLength = options.keyLength ?? 32;
-    const cost = options.cost ?? 16_384;
-    const blockSize = options.blockSize ?? 8;
-    const parallelization = options.parallelization ?? 1;
+    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;
     const salt = options.salt ??
         new Uint8Array(await provider.randomBytes(options.saltLength ?? 16));
-    validateScryptOptions(keyLength, cost, blockSize, parallelization, salt);
+    validateScryptOptions(keyLength, cost, blockSize, parallelization, salt, options.maxMemory);
     const key = await provider.deriveKey({
-        password: password instanceof Uint8Array ? password : Buffer.from(password, "utf8"),
+        password,
         salt,
         algorithm: "scrypt",
         keyLength,
         memoryCost: cost,
+        blockSize,
         parallelism: parallelization,
+        maxMemory: options.maxMemory,
     });
     return Object.freeze({
         algorithm: CryptoAlgorithm.SCRYPT,
@@ -62,6 +82,11 @@ export async function deriveKey(password, algorithm, options = {}) {
                 ...options,
                 digest: "sha256",
             });
+        case CryptoAlgorithm.PBKDF2_SHA384:
+            return derivePbkdf2(password, {
+                ...options,
+                digest: "sha384",
+            });
         case CryptoAlgorithm.PBKDF2_SHA512:
             return derivePbkdf2(password, {
                 ...options,
@@ -70,7 +95,7 @@ export async function deriveKey(password, algorithm, options = {}) {
         case CryptoAlgorithm.SCRYPT:
             return deriveScrypt(password, options);
         default:
-            throw new TypeError(`Unsupported key derivation algorithm: ${algorithm}.`);
+            throw new TypeError(`Unsupported key derivation algorithm: ${String(algorithm)}.`);
     }
 }
 //# sourceMappingURL=cryptoKeyDerivation.core.js.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.salt.d.ts

@@ -1,5 +1,6 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Creates a random salt.
  */
-export declare function generateSalt(length?: number): Promise<Uint8Array>;
+export declare function generateSalt(length?: number, provider?: CryptoProvider): Promise<Uint8Array>;
 //# sourceMappingURL=cryptoKeyDerivation.salt.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.salt.js

@@ -1,12 +1,11 @@
-import { createNodeCryptoProvider } from "../node/index.js";
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 /**
  * Creates a random salt.
  */
-export async function generateSalt(length = 16) {
+export async function generateSalt(length = 16, provider = getDefaultCryptoProvider()) {
     if (!Number.isInteger(length) || length < 16) {
         throw new RangeError("Salt length must be an integer of at least 16 bytes.");
     }
-    const provider = createNodeCryptoProvider();
     return provider.randomBytes(length);
 }
 //# sourceMappingURL=cryptoKeyDerivation.salt.js.map

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

@@ -1,12 +1,14 @@
+import type { CryptoProvider, Pbkdf2Digest } from "../cryptoProvider/index.js";
 /**
  * Options for PBKDF2 key derivation.
  */
 export interface Pbkdf2Options {
     readonly iterations?: number;
     readonly keyLength?: number;
-    readonly digest?: "sha256" | "sha384" | "sha512";
+    readonly digest?: Pbkdf2Digest;
     readonly salt?: Uint8Array;
     readonly saltLength?: number;
+    readonly provider?: CryptoProvider;
 }
 /**
  * Options for scrypt key derivation.
@@ -18,6 +20,8 @@ export interface ScryptOptions {
     readonly parallelization?: number;
     readonly salt?: Uint8Array;
     readonly saltLength?: number;
+    /** Memory upper bound in bytes; defaults to a value derived from cost/blockSize/parallelization. */
     readonly maxMemory?: number;
+    readonly provider?: CryptoProvider;
 }
 //# sourceMappingURL=cryptoKeyDerivation.type.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.validate.d.ts

@@ -1,9 +1,20 @@
 /**
  * Validates PBKDF2 key derivation options.
+ *
+ * Both floors and ceilings are enforced: `iterations` is bounded by
+ * `PASSWORD_HASH.LIMITS.MAX_PBKDF2_ITERATIONS` and `keyLength` by
+ * `PASSWORD_HASH.LIMITS.MAX_DERIVED_KEY_BYTES`, so a work factor read from
+ * configuration cannot request unbounded CPU time.
  */
-export declare function validatePbkdf2Options(iterations: number, keyLength: number, salt: Uint8Array): void;
+export declare function validatePbkdf2Options(iterations: number, keyLength: number, salt: Uint8Array, digest?: unknown): void;
 /**
  * Validates scrypt key derivation options.
+ *
+ * `cost`, `blockSize` and `parallelization` are bounded by
+ * `PASSWORD_HASH.LIMITS`, and `128 * cost * blockSize` (the scrypt working
+ * memory) by `MAX_SCRYPT_MEMORY_BYTES`. Without these ceilings the memory
+ * "bound" passed to the provider was derived from the very parameters it
+ * was meant to bound, so a cost of 2^30 allocated terabytes.
  */
-export declare function validateScryptOptions(keyLength: number, cost: number, blockSize: number, parallelization: number, salt: Uint8Array): void;
+export declare function validateScryptOptions(keyLength: number, cost: number, blockSize: number, parallelization: number, salt: Uint8Array, maxMemory?: number): void;
 //# sourceMappingURL=cryptoKeyDerivation.validate.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.validate.js

@@ -1,35 +1,72 @@
+import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
+import { isPbkdf2Digest } from "../cryptoProvider/cryptoProvider.type.js";
+const LIMITS = PASSWORD_HASH.LIMITS;
 /**
  * Validates PBKDF2 key derivation options.
+ *
+ * Both floors and ceilings are enforced: `iterations` is bounded by
+ * `PASSWORD_HASH.LIMITS.MAX_PBKDF2_ITERATIONS` and `keyLength` by
+ * `PASSWORD_HASH.LIMITS.MAX_DERIVED_KEY_BYTES`, so a work factor read from
+ * configuration cannot request unbounded CPU time.
  */
-export function validatePbkdf2Options(iterations, keyLength, salt) {
-    if (!Number.isInteger(iterations) || iterations < 100_000) {
-        throw new RangeError("PBKDF2 iterations must be at least 100000.");
+export function validatePbkdf2Options(iterations, keyLength, salt, digest = "sha256") {
+    if (!Number.isInteger(iterations) ||
+        iterations < PASSWORD_HASH.PBKDF2.MIN_ITERATIONS ||
+        iterations > LIMITS.MAX_PBKDF2_ITERATIONS) {
+        throw new RangeError(`PBKDF2 iterations must be an integer between ${PASSWORD_HASH.PBKDF2.MIN_ITERATIONS} and ${LIMITS.MAX_PBKDF2_ITERATIONS}.`);
     }
-    if (!Number.isInteger(keyLength) || keyLength < 16) {
-        throw new RangeError("PBKDF2 keyLength must be at least 16 bytes.");
+    if (!Number.isInteger(keyLength) ||
+        keyLength < 16 ||
+        keyLength > LIMITS.MAX_DERIVED_KEY_BYTES) {
+        throw new RangeError(`PBKDF2 keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`);
     }
-    if (salt.byteLength < 16) {
+    if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
         throw new RangeError("PBKDF2 salt must be at least 16 bytes.");
     }
+    if (!isPbkdf2Digest(digest)) {
+        throw new TypeError(`Unsupported PBKDF2 digest: ${String(digest)}.`);
+    }
 }
 /**
  * Validates scrypt key derivation options.
+ *
+ * `cost`, `blockSize` and `parallelization` are bounded by
+ * `PASSWORD_HASH.LIMITS`, and `128 * cost * blockSize` (the scrypt working
+ * memory) by `MAX_SCRYPT_MEMORY_BYTES`. Without these ceilings the memory
+ * "bound" passed to the provider was derived from the very parameters it
+ * was meant to bound, so a cost of 2^30 allocated terabytes.
  */
-export function validateScryptOptions(keyLength, cost, blockSize, parallelization, salt) {
-    if (!Number.isInteger(keyLength) || keyLength < 16) {
-        throw new RangeError("scrypt keyLength must be at least 16 bytes.");
+export function validateScryptOptions(keyLength, cost, blockSize, parallelization, salt, maxMemory) {
+    if (!Number.isInteger(keyLength) ||
+        keyLength < 16 ||
+        keyLength > LIMITS.MAX_DERIVED_KEY_BYTES) {
+        throw new RangeError(`scrypt keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`);
+    }
+    if (!Number.isInteger(cost) ||
+        cost < 2 ||
+        cost > LIMITS.MAX_SCRYPT_COST ||
+        (cost & (cost - 1)) !== 0) {
+        throw new RangeError(`scrypt cost must be a power of two between 2 and ${LIMITS.MAX_SCRYPT_COST}.`);
     }
-    if (!Number.isInteger(cost) || cost < 2 || (cost & (cost - 1)) !== 0) {
-        throw new RangeError("scrypt cost must be a power of two greater than or equal to 2.");
+    if (!Number.isInteger(blockSize) ||
+        blockSize <= 0 ||
+        blockSize > LIMITS.MAX_SCRYPT_BLOCK_SIZE) {
+        throw new RangeError(`scrypt blockSize must be an integer between 1 and ${LIMITS.MAX_SCRYPT_BLOCK_SIZE}.`);
     }
-    if (!Number.isInteger(blockSize) || blockSize <= 0) {
-        throw new RangeError("scrypt blockSize must be a positive integer.");
+    if (!Number.isInteger(parallelization) ||
+        parallelization <= 0 ||
+        parallelization > LIMITS.MAX_SCRYPT_PARALLELIZATION) {
+        throw new RangeError(`scrypt parallelization must be an integer between 1 and ${LIMITS.MAX_SCRYPT_PARALLELIZATION}.`);
     }
-    if (!Number.isInteger(parallelization) || parallelization <= 0) {
-        throw new RangeError("scrypt parallelization must be a positive integer.");
+    if (128 * cost * blockSize > LIMITS.MAX_SCRYPT_MEMORY_BYTES) {
+        throw new RangeError(`scrypt cost * blockSize exceeds the memory bound of ${LIMITS.MAX_SCRYPT_MEMORY_BYTES} bytes.`);
     }
-    if (salt.byteLength < 16) {
+    if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
         throw new RangeError("scrypt salt must be at least 16 bytes.");
     }
+    if (maxMemory !== undefined &&
+        (!Number.isInteger(maxMemory) || maxMemory <= 0)) {
+        throw new RangeError("scrypt maxMemory must be a positive integer.");
+    }
 }
 //# sourceMappingURL=cryptoKeyDerivation.validate.js.map

package/dist/cryptoPassword/cryptoPassword.codec.d.ts

@@ -1,10 +1,24 @@
-import type { PasswordHashParameters } from "./cryptoPassword.type.js";
+import type { Pbkdf2Digest } from "../cryptoProvider/cryptoProvider.type.js";
+import type { PasswordHashParameters, Pbkdf2PasswordAlgorithm } from "./cryptoPassword.type.js";
 /**
  * Current password hash encoding format version.
  */
 export declare const PASSWORD_FORMAT_VERSION = "v1";
+/**
+ * Returns the PBKDF2 password algorithm label for a digest.
+ */
+export declare function pbkdf2PasswordAlgorithm(digest: Pbkdf2Digest): Pbkdf2PasswordAlgorithm;
 /**
  * Decodes an encoded password hash into its parameters.
+ *
+ * Supported formats:
+ *
+ * - `v1$scrypt$<N>$<r>$<p>$<salt>.<hash>`
+ * - `v1$pbkdf2-<digest>$<iterations>$<salt>.<hash>`
+ *
+ * All binary fields are canonical Base64URL. Parameters are validated
+ * against `PASSWORD_HASH.LIMITS`, so a decoded hash is always safe to
+ * re-derive.
  */
 export declare function decodePasswordHash(encoded: string): PasswordHashParameters;
 /**