@zudojs/crypto 1.3.2 → 1.4.0

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

@@ -3,8 +3,15 @@ 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.
+ * The key is raw bytes, not text: a string secret must be encoded first
+ * (`new TextEncoder().encode(secret)` or `Buffer.from(secret, "utf8")`), and
+ * it must be at least `KEY_SIZE.MIN_HMAC_KEY_BYTES` (16) bytes so that a
+ * missing or empty secret cannot silently produce forgeable tags.
+ *
+ * @throws {TypeError} when the key is not a `Uint8Array` or the algorithm
+ *   name is unknown (argument-shape errors).
+ * @throws {CryptoError} `CRYPTO_HASH` when the key is shorter than
+ *   `KEY_SIZE.MIN_HMAC_KEY_BYTES`.
  */
 export declare function hmac(input: HashInput, key: Uint8Array, algorithm?: HmacAlgorithm, encoding?: HashEncoding, provider?: CryptoProvider): Promise<string>;
 /**
@@ -19,4 +26,3 @@ export declare function hmacSha384(input: HashInput, key: Uint8Array, encoding?:
  * Calculates a SHA-512 HMAC.
  */
 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

@@ -2,22 +2,33 @@ import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.defau
 import { assertHmacCapability } from "../cryptoProvider/cryptoProvider.capability.js";
 import { isHmacAlgorithmName } from "../cryptoProvider/cryptoProvider.type.js";
 import { KEY_SIZE } from "../cryptoConstants/cryptoConstants.type.js";
+import { hashError } from "../cryptoErrors/cryptoErrors.helper.js";
 import { encodeDigest } from "./cryptoHash.codec.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.
+ * The key is raw bytes, not text: a string secret must be encoded first
+ * (`new TextEncoder().encode(secret)` or `Buffer.from(secret, "utf8")`), and
+ * it must be at least `KEY_SIZE.MIN_HMAC_KEY_BYTES` (16) bytes so that a
+ * missing or empty secret cannot silently produce forgeable tags.
+ *
+ * @throws {TypeError} when the key is not a `Uint8Array` or the algorithm
+ *   name is unknown (argument-shape errors).
+ * @throws {CryptoError} `CRYPTO_HASH` when the key is shorter than
+ *   `KEY_SIZE.MIN_HMAC_KEY_BYTES`.
  */
 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.");
