@zudojs/crypto 1.3.2 → 1.4.0

package/README.md

@@ -46,12 +46,12 @@ const sessionToken = await generateToken({ bytes: 32, prefix: "sess_" });
 
 ## Features
 
-- Hashing: SHA-256/384/512 and SHA3-256/384/512, HMAC (keys of at least 16 bytes)
-- Authenticated encryption: AES-256-GCM with strict IV (12 bytes) and tag (16 bytes) validation, plus a versioned string envelope
-- Password hashing: scrypt (default N=2^14, r=8, p=5 — the OWASP row for that N) and PBKDF2-HMAC (provider level), versioned self-describing encoding, bounded parameters on verification. New hashes must use a cost of at least `PASSWORD_HASH.SCRYPT.MIN_COST` (16 384); older stored hashes with a smaller cost still verify. Key derivation (`deriveScrypt`) keeps p=1 by default, so derived keys do not change
+- Hashing: SHA-256/384/512 and SHA3-256/384/512, HMAC (the key is a `Uint8Array` of at least 16 bytes — encode a string secret with `new TextEncoder().encode(secret)` first)
+- Authenticated encryption: AES-256-GCM with strict IV (12 bytes) and tag (16 bytes) validation, plus a versioned string envelope. Omit `iv` to get a fresh random one per call; a caller-supplied `iv` is refused if this process already encrypted with it under the same key (`unsafeAllowIvReuse` opts out, for test vectors only)
+- Password hashing: scrypt (default N=2^14, r=8, p=5 — the OWASP row for that N) and PBKDF2-HMAC (provider level), versioned self-describing encoding, bounded parameters on verification. New hashes must use a cost of at least `PASSWORD_HASH.SCRYPT.MIN_COST` (16 384); older stored hashes with a smaller cost still verify. Key derivation (`deriveScrypt`) keeps p=1 by default, so derived keys do not change. `hashPassword(password, { minLength: PASSWORD_POLICY.MIN_LENGTH })` opts into the 8-character minimum; the default stays permissive so existing credentials can be re-hashed
 - Key derivation: PBKDF2 (sha256/384/512, 600 000 iterations by default) and scrypt (cost, block size, parallelization, memory bound); every work factor and the output length are capped by `PASSWORD_HASH.LIMITS`, so a value read from configuration cannot request unbounded CPU or memory
 - Digital signatures: Ed25519, RSA-SHA256/384/512, ECDSA-SHA256/384/512; the algorithm label is bound to the key type
-- Secure random: unbiased integers up to 2^48, UUID v4, bytes, alphabets, numeric codes
+- Secure random: unbiased integers up to 2^48, UUID v4, bytes, alphabets, numeric codes. Units: `randomHex(n)` is `n` characters, `randomBase64Url(n)` is `n` bytes, `generateCryptoKey(n)` is `n` bytes and the resulting `CryptoKey` reports `length` in bits and `byteLength` in bytes
 - Opaque tokens (API keys, sessions, refresh, CSRF, OTP) with SHA-256 storage hashes
 - Encoding helpers (hex, base64, base64url, strict UTF-8) with canonical-form validation and constant-time comparison
 - Provider injection: `setDefaultCryptoProvider`, `createCryptoService({ provider })`, `createCryptoFactory({ provider })`, or a `provider` option on any helper
@@ -60,7 +60,7 @@ Not implemented (and not advertised by the types): bcrypt, Argon2, ChaCha20-Poly
 
 ## Errors
 
-Failures throw `CryptoError` from `@zudojs/errors` with a stable `code` (`ERR_CRYPTO_CIPHER`, `ERR_CRYPTO_HASH`, ...) and the underlying Node error as `cause`. `verifyPassword` and `verifyTokenHash` return `false` (never throw) for wrong or malformed inputs.
+Failures throw `CryptoError` from `@zudojs/errors` with a stable `code` (`ERR_CRYPTO_CIPHER`, `ERR_CRYPTO_HASH`, ...) and the underlying Node error as `cause`. Cryptographic parameter violations are `CryptoError`s too: a short HMAC key (`ERR_CRYPTO_HASH`), an out-of-range scrypt/PBKDF2 work factor (`ERR_CRYPTO_DERIVATION` for `derive*`, `ERR_CRYPTO_HASH` for `hashPassword`), a bad key length (`ERR_CRYPTO_KEY`), and a password outside the length bounds (`ERR_CRYPTO_HASH` with `statusCode: 400` and `expose: true`, since the end user can act on it). Plain argument-shape mistakes — a non-`Uint8Array` key, an unknown algorithm name, a non-integer random length — stay `TypeError`/`RangeError`. `verifyPassword` and `verifyTokenHash` return `false` (never throw) for wrong or malformed inputs.
 
 ## Use Cases
 

package/dist/compare/compare.helper.d.ts

@@ -13,4 +13,3 @@ export declare function timingSafeEqual(left: Uint8Array, right: Uint8Array): bo
  * Performs a constant-time comparison of two strings by their UTF-8 bytes.
  */
 export declare function timingSafeEqualString(left: string, right: string): boolean;
-//# sourceMappingURL=compare.helper.d.ts.map

package/dist/compare/compare.helper.js

@@ -30,4 +30,3 @@ export function timingSafeEqualString(left, right) {
     }
     return timingSafeEqual(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
 }
-//# sourceMappingURL=compare.helper.js.map

package/dist/compare/index.d.ts

@@ -4,4 +4,3 @@
  * Constant-time comparison utilities for cryptographic operations.
  */
 export * from "./compare.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/compare/index.js

@@ -4,4 +4,3 @@
  * Constant-time comparison utilities for cryptographic operations.
  */
 export * from "./compare.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/cryptoCipher/cryptoCipher.core.d.ts

@@ -6,11 +6,20 @@ import type { CryptoProvider } from "../cryptoProvider/index.js";
  * key. Reusing an IV under the same key with AES-GCM leaks the XOR of the
  * plaintexts and allows authentication-key recovery; omit it to have a
  * fresh random IV drawn for every call.
+ *
+ * A supplied `iv` is checked against every (key, iv) pair this process has
+ * already encrypted with, and a repeat is refused with a `CryptoError`
+ * (see {@link assertIvNotReused}). The check is per process and cannot
+ * see other processes or earlier runs, so it is a safety net, not a
+ * uniqueness guarantee. `unsafeAllowIvReuse` disables it for the rare case
+ * that genuinely needs a repeated nonce, such as replaying a published
+ * test vector; never set it in application code.
  */
 export interface CipherOptions {
     readonly iv?: Uint8Array;
     readonly aad?: Uint8Array;
     readonly provider?: CryptoProvider;
+    readonly unsafeAllowIvReuse?: boolean;
 }
 /**
  * Authenticated encryption result.
@@ -23,6 +32,9 @@ export interface CipherResult {
 }
 /**
  * Encrypts data using AES-256-GCM.
+ *
+ * @throws {CryptoError} `CRYPTO_CIPHER` when a supplied `iv` is not 12
+ *   bytes, or was already used with this key in this process.
  */
 export declare function encrypt(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions): Promise<CipherResult>;
 /**
@@ -32,4 +44,3 @@ export declare function encrypt(plaintext: Uint8Array, key: Uint8Array, options?
  * tags are rejected before the cipher is touched.
  */
 export declare function decrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array, provider?: CryptoProvider): Promise<Uint8Array>;
-//# sourceMappingURL=cryptoCipher.core.d.ts.map

package/dist/cryptoCipher/cryptoCipher.core.js

@@ -3,8 +3,12 @@ import { assertProviderCapability } from "../cryptoProvider/cryptoProvider.capab
 import { AES_GCM } from "../cryptoConstants/cryptoConstants.type.js";
 import { CryptoOperation } from "@zudojs/errors";
 import { cipherError } from "../cryptoErrors/cryptoErrors.helper.js";