+        throw new TypeError("HMAC key must be a Uint8Array of raw key bytes" +
+            (typeof key === "string"
+                ? '; encode a string secret first, e.g. new TextEncoder().encode(secret) or Buffer.from(secret, "utf8").'
+                : "."));
     }
     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.`);
+        throw hashError(`HMAC key must be at least ${KEY_SIZE.MIN_HMAC_KEY_BYTES} bytes, received ${key.byteLength}.`, `hmac-${algorithm}`);
     }
     assertHmacCapability(provider);
     const digest = await provider.hmac(algorithm, key, input);
@@ -41,4 +52,3 @@ export async function hmacSha384(input, key, encoding = "hex", provider) {
 export async function hmacSha512(input, key, encoding = "hex", provider) {
     return hmac(input, key, "sha512", encoding, provider);
 }
-//# sourceMappingURL=cryptoHmac.core.js.map

package/dist/cryptoHash/index.d.ts

@@ -8,4 +8,3 @@ export * from "./cryptoHash.convenience.js";
 export * from "./cryptoHmac.core.js";
 export * from "./cryptoHash.compare.js";
 export * from "./cryptoHash.codec.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoHash/index.js

@@ -8,4 +8,3 @@ export * from "./cryptoHash.convenience.js";
 export * from "./cryptoHmac.core.js";
 export * from "./cryptoHash.compare.js";
 export * from "./cryptoHash.codec.js";
-//# sourceMappingURL=index.js.map

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

@@ -30,9 +30,15 @@ export declare function createCryptoKey(bytes: Uint8Array, options: CryptoKeyOpt
 /**
  * Generates a cryptographically secure random symmetric key.
  *
+ * `length` is in **bytes** (`generateCryptoKey(32, …)` is a 256-bit key);
+ * the returned key reports `byteLength: 32` and `length: 256` (bits).
+ *
  * 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.
+ *
+ * @throws {CryptoError} `CRYPTO_KEY` when the algorithm is asymmetric or
+ *   `length` is not a positive integer.
  */
 export declare function generateCryptoKey(length: number, options: CryptoKeyOptions, provider?: CryptoProvider): Promise<CryptoKey>;
 /**
@@ -45,4 +51,3 @@ export declare function defaultKeyLength(algorithm: CryptoAlgorithm): number;
  * This operation is only permitted for extractable keys.
  */
 export declare function exportCryptoKey(key: CryptoKey): Uint8Array;
-//# sourceMappingURL=cryptoKey.factory.d.ts.map

package/dist/cryptoKey/cryptoKey.factory.js

@@ -75,6 +75,7 @@ export async function createCryptoKey(bytes, options, provider = getDefaultCrypt
         extractable: options.extractable ?? false,
         createdAt,
         length: keyBytes.byteLength * 8,
+        byteLength: keyBytes.byteLength,
         fingerprint,
         bytes: () => new Uint8Array(keyBytes),
     });
@@ -82,16 +83,22 @@ export async function createCryptoKey(bytes, options, provider = getDefaultCrypt
 /**
  * Generates a cryptographically secure random symmetric key.
  *
+ * `length` is in **bytes** (`generateCryptoKey(32, …)` is a 256-bit key);
+ * the returned key reports `byteLength: 32` and `length: 256` (bits).
+ *
  * 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.
+ *
+ * @throws {CryptoError} `CRYPTO_KEY` when the algorithm is asymmetric or
+ *   `length` is not a positive integer.
  */
 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.");
+        throw keyError("Cryptographic key length must be a positive integer number of bytes.", CryptoOperation.KEY_GENERATION, options.algorithm);
     }
     assertRandomCapability(provider);
     const bytes = await provider.randomBytes(length);
@@ -137,4 +144,3 @@ async function generateKeyId(provider) {
     const idBytes = await provider.randomBytes(16);
     return encode(idBytes, "hex");
 }
-//# sourceMappingURL=cryptoKey.factory.js.map

package/dist/cryptoKey/cryptoKey.type.d.ts

@@ -17,6 +17,15 @@ export declare enum CryptoKeyUsage {
  *
  * The underlying byte array is copied when a key is created and when
  * its bytes are requested to prevent accidental mutation.
+ *
+ * Units: `length` is in **bits** (256 for a 32-byte key) and `byteLength`
+ * in bytes; `generateCryptoKey(length)` takes bytes.
+ *
+ * `extractable` gates the public export path (`exportCryptoKey`) and
+ * conversion to a signing key. `bytes()` is the raw accessor the providers
+ * use to perform operations with the key, so it is available regardless of
+ * `extractable`; treat it as internal and hand keys to the package's
+ * functions rather than reading them out.
  */
 export interface CryptoKey {
     readonly algorithm: CryptoAlgorithm;
@@ -24,7 +33,10 @@ export interface CryptoKey {
     readonly usages: readonly CryptoKeyUsage[];
     readonly extractable: boolean;
     readonly createdAt: number;
+    /** Key size in bits. */
     readonly length: number;
+    /** Key size in bytes (`length / 8`). */
+    readonly byteLength: number;
     readonly fingerprint: string;
     readonly bytes: () => Uint8Array;
 }
@@ -41,4 +53,3 @@ export interface CryptoKeyOptions {
  * Checks whether a value is a CryptoKey.
  */
 export declare function isCryptoKey(value: unknown): value is CryptoKey;
-//# sourceMappingURL=cryptoKey.type.d.ts.map

package/dist/cryptoKey/cryptoKey.type.js

@@ -29,4 +29,3 @@ export function isCryptoKey(value) {
         typeof key.fingerprint === "string" &&
         typeof key.bytes === "function");
 }
-//# sourceMappingURL=cryptoKey.type.js.map

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

@@ -12,4 +12,3 @@ export declare function getCryptoKeyFingerprint(key: CryptoKey): string;
  * Compares two cryptographic keys by identity.
  */
 export declare function cryptoKeysEqual(left: CryptoKey, right: CryptoKey): boolean;
-//# sourceMappingURL=cryptoKey.utils.d.ts.map

package/dist/cryptoKey/cryptoKey.utils.js

@@ -17,4 +17,3 @@ export function cryptoKeysEqual(left, right) {
         left.fingerprint === right.fingerprint &&
         left.algorithm === right.algorithm);
 }
-//# sourceMappingURL=cryptoKey.utils.js.map

package/dist/cryptoKey/index.d.ts

@@ -6,4 +6,3 @@
 export * from "./cryptoKey.type.js";
 export * from "./cryptoKey.factory.js";
 export * from "./cryptoKey.utils.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoKey/index.js

@@ -6,4 +6,3 @@
 export * from "./cryptoKey.type.js";
 export * from "./cryptoKey.factory.js";
 export * from "./cryptoKey.utils.js";
-//# sourceMappingURL=index.js.map

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

@@ -19,4 +19,3 @@ export declare function deriveScrypt(password: string | Uint8Array, options?: Sc
  * Derives a key using the selected key derivation algorithm.
  */
 export declare function deriveKey(password: string | Uint8Array, algorithm: CryptoAlgorithm, options?: Pbkdf2Options | ScryptOptions): Promise<DerivedKeyResult>;
-//# sourceMappingURL=cryptoKeyDerivation.core.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.core.js

@@ -104,4 +104,3 @@ export async function deriveKey(password, algorithm, options = {}) {
             throw new TypeError(`Unsupported key derivation algorithm: ${String(algorithm)}.`);
     }
 }
-//# sourceMappingURL=cryptoKeyDerivation.core.js.map

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

@@ -1,6 +1,8 @@
 import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
- * Creates a random salt.
+ * Creates a random salt of `length` bytes (default 16).
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` when `length` is not an integer
+ *   of at least 16.
  */
 export declare function generateSalt(length?: number, provider?: CryptoProvider): Promise<Uint8Array>;
-//# sourceMappingURL=cryptoKeyDerivation.salt.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.salt.js

@@ -1,13 +1,16 @@
 import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
 import { assertRandomCapability } from "../cryptoProvider/cryptoProvider.capability.js";
+import { keyDerivationError } from "../cryptoErrors/cryptoErrors.helper.js";
 /**
- * Creates a random salt.
+ * Creates a random salt of `length` bytes (default 16).
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` when `length` is not an integer
+ *   of at least 16.
  */
 export async function generateSalt(length = 16, provider = getDefaultCryptoProvider()) {
     assertRandomCapability(provider);
     if (!Number.isInteger(length) || length < 16) {
-        throw new RangeError("Salt length must be an integer of at least 16 bytes.");
+        throw keyDerivationError("Salt length must be an integer of at least 16 bytes.", undefined);
     }
     return provider.randomBytes(length);
 }
-//# sourceMappingURL=cryptoKeyDerivation.salt.js.map

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

@@ -24,4 +24,3 @@ export interface ScryptOptions {
     readonly maxMemory?: number;
     readonly provider?: CryptoProvider;
 }
-//# sourceMappingURL=cryptoKeyDerivation.type.d.ts.map

package/dist/cryptoKeyDerivation/cryptoKeyDerivation.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=cryptoKeyDerivation.type.js.map

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

@@ -5,6 +5,9 @@
  * `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.
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` for an out-of-range work factor,
+ *   key length or salt; `TypeError` for an unknown digest name.
  */
 export declare function validatePbkdf2Options(iterations: number, keyLength: number, salt: Uint8Array, digest?: unknown): void;
 /**
@@ -15,6 +18,8 @@ export declare function validatePbkdf2Options(iterations: number, keyLength: num
  * 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.
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` for any parameter outside its
+ *   bound.
  */
 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,5 +1,6 @@
 import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
 import { isPbkdf2Digest } from "../cryptoProvider/cryptoProvider.type.js";