+import { assertIvNotReused } from "./cryptoCipher.nonceGuard.js";
 /**
  * Encrypts data using AES-256-GCM.
+ *
+ * @throws {CryptoError} `CRYPTO_CIPHER` when a supplied `iv` is not 12
+ *   bytes, or was already used with this key in this process.
  */
 export async function encrypt(plaintext, key, options = {}) {
     if (options.iv !== undefined && options.iv.byteLength !== AES_GCM.IV_BYTES) {
@@ -12,6 +16,11 @@ export async function encrypt(plaintext, key, options = {}) {
     }
     const provider = options.provider ?? getDefaultCryptoProvider();
     assertProviderCapability(provider, "encryption", CryptoOperation.ENCRYPT);
+    if (options.iv !== undefined &&
+        key instanceof Uint8Array &&
+        options.unsafeAllowIvReuse !== true) {
+        assertIvNotReused(key, options.iv);
+    }
     const encrypted = await provider.encrypt({
         key,
         plaintext,
@@ -51,4 +60,3 @@ export async function decrypt(ciphertext, key, iv, authTag, aad, provider = getD
         associatedData: aad,
     });
 }
-//# sourceMappingURL=cryptoCipher.core.js.map

package/dist/cryptoCipher/cryptoCipher.envelope.d.ts

@@ -18,4 +18,3 @@ export declare function encryptEnvelope(plaintext: Uint8Array, key: Uint8Array,
  * authentication both surface as `CryptoError` with code `ERR_CRYPTO_CIPHER`.
  */
 export declare function decryptEnvelope(envelope: string, key: Uint8Array, aad?: Uint8Array, provider?: CryptoProvider): Promise<Uint8Array>;
-//# sourceMappingURL=cryptoCipher.envelope.d.ts.map

package/dist/cryptoCipher/cryptoCipher.envelope.js

@@ -66,4 +66,3 @@ function decodeField(value, name) {
 function envelopeError(message, cause) {
     return cipherError(message, CryptoOperation.DECRYPT, "aes-256-gcm", cause);
 }
-//# sourceMappingURL=cryptoCipher.envelope.js.map

package/dist/cryptoCipher/cryptoCipher.nonceGuard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Upper bound on remembered (key, iv) pairs. Past it the oldest entries
+ * are forgotten first, so the guard is best-effort for very long-lived
+ * processes but exact for the reuse patterns that occur in practice
+ * (a fixed iv hard-coded next to a fixed key).
+ */
+export declare const IV_REUSE_GUARD_CAPACITY = 65536;
+/**
+ * Rejects a caller-supplied AES-GCM iv that this process has already used
+ * under the same key.
+ *
+ * AES-GCM is catastrophically broken by nonce reuse: two messages encrypted
+ * under one (key, iv) pair leak the XOR of their plaintexts and allow the
+ * authentication key to be recovered. A random iv drawn per call (the
+ * default when `iv` is omitted) never trips this guard; it exists to catch
+ * the hard-coded or counter-reset iv before it reaches the cipher.
+ *
+ * The guard is per process: it cannot see ivs used by other processes or
+ * before a restart, so it is a safety net, not a substitute for a scheme
+ * that guarantees uniqueness (random ivs, or a durable counter).
+ *
+ * @throws {CryptoError} `CRYPTO_CIPHER` when the pair was already used.
+ */
+export declare function assertIvNotReused(key: Uint8Array, iv: Uint8Array): void;

package/dist/cryptoCipher/cryptoCipher.nonceGuard.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { CryptoOperation } from "@zudojs/errors";
+import { cipherError } from "../cryptoErrors/cryptoErrors.helper.js";
+/**
+ * Upper bound on remembered (key, iv) pairs. Past it the oldest entries
+ * are forgotten first, so the guard is best-effort for very long-lived
+ * processes but exact for the reuse patterns that occur in practice
+ * (a fixed iv hard-coded next to a fixed key).
+ */
+export const IV_REUSE_GUARD_CAPACITY = 65_536;
+const seen = new Set();
+function fingerprint(key, iv) {
+    return createHash("sha256")
+        .update("zudojs-crypto-iv-reuse-guard-v1")
+        .update(Uint8Array.from([key.byteLength]))
+        .update(key)
+        .update(iv)
+        .digest("base64url");
+}
+/**
+ * Rejects a caller-supplied AES-GCM iv that this process has already used
+ * under the same key.
+ *
+ * AES-GCM is catastrophically broken by nonce reuse: two messages encrypted
+ * under one (key, iv) pair leak the XOR of their plaintexts and allow the
+ * authentication key to be recovered. A random iv drawn per call (the
+ * default when `iv` is omitted) never trips this guard; it exists to catch
+ * the hard-coded or counter-reset iv before it reaches the cipher.
+ *
+ * The guard is per process: it cannot see ivs used by other processes or
+ * before a restart, so it is a safety net, not a substitute for a scheme
+ * that guarantees uniqueness (random ivs, or a durable counter).
+ *
+ * @throws {CryptoError} `CRYPTO_CIPHER` when the pair was already used.
+ */
+export function assertIvNotReused(key, iv) {
+    const entry = fingerprint(key, iv);
+    if (seen.has(entry)) {
+        throw cipherError("AES-256-GCM iv has already been used with this key in this process; " +
+            "reusing a GCM nonce under one key breaks confidentiality and " +
+            "authenticity. Omit `iv` to draw a fresh random one per call.", CryptoOperation.ENCRYPT, "aes-256-gcm");
+    }
+    if (seen.size >= IV_REUSE_GUARD_CAPACITY) {
+        const oldest = seen.values().next();
+        if (!oldest.done) {
+            seen.delete(oldest.value);
+        }
+    }
+    seen.add(entry);
+}

package/dist/cryptoCipher/cryptoCipher.string.d.ts

@@ -8,4 +8,3 @@ export declare function encryptString(plaintext: string, key: Uint8Array, option
  * Decrypts AES-256-GCM ciphertext into a UTF-8 string.
  */
 export declare function decryptString(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array, provider?: CryptoProvider): Promise<string>;
-//# sourceMappingURL=cryptoCipher.string.d.ts.map

package/dist/cryptoCipher/cryptoCipher.string.js

@@ -12,4 +12,3 @@ export async function decryptString(ciphertext, key, iv, authTag, aad, provider)
     const plaintext = await decrypt(ciphertext, key, iv, authTag, aad, provider);
     return Buffer.from(plaintext).toString("utf8");
 }
-//# sourceMappingURL=cryptoCipher.string.js.map

package/dist/cryptoCipher/index.d.ts

@@ -4,6 +4,6 @@
  * Symmetric and asymmetric encryption operations.
  */
 export * from "./cryptoCipher.core.js";
+export * from "./cryptoCipher.nonceGuard.js";
 export * from "./cryptoCipher.string.js";
 export * from "./cryptoCipher.envelope.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoCipher/index.js

@@ -4,6 +4,6 @@
  * Symmetric and asymmetric encryption operations.
  */
 export * from "./cryptoCipher.core.js";
+export * from "./cryptoCipher.nonceGuard.js";
 export * from "./cryptoCipher.string.js";
 export * from "./cryptoCipher.envelope.js";
-//# sourceMappingURL=index.js.map

package/dist/cryptoConstants/cryptoConstants.config.d.ts

@@ -33,4 +33,3 @@ export declare function getDefaultPasswordHashConfig(): {
     readonly pbkdf2Iterations: number;
     readonly pbkdf2Digest: string;
 };
-//# sourceMappingURL=cryptoConstants.config.d.ts.map

package/dist/cryptoConstants/cryptoConstants.config.js

@@ -26,4 +26,3 @@ export function getDefaultPasswordHashConfig() {
         pbkdf2Digest: PASSWORD_HASH.PBKDF2.DIGEST,
     };
 }
-//# sourceMappingURL=cryptoConstants.config.js.map

package/dist/cryptoConstants/cryptoConstants.guard.d.ts

@@ -34,4 +34,3 @@ export declare function isCryptoAlgorithm(value: unknown): value is CryptoAlgori
  * Throws when the value is not a supported algorithm.
  */
 export declare function parseCryptoAlgorithm(value: string): CryptoAlgorithm;
-//# sourceMappingURL=cryptoConstants.guard.d.ts.map

package/dist/cryptoConstants/cryptoConstants.guard.js

@@ -57,4 +57,3 @@ export function parseCryptoAlgorithm(value) {
     }
     throw new TypeError(`Unsupported cryptographic algorithm: "${value}".`);
 }
-//# sourceMappingURL=cryptoConstants.guard.js.map

package/dist/cryptoConstants/cryptoConstants.security.d.ts

@@ -91,4 +91,3 @@ export declare const TOKEN_TTL: Readonly<{
     readonly SESSION_MS: number;
     readonly REFRESH_TOKEN_MS: number;
 }>;
-//# sourceMappingURL=cryptoConstants.security.d.ts.map

package/dist/cryptoConstants/cryptoConstants.security.js

@@ -92,4 +92,3 @@ export const TOKEN_TTL = Object.freeze({
     SESSION_MS: 24 * TimeMs.HOUR,
     REFRESH_TOKEN_MS: 30 * 24 * TimeMs.HOUR,
 });
-//# sourceMappingURL=cryptoConstants.security.js.map

package/dist/cryptoConstants/cryptoConstants.token.d.ts

@@ -46,4 +46,3 @@ export declare const CRYPTO_VERSION: Readonly<{
     readonly ENCRYPTION_ENVELOPE: "v1";
     readonly TOKEN: "v1";
 }>;
-//# sourceMappingURL=cryptoConstants.token.d.ts.map

package/dist/cryptoConstants/cryptoConstants.token.js

@@ -46,4 +46,3 @@ export const CRYPTO_VERSION = Object.freeze({
     ENCRYPTION_ENVELOPE: "v1",
     TOKEN: "v1",
 });
-//# sourceMappingURL=cryptoConstants.token.js.map

package/dist/cryptoConstants/cryptoConstants.type.d.ts

@@ -114,4 +114,3 @@ export declare const CRYPTO_ALGORITHM: Readonly<{
     readonly SCRYPT: "scrypt";
     readonly ED25519: "ed25519";
 }>;
-//# sourceMappingURL=cryptoConstants.type.d.ts.map

package/dist/cryptoConstants/cryptoConstants.type.js

@@ -135,4 +135,3 @@ export const CRYPTO_ALGORITHM = Object.freeze({
     SCRYPT: "scrypt",
     ED25519: "ed25519",
 });
-//# sourceMappingURL=cryptoConstants.type.js.map

package/dist/cryptoConstants/index.d.ts

@@ -8,4 +8,3 @@ export * from "./cryptoConstants.config.js";
 export * from "./cryptoConstants.security.js";
 export * from "./cryptoConstants.token.js";
 export * from "./cryptoConstants.guard.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoConstants/index.js

@@ -8,4 +8,3 @@ export * from "./cryptoConstants.config.js";
 export * from "./cryptoConstants.security.js";
 export * from "./cryptoConstants.token.js";
 export * from "./cryptoConstants.guard.js";
-//# sourceMappingURL=index.js.map

package/dist/cryptoEncoding/cryptoEncoding.arrayBuffer.d.ts

@@ -6,4 +6,3 @@ export declare function arrayBufferToBytes(value: ArrayBuffer): Uint8Array;
  * Converts bytes into an ArrayBuffer copy.
  */
 export declare function bytesToArrayBuffer(value: Uint8Array): ArrayBuffer;
-//# sourceMappingURL=cryptoEncoding.arrayBuffer.d.ts.map

package/dist/cryptoEncoding/cryptoEncoding.arrayBuffer.js

@@ -16,4 +16,3 @@ export function bytesToArrayBuffer(value) {
     }
     return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
 }
-//# sourceMappingURL=cryptoEncoding.arrayBuffer.js.map

package/dist/cryptoEncoding/cryptoEncoding.compare.d.ts

@@ -8,4 +8,3 @@ import type { CryptoEncoding } from "./cryptoEncoding.core.js";
  * through a non-canonical form.
  */
 export declare function timingSafeEqualEncoded(left: string, right: string, encoding?: CryptoEncoding): boolean;
-//# sourceMappingURL=cryptoEncoding.compare.d.ts.map

package/dist/cryptoEncoding/cryptoEncoding.compare.js

@@ -20,4 +20,3 @@ export function timingSafeEqualEncoded(left, right, encoding = "base64url") {
     }
     return timingSafeEqual(leftBytes, rightBytes);
 }