+import { keyDerivationError } from "../cryptoErrors/cryptoErrors.helper.js";
 const LIMITS = PASSWORD_HASH.LIMITS;
 /**
  * Validates PBKDF2 key derivation options.
@@ -8,20 +9,23 @@ const LIMITS = PASSWORD_HASH.LIMITS;
  * `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.
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` for an out-of-range work factor,
+ *   key length or salt; `TypeError` for an unknown digest name.
  */
 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}.`);
+        throw keyDerivationError(`PBKDF2 iterations must be an integer between ${PASSWORD_HASH.PBKDF2.MIN_ITERATIONS} and ${LIMITS.MAX_PBKDF2_ITERATIONS}.`, "pbkdf2");
     }
     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.`);
+        throw keyDerivationError(`PBKDF2 keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`, "pbkdf2");
     }
     if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
-        throw new RangeError("PBKDF2 salt must be at least 16 bytes.");
+        throw keyDerivationError("PBKDF2 salt must be at least 16 bytes.", "pbkdf2");
     }
     if (!isPbkdf2Digest(digest)) {
         throw new TypeError(`Unsupported PBKDF2 digest: ${String(digest)}.`);
@@ -35,38 +39,40 @@ export function validatePbkdf2Options(iterations, keyLength, salt, digest = "sha
  * 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.
+ *
+ * @throws {CryptoError} `CRYPTO_DERIVATION` for any parameter outside its
+ *   bound.
  */
 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.`);
+        throw keyDerivationError(`scrypt keyLength must be an integer between 16 and ${LIMITS.MAX_DERIVED_KEY_BYTES} bytes.`, "scrypt");
     }
     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}.`);
+        throw keyDerivationError(`scrypt cost must be a power of two between 2 and ${LIMITS.MAX_SCRYPT_COST}.`, "scrypt");
     }
     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}.`);
+        throw keyDerivationError(`scrypt blockSize must be an integer between 1 and ${LIMITS.MAX_SCRYPT_BLOCK_SIZE}.`, "scrypt");
     }
     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}.`);
+        throw keyDerivationError(`scrypt parallelization must be an integer between 1 and ${LIMITS.MAX_SCRYPT_PARALLELIZATION}.`, "scrypt");
     }
     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.`);
+        throw keyDerivationError(`scrypt cost * blockSize exceeds the memory bound of ${LIMITS.MAX_SCRYPT_MEMORY_BYTES} bytes.`, "scrypt");
     }
     if (!(salt instanceof Uint8Array) || salt.byteLength < 16) {
-        throw new RangeError("scrypt salt must be at least 16 bytes.");
+        throw keyDerivationError("scrypt salt must be at least 16 bytes.", "scrypt");
     }
     if (maxMemory !== undefined &&
         (!Number.isInteger(maxMemory) || maxMemory <= 0)) {
-        throw new RangeError("scrypt maxMemory must be a positive integer.");
+        throw keyDerivationError("scrypt maxMemory must be a positive integer.", "scrypt");
     }
 }
-//# sourceMappingURL=cryptoKeyDerivation.validate.js.map

package/dist/cryptoKeyDerivation/index.d.ts

@@ -7,4 +7,3 @@ export * from "./cryptoKeyDerivation.core.js";
 export * from "./cryptoKeyDerivation.type.js";
 export * from "./cryptoKeyDerivation.salt.js";
 export * from "./cryptoKeyDerivation.validate.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoKeyDerivation/index.js

@@ -7,4 +7,3 @@ export * from "./cryptoKeyDerivation.core.js";
 export * from "./cryptoKeyDerivation.type.js";
 export * from "./cryptoKeyDerivation.salt.js";
 export * from "./cryptoKeyDerivation.validate.js";
-//# sourceMappingURL=index.js.map

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

@@ -25,4 +25,3 @@ export declare function decodePasswordHash(encoded: string): PasswordHashParamet
  * Encodes password hashing parameters into a portable string.
  */
 export declare function encodePasswordHash(parameters: PasswordHashParameters): string;
-//# sourceMappingURL=cryptoPassword.codec.d.ts.map

package/dist/cryptoPassword/cryptoPassword.codec.js

@@ -155,4 +155,3 @@ function decodePayload(payload) {
     }
     return { salt, hash };
 }
-//# sourceMappingURL=cryptoPassword.codec.js.map

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

@@ -2,15 +2,25 @@ import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { PasswordHashOptions, PasswordHashResult } from "./cryptoPassword.type.js";
 /**
  * Options for `hashPassword` including an optional provider override.
+ *
+ * `minLength` opts into a minimum password length; pass
+ * `PASSWORD_POLICY.MIN_LENGTH` (8) to apply the package policy. It is
+ * opt-in because `hashPassword` is also used to re-hash existing
+ * credentials that predate the policy; enforce it at registration and
+ * password change.
  */
 export interface HashPasswordOptions extends PasswordHashOptions {
     readonly provider?: CryptoProvider;
+    readonly minLength?: number;
 }
 /**
  * Hashes a password using scrypt.
  *
  * `saltBytes` and `keyBytes` are honoured, and the returned `salt`/`hash`
  * are exactly the values inside `encoded`.
+ *
+ * @throws {CryptoError} `CRYPTO_HASH` when the password is outside the
+ *   length bounds (user-facing, 400) or a work factor is out of range.
  */
 export declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<PasswordHashResult>;
 /**
@@ -21,4 +31,3 @@ export declare function hashPassword(password: string, options?: HashPasswordOpt
  * password also yields false.
  */
 export declare function verifyPassword(password: string, encoded: string, provider?: CryptoProvider): Promise<boolean>;
-//# sourceMappingURL=cryptoPassword.core.d.ts.map

package/dist/cryptoPassword/cryptoPassword.core.js

@@ -2,17 +2,27 @@ import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.defau
 import { assertPasswordHashingCapability, assertRandomCapability, } from "../cryptoProvider/cryptoProvider.capability.js";
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
 import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
-import { assertPassword, validateParameters, } from "./cryptoPassword.validate.js";
+import { validateParameters } from "./cryptoPassword.validate.js";
 import { decodePasswordHash, PASSWORD_FORMAT_VERSION, } from "./cryptoPassword.codec.js";
-import { assertNewHashCost } from "./cryptoPassword.helper.js";
+import { assertNewHashCost, assertPassword, } from "./cryptoPassword.helper.js";
+import { PASSWORD_POLICY } from "../cryptoConstants/cryptoConstants.security.js";
 /**
  * Hashes a password using scrypt.
  *
  * `saltBytes` and `keyBytes` are honoured, and the returned `salt`/`hash`
  * are exactly the values inside `encoded`.
+ *
+ * @throws {CryptoError} `CRYPTO_HASH` when the password is outside the
+ *   length bounds (user-facing, 400) or a work factor is out of range.
  */
 export async function hashPassword(password, options = {}) {
-    assertPassword(password);
+    if (options.minLength !== undefined &&
+        (!Number.isInteger(options.minLength) ||
+            options.minLength < 1 ||
+            options.minLength > PASSWORD_POLICY.MAX_LENGTH)) {
+        throw new RangeError(`minLength must be an integer between 1 and ${PASSWORD_POLICY.MAX_LENGTH}.`);
+    }
+    assertPassword(password, options.minLength);
     const provider = options.provider ?? getDefaultCryptoProvider();
     assertPasswordHashingCapability(provider);
     assertRandomCapability(provider);
@@ -70,4 +80,3 @@ export async function verifyPassword(password, encoded, provider = getDefaultCry
         return false;
     }
 }
-//# sourceMappingURL=cryptoPassword.core.js.map

package/dist/cryptoPassword/cryptoPassword.helper.d.ts

@@ -19,7 +19,15 @@ export declare function isValidPassword(password: string, minimumLength?: number
  * older stored hashes stay verifiable; minting a new hash with `cost: 2`
  * produced a hash that is effectively free to crack.
  *
- * @throws {RangeError} when `cost` is below the floor.
+ * @throws {CryptoError} `CRYPTO_HASH` when `cost` is below the floor.
  */
 export declare function assertNewHashCost(cost: number): void;
-//# sourceMappingURL=cryptoPassword.helper.d.ts.map
+/**
+ * Asserts that a value is a password string within the length bounds:
+ * non-empty, at least `minLength` code units when one is given, and at
+ * most `PASSWORD_POLICY.MAX_LENGTH`.
+ *
+ * Length violations are user-facing `CryptoError`s (`CRYPTO_HASH`,
+ * `statusCode` 400, `expose` true); a non-string is a `TypeError`.
+ */
+export declare function assertPassword(password: string, minLength?: number): void;

package/dist/cryptoPassword/cryptoPassword.helper.js

@@ -1,4 +1,5 @@
-import { PASSWORD_HASH } from "../cryptoConstants/cryptoConstants.security.js";
+import { PASSWORD_HASH, PASSWORD_POLICY, } from "../cryptoConstants/cryptoConstants.security.js";
+import { passwordHashError } from "../cryptoErrors/cryptoErrors.helper.js";
 import { decodePasswordHash } from "./cryptoPassword.codec.js";
 const PASSWORD_MINIMUM_DEFAULT_LENGTH = 8;
 /**
@@ -39,11 +40,32 @@ export function isValidPassword(password, minimumLength = PASSWORD_MINIMUM_DEFAU
  * older stored hashes stay verifiable; minting a new hash with `cost: 2`
  * produced a hash that is effectively free to crack.
  *
- * @throws {RangeError} when `cost` is below the floor.
+ * @throws {CryptoError} `CRYPTO_HASH` when `cost` is below the floor.
  */
 export function assertNewHashCost(cost) {
     if (typeof cost === "number" && cost < PASSWORD_HASH.SCRYPT.MIN_COST) {
-        throw new RangeError(`scrypt cost for a new password hash must be at least ${PASSWORD_HASH.SCRYPT.MIN_COST}.`);
+        throw passwordHashError(`scrypt cost for a new password hash must be at least ${PASSWORD_HASH.SCRYPT.MIN_COST}.`);
+    }
+}
+/**
+ * Asserts that a value is a password string within the length bounds:
+ * non-empty, at least `minLength` code units when one is given, and at
+ * most `PASSWORD_POLICY.MAX_LENGTH`.
+ *
+ * Length violations are user-facing `CryptoError`s (`CRYPTO_HASH`,
+ * `statusCode` 400, `expose` true); a non-string is a `TypeError`.
+ */
+export function assertPassword(password, minLength) {
+    if (typeof password !== "string") {
+        throw new TypeError("Password must be a string.");
+    }
+    if (password.length === 0) {
+        throw new TypeError("Password cannot be empty.");
+    }
+    if (minLength !== undefined && password.length < minLength) {
+        throw passwordHashError(`Password must be at least ${minLength} characters.`, { userFacing: true });
+    }
+    if (password.length > PASSWORD_POLICY.MAX_LENGTH) {
+        throw passwordHashError(`Password must not exceed ${PASSWORD_POLICY.MAX_LENGTH} characters.`, { userFacing: true });
     }
 }
-//# sourceMappingURL=cryptoPassword.helper.js.map

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

@@ -62,4 +62,3 @@ export interface Pbkdf2PasswordHashParameters {
  * Discriminate on `algorithm` to access algorithm-specific fields.
  */
 export type PasswordHashParameters = ScryptPasswordHashParameters | Pbkdf2PasswordHashParameters;
-//# sourceMappingURL=cryptoPassword.type.d.ts.map

package/dist/cryptoPassword/cryptoPassword.type.js

@@ -1,2 +1 @@
 import { CryptoAlgorithm } from "../cryptoConstants/cryptoConstants.type.js";
-//# sourceMappingURL=cryptoPassword.type.js.map

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

@@ -2,6 +2,8 @@
  * 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.
+ *
+ * @throws {CryptoError} `CRYPTO_HASH` for any parameter outside its bound.
  */
 export declare function validateParameters(parameters: {
     readonly saltBytes: number;
@@ -12,6 +14,8 @@ export declare function validateParameters(parameters: {
 }): void;
 /**
  * Validates PBKDF2 password hashing parameters, including upper bounds.
+ *
+ * @throws {CryptoError} `CRYPTO_HASH` for any parameter outside its bound.
  */
 export declare function validatePbkdf2Parameters(parameters: {
     readonly saltBytes: number;
@@ -26,9 +30,3 @@ export declare function parsePositiveInteger(value: string, name: string): numbe
  * Decodes a non-empty, canonical Base64URL string into bytes.
  */
 export declare function decodeBase64Url(value: string): Uint8Array;
-/**
- * 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