-//# sourceMappingURL=cryptoEncoding.compare.js.map

package/dist/cryptoEncoding/cryptoEncoding.core.d.ts

@@ -40,4 +40,3 @@ export declare function utf8Encode(value: string): Uint8Array;
  * Throws when the bytes are not well-formed UTF-8.
  */
 export declare function utf8Decode(value: Uint8Array): string;
-//# sourceMappingURL=cryptoEncoding.core.d.ts.map

package/dist/cryptoEncoding/cryptoEncoding.core.js

@@ -98,4 +98,3 @@ function assertBytes(value) {
         throw new TypeError("Value must be a Uint8Array.");
     }
 }
-//# sourceMappingURL=cryptoEncoding.core.js.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.base64.d.ts

@@ -18,4 +18,3 @@ export declare function fromBase64(value: string): Uint8Array;
  * The empty string is valid (it encodes zero bytes).
  */
 export declare function isBase64(value: string): boolean;
-//# sourceMappingURL=cryptoEncoding.base64.d.ts.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.base64.js

@@ -40,4 +40,3 @@ function assertBytes(value) {
         throw new TypeError("Value must be a Uint8Array.");
     }
 }
-//# sourceMappingURL=cryptoEncoding.base64.js.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.base64url.d.ts

@@ -18,4 +18,3 @@ export declare function fromBase64Url(value: string): Uint8Array;
  * The empty string is valid (it encodes zero bytes).
  */
 export declare function isBase64Url(value: string): boolean;
-//# sourceMappingURL=cryptoEncoding.base64url.d.ts.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.base64url.js

@@ -40,4 +40,3 @@ function assertBytes(value) {
         throw new TypeError("Value must be a Uint8Array.");
     }
 }
-//# sourceMappingURL=cryptoEncoding.base64url.js.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.hex.d.ts

@@ -17,4 +17,3 @@ export declare function fromHex(value: string): Uint8Array;
  * The empty string is valid (it encodes zero bytes).
  */
 export declare function isHex(value: string): boolean;
-//# sourceMappingURL=cryptoEncoding.hex.d.ts.map

package/dist/cryptoEncoding/encoding/cryptoEncoding.hex.js

@@ -34,4 +34,3 @@ function assertBytes(value) {
         throw new TypeError("Value must be a Uint8Array.");
     }
 }
-//# sourceMappingURL=cryptoEncoding.hex.js.map

package/dist/cryptoEncoding/encoding/index.d.ts

@@ -6,4 +6,3 @@
 export * from "./cryptoEncoding.hex.js";
 export * from "./cryptoEncoding.base64.js";
 export * from "./cryptoEncoding.base64url.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoEncoding/encoding/index.js

@@ -6,4 +6,3 @@
 export * from "./cryptoEncoding.hex.js";
 export * from "./cryptoEncoding.base64.js";
 export * from "./cryptoEncoding.base64url.js";
-//# sourceMappingURL=index.js.map

package/dist/cryptoEncoding/index.d.ts

@@ -9,4 +9,3 @@ export * from "./encoding/cryptoEncoding.base64.js";
 export * from "./encoding/cryptoEncoding.base64url.js";
 export * from "./cryptoEncoding.compare.js";
 export * from "./cryptoEncoding.arrayBuffer.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoEncoding/index.js

@@ -9,4 +9,3 @@ export * from "./encoding/cryptoEncoding.base64.js";
 export * from "./encoding/cryptoEncoding.base64url.js";
 export * from "./cryptoEncoding.compare.js";
 export * from "./cryptoEncoding.arrayBuffer.js";
-//# sourceMappingURL=index.js.map

package/dist/cryptoErrors/cryptoErrors.helper.d.ts

@@ -19,6 +19,19 @@ export declare function keyDerivationError(message: string, algorithm: string |
  * Builds a key error that preserves the underlying failure as `cause`.
  */
 export declare function keyError(message: string, operation: CryptoOperation.KEY_GENERATION | CryptoOperation.KEY_IMPORT | CryptoOperation.KEY_EXPORT, algorithm: string | undefined, cause?: unknown): CryptoError;
+/**
+ * Builds a password hashing error (`CRYPTO_HASH`, operation `HASH`).
+ *
+ * Pass `userFacing: true` for a rejection the end user caused and can act
+ * on, such as a password outside the length policy: the error then carries
+ * `statusCode: 400` and `expose: true` so an HTTP layer answers with the
+ * message instead of a generic 500. Parameter violations by the caller
+ * (a weak scrypt cost) keep the 500 default.
+ */
+export declare function passwordHashError(message: string, options?: {
+    readonly userFacing?: boolean;
+    readonly cause?: unknown;
+}): CryptoError;
 /**
  * Builds a generic crypto error for an operation, preserving `cause`.
  */
@@ -27,4 +40,3 @@ export declare function operationError(message: string, operation: CryptoOperati
  * Re-throws CryptoErrors unchanged and wraps anything else.
  */
 export declare function rethrowAsCryptoError(error: unknown, wrap: (cause: unknown) => CryptoError): never;
-//# sourceMappingURL=cryptoErrors.helper.d.ts.map

package/dist/cryptoErrors/cryptoErrors.helper.js

@@ -54,6 +54,24 @@ export function keyError(message, operation, algorithm, cause) {
         cause,
     });
 }
+/**
+ * Builds a password hashing error (`CRYPTO_HASH`, operation `HASH`).
+ *
+ * Pass `userFacing: true` for a rejection the end user caused and can act
+ * on, such as a password outside the length policy: the error then carries
+ * `statusCode: 400` and `expose: true` so an HTTP layer answers with the
+ * message instead of a generic 500. Parameter violations by the caller
+ * (a weak scrypt cost) keep the 500 default.
+ */
+export function passwordHashError(message, options = {}) {
+    return new CryptoError(message, {
+        code: ErrorCode.CRYPTO_HASH,
+        operation: CryptoOperation.HASH,
+        algorithm: "scrypt",
+        cause: options.cause,
+        ...(options.userFacing ? { statusCode: 400, expose: true } : {}),
+    });
+}
 /**
  * Builds a generic crypto error for an operation, preserving `cause`.
  */
@@ -69,4 +87,3 @@ export function rethrowAsCryptoError(error, wrap) {
     }
     throw wrap(error);
 }
-//# sourceMappingURL=cryptoErrors.helper.js.map

package/dist/cryptoErrors/index.d.ts

@@ -8,4 +8,3 @@
  */
 export { CryptoError, CryptoOperation, createCryptoError, isCryptoError, cryptoHashError, cryptoCipherError, cryptoSignatureError, cryptoKeyDerivationError, cryptoKeyError, } from "@zudojs/errors";
 export type { CryptoErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoErrors/index.js

@@ -7,4 +7,3 @@
  * error hierarchy across the framework.
  */
 export { CryptoError, CryptoOperation, createCryptoError, isCryptoError, cryptoHashError, cryptoCipherError, cryptoSignatureError, cryptoKeyDerivationError, cryptoKeyError, } from "@zudojs/errors";
-//# sourceMappingURL=index.js.map

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

@@ -88,4 +88,3 @@ export declare const cryptoFactory: CryptoFactory;
  * Returns the default application crypto factory.
  */
 export declare function getCryptoFactory(): CryptoFactory;
-//# sourceMappingURL=cryptoFactory.core.d.ts.map

package/dist/cryptoFactory/cryptoFactory.core.js

@@ -128,4 +128,3 @@ export const cryptoFactory = createCryptoFactory();
 export function getCryptoFactory() {
     return cryptoFactory;
 }
-//# sourceMappingURL=cryptoFactory.core.js.map

package/dist/cryptoFactory/cryptoFactory.encoding.d.ts

@@ -2,4 +2,3 @@ import type { CryptoEncoding } from "../cryptoEncoding/cryptoEncoding.core.js";
 export type { CryptoEncoding };
 export declare function factoryEncode(value: Uint8Array, encoding?: CryptoEncoding): string;
 export declare function factoryDecode(value: string, encoding?: CryptoEncoding): Uint8Array;
-//# sourceMappingURL=cryptoFactory.encoding.d.ts.map

package/dist/cryptoFactory/cryptoFactory.encoding.js

@@ -5,4 +5,3 @@ export function factoryEncode(value, encoding = "base64url") {
 export function factoryDecode(value, encoding = "base64url") {
     return decode(value, encoding);
 }
-//# sourceMappingURL=cryptoFactory.encoding.js.map

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

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

package/dist/cryptoFactory/cryptoFactory.password.js

@@ -5,4 +5,3 @@ export async function factoryCreatePasswordHash(password, options, provider) {
 export async function factoryVerifyPassword(password, encodedHash, provider) {
     return verifyPassword(password, encodedHash, provider);
 }
-//# sourceMappingURL=cryptoFactory.password.js.map

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

@@ -8,4 +8,3 @@ export declare function factoryCreateVerificationToken(provider?: CryptoProvider
 export declare function factoryCreatePasswordResetToken(provider?: CryptoProvider): Promise<string>;
 export declare function factoryCreateCsrfToken(provider?: CryptoProvider): Promise<string>;
 export declare function factoryCreateOtp(digits?: number, provider?: CryptoProvider): Promise<string>;
-//# sourceMappingURL=cryptoFactory.token.d.ts.map

package/dist/cryptoFactory/cryptoFactory.token.js

@@ -28,4 +28,3 @@ export async function factoryCreateCsrfToken(provider) {
 export async function factoryCreateOtp(digits = 6, provider) {
     return generateOtp(digits, provider);
 }
-//# sourceMappingURL=cryptoFactory.token.js.map

package/dist/cryptoFactory/index.d.ts

@@ -4,4 +4,3 @@
  * Factory functions for crypto primitives.
  */
 export * from "./cryptoFactory.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cryptoFactory/index.js

@@ -4,4 +4,3 @@
  * Factory functions for crypto primitives.
  */
 export * from "./cryptoFactory.core.js";
-//# sourceMappingURL=index.js.map

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

@@ -9,4 +9,3 @@ export declare function encodeDigest(digest: Uint8Array, encoding: HashEncoding)
  * Input must be a non-empty, canonical encoding.
  */
 export declare function decodeDigest(digest: string, encoding?: HashEncoding): Uint8Array;
-//# sourceMappingURL=cryptoHash.codec.d.ts.map

package/dist/cryptoHash/cryptoHash.codec.js

@@ -36,4 +36,3 @@ export function decodeDigest(digest, encoding = "hex") {
             throw new TypeError(`Unsupported hash encoding: ${String(encoding)}.`);
     }
 }
-//# sourceMappingURL=cryptoHash.codec.js.map

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

@@ -4,4 +4,3 @@
  * Alias of `timingSafeEqual` kept for API compatibility.
  */
 export declare function equalDigests(left: Uint8Array, right: Uint8Array): boolean;
-//# sourceMappingURL=cryptoHash.compare.d.ts.map

package/dist/cryptoHash/cryptoHash.compare.js

@@ -7,4 +7,3 @@ import { timingSafeEqual } from "../compare/compare.helper.js";
 export function equalDigests(left, right) {
     return timingSafeEqual(left, right);
 }
-//# sourceMappingURL=cryptoHash.compare.js.map

package/dist/cryptoHash/cryptoHash.convenience.d.ts

@@ -23,4 +23,3 @@ export declare function sha3_384(input: HashInput, encoding?: HashEncoding): Pro
  * Calculates a SHA3-512 digest.
  */
 export declare function sha3_512(input: HashInput, encoding?: HashEncoding): Promise<string>;
-//# sourceMappingURL=cryptoHash.convenience.d.ts.map

package/dist/cryptoHash/cryptoHash.convenience.js

@@ -53,4 +53,3 @@ export async function sha3_512(input, encoding = "hex") {
         encoding,
     })).encoded;
 }
-//# sourceMappingURL=cryptoHash.convenience.js.map

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

@@ -20,4 +20,3 @@ export interface HashOptions {
  * or sha1 are rejected at runtime even when passed as plain strings.
  */
 export declare function hash(input: HashInput, options?: HashOptions): Promise<HashResult>;
-//# sourceMappingURL=cryptoHash.core.d.ts.map

package/dist/cryptoHash/cryptoHash.core.js

@@ -23,4 +23,3 @@ export async function hash(input, options = {}) {
         encoded: encodeDigest(digest, encoding),
     });
 }
-//# sourceMappingURL=cryptoHash.core.js.map