@zudojs/crypto 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/crypto
 
-Cryptographic primitives for hashing, encryption, tokens, and secure random generation.
+Cryptographic primitives for hashing, authenticated encryption, password hashing, digital signatures, key derivation, opaque tokens, and secure random generation. Everything is backed by `node:crypto` through a swappable provider.
 
 ## Installation
 
@@ -11,25 +11,54 @@ npm install @zudojs/crypto
 ## Quick Start
 
 ```typescript
-import { hash, encrypt, decrypt, randomBytes } from "@zudojs/crypto";
+import {
+  randomBytesSecure,
+  hash,
+  hashPassword,
+  verifyPassword,
+  encryptEnvelope,
+  decryptEnvelope,
+  generateToken,
+} from "@zudojs/crypto";
 
-const hashed = await hash("password", "salt");
-const token = randomBytes(32);
-const encrypted = await encrypt("secret", key);
-const decrypted = await decrypt(encrypted, key);
+// Hashing (SHA-2 / SHA-3 only; md5 and sha1 are rejected)
+const digest = await hash("hello", { algorithm: "sha256", encoding: "hex" });
+console.log(digest.encoded);
+
+// Password hashing (scrypt, self-describing "v1$scrypt$..." string)
+const stored = await hashPassword("correct horse battery staple");
+const ok = await verifyPassword("correct horse battery staple", stored.encoded);
+
+// Authenticated encryption (AES-256-GCM, 12-byte IV, 16-byte tag)
+const key = await randomBytesSecure(32);
+const envelope = await encryptEnvelope(new TextEncoder().encode("secret"), key);
+const plaintext = await decryptEnvelope(envelope, key);
+
+// Opaque tokens
+const sessionToken = await generateToken({ bytes: 32, prefix: "sess_" });
 ```
 
 ## Features
 
-- Hashing (SHA-256, SHA-512, bcrypt, argon2)
-- Symmetric encryption (AES-GCM)
-- Secure random generation
-- Token generation
-- Key derivation functions
+- 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, OWASP parameters) and PBKDF2-HMAC (provider level), versioned self-describing encoding, bounded parameters on verification
+- Key derivation: PBKDF2 (sha256/384/512, 600 000 iterations by default) and scrypt (cost, block size, parallelization, memory bound)
+- 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
+- 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
+
+Not implemented (and not advertised by the types): bcrypt, Argon2, ChaCha20-Poly1305, AES-CBC, X25519.
+
+## 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.
 
 ## Use Cases
 
-- Password hashing
-- API token generation
+- Password storage and login verification
+- API token generation and storage
 - Data encryption at rest
-- Secure random values
+- Secure random values and one-time codes

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

@@ -1,8 +1,16 @@
 /**
  * Performs a constant-time comparison of two byte arrays.
  *
- * Returns false immediately if the lengths differ.
- * Uses XOR accumulation to avoid timing side-channels.
+ * Returns false immediately if the lengths differ. This leaks only the
+ * fact that the lengths differ, which is acceptable for fixed-size
+ * values such as digests, MACs and tokens; do not rely on this function
+ * to hide the length of variable-length secrets.
+ *
+ * The byte-wise comparison is delegated to `node:crypto.timingSafeEqual`.
  */
 export declare function timingSafeEqual(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * 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

@@ -1,17 +1,33 @@
+import { timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
 /**
  * Performs a constant-time comparison of two byte arrays.
  *
- * Returns false immediately if the lengths differ.
- * Uses XOR accumulation to avoid timing side-channels.
+ * Returns false immediately if the lengths differ. This leaks only the
+ * fact that the lengths differ, which is acceptable for fixed-size
+ * values such as digests, MACs and tokens; do not rely on this function
+ * to hide the length of variable-length secrets.
+ *
+ * The byte-wise comparison is delegated to `node:crypto.timingSafeEqual`.
  */
 export function timingSafeEqual(left, right) {
+    if (!(left instanceof Uint8Array) || !(right instanceof Uint8Array)) {
+        throw new TypeError("timingSafeEqual arguments must be Uint8Array.");
+    }
     if (left.byteLength !== right.byteLength) {
         return false;
     }
-    let difference = 0;
-    for (let index = 0; index < left.byteLength; index += 1) {
-        difference |= left[index] ^ right[index];
+    if (left.byteLength === 0) {
+        return true;
+    }
+    return nodeTimingSafeEqual(left, right);
+}
+/**
+ * Performs a constant-time comparison of two strings by their UTF-8 bytes.
+ */
+export function timingSafeEqualString(left, right) {
+    if (typeof left !== "string" || typeof right !== "string") {
+        return false;
     }
-    return difference === 0;
+    return timingSafeEqual(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
 }
 //# sourceMappingURL=compare.helper.js.map

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

@@ -1,9 +1,16 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 /**
  * Options used when encrypting data.
+ *
+ * `iv`, when supplied, must be exactly 12 bytes and MUST be unique per
+ * 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.
  */
 export interface CipherOptions {
     readonly iv?: Uint8Array;
     readonly aad?: Uint8Array;
+    readonly provider?: CryptoProvider;
 }
 /**
  * Authenticated encryption result.
@@ -20,6 +27,9 @@ export interface CipherResult {
 export declare function encrypt(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions): Promise<CipherResult>;
 /**
  * Decrypts AES-256-GCM ciphertext.
+ *
+ * The IV must be 12 bytes and the authentication tag 16 bytes; truncated
+ * tags are rejected before the cipher is touched.
  */
-export declare function decrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+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

@@ -1,9 +1,15 @@
-import { createNodeCryptoProvider } from "../node/index.js";
-const provider = createNodeCryptoProvider();
+import { getDefaultCryptoProvider } from "../cryptoProvider/cryptoProvider.default.js";
+import { AES_GCM } from "../cryptoConstants/cryptoConstants.type.js";
+import { CryptoOperation } from "@zudojs/errors";
+import { cipherError } from "../cryptoErrors/cryptoErrors.helper.js";
 /**
  * Encrypts data using AES-256-GCM.
  */
 export async function encrypt(plaintext, key, options = {}) {
+    if (options.iv !== undefined && options.iv.byteLength !== AES_GCM.IV_BYTES) {
+        throw cipherError(`AES-256-GCM iv must be ${AES_GCM.IV_BYTES} bytes.`, CryptoOperation.ENCRYPT, "aes-256-gcm");
+    }
+    const provider = options.provider ?? getDefaultCryptoProvider();
     const encrypted = await provider.encrypt({
         key,
         plaintext,
@@ -19,8 +25,18 @@ export async function encrypt(plaintext, key, options = {}) {
 }
 /**
  * Decrypts AES-256-GCM ciphertext.
+ *
+ * The IV must be 12 bytes and the authentication tag 16 bytes; truncated
+ * tags are rejected before the cipher is touched.
  */
-export async function decrypt(ciphertext, key, iv, authTag, aad) {
+export async function decrypt(ciphertext, key, iv, authTag, aad, provider = getDefaultCryptoProvider()) {
+    if (!(iv instanceof Uint8Array) || iv.byteLength !== AES_GCM.IV_BYTES) {
+        throw cipherError(`AES-256-GCM iv must be ${AES_GCM.IV_BYTES} bytes.`, CryptoOperation.DECRYPT, "aes-256-gcm");
+    }
+    if (!(authTag instanceof Uint8Array) ||
+        authTag.byteLength !== AES_GCM.AUTH_TAG_BYTES) {
+        throw cipherError(`AES-256-GCM authentication tag must be ${AES_GCM.AUTH_TAG_BYTES} bytes.`, CryptoOperation.DECRYPT, "aes-256-gcm");
+    }
     return provider.decrypt({
         key,
         encrypted: {

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

@@ -1,3 +1,4 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { CipherOptions } from "./cryptoCipher.core.js";
 /**
  * Creates an encrypted envelope suitable for storage or transport.
@@ -6,11 +7,15 @@ import type { CipherOptions } from "./cryptoCipher.core.js";
  *
  * version.algorithm.iv.authTag.ciphertext
  *
- * All binary fields are Base64URL encoded.
+ * All binary fields are canonical Base64URL encoded.
  */
 export declare function encryptEnvelope(plaintext: Uint8Array, key: Uint8Array, options?: CipherOptions): Promise<string>;
 /**
  * Decrypts an encrypted envelope.
+ *
+ * Every field is validated (version, algorithm, canonical Base64URL, IV and
+ * tag lengths) before the cipher is invoked; malformed envelopes and failed
+ * authentication both surface as `CryptoError` with code `ERR_CRYPTO_CIPHER`.
  */
-export declare function decryptEnvelope(envelope: string, key: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>;
+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

@@ -1,4 +1,8 @@
 import { encrypt, decrypt } from "./cryptoCipher.core.js";
+import { AES_GCM } from "../cryptoConstants/cryptoConstants.type.js";
+import { fromBase64Url } from "../cryptoEncoding/encoding/cryptoEncoding.base64url.js";
+import { CryptoOperation } from "@zudojs/errors";
+import { cipherError } from "../cryptoErrors/cryptoErrors.helper.js";
 /**
  * Creates an encrypted envelope suitable for storage or transport.
  *
@@ -6,7 +10,7 @@ import { encrypt, decrypt } from "./cryptoCipher.core.js";
  *
  * version.algorithm.iv.authTag.ciphertext
  *
- * All binary fields are Base64URL encoded.
+ * All binary fields are canonical Base64URL encoded.
  */
 export async function encryptEnvelope(plaintext, key, options = {}) {
     const result = await encrypt(plaintext, key, options);
@@ -20,31 +24,46 @@ export async function encryptEnvelope(plaintext, key, options = {}) {
 }
 /**
  * Decrypts an encrypted envelope.
+ *
+ * Every field is validated (version, algorithm, canonical Base64URL, IV and
+ * tag lengths) before the cipher is invoked; malformed envelopes and failed
+ * authentication both surface as `CryptoError` with code `ERR_CRYPTO_CIPHER`.
  */
-export async function decryptEnvelope(envelope, key, aad) {
+export async function decryptEnvelope(envelope, key, aad, provider) {
     if (typeof envelope !== "string") {
-        throw new TypeError("Encrypted envelope must be a string.");
+        throw envelopeError("Encrypted envelope must be a string.");
     }
     const parts = envelope.split(".");
     if (parts.length !== 5) {
-        throw new TypeError("Invalid encrypted envelope.");
+        throw envelopeError("Invalid encrypted envelope.");
     }
     const [version, algorithm, encodedIv, encodedAuthTag, encodedCiphertext] = parts;
     if (version !== "v1") {
-        throw new TypeError(`Unsupported encrypted envelope version: ${version}.`);
+        throw envelopeError(`Unsupported encrypted envelope version: ${version}.`);
     }
     if (algorithm !== "aes-256-gcm") {
-        throw new TypeError(`Unsupported envelope algorithm: ${algorithm}.`);
+        throw envelopeError(`Unsupported envelope algorithm: ${algorithm}.`);
+    }
+    const iv = decodeField(encodedIv, "iv");
+    const authTag = decodeField(encodedAuthTag, "authentication tag");
+    const ciphertext = decodeField(encodedCiphertext, "ciphertext");
+    if (iv.byteLength !== AES_GCM.IV_BYTES) {
+        throw envelopeError(`Encrypted envelope iv must be ${AES_GCM.IV_BYTES} bytes.`);
+    }
+    if (authTag.byteLength !== AES_GCM.AUTH_TAG_BYTES) {
+        throw envelopeError(`Encrypted envelope authentication tag must be ${AES_GCM.AUTH_TAG_BYTES} bytes.`);
     }
-    const iv = decodeBase64Url(encodedIv);
-    const authTag = decodeBase64Url(encodedAuthTag);
-    const ciphertext = decodeBase64Url(encodedCiphertext);
-    return decrypt(ciphertext, key, iv, authTag, aad);
+    return decrypt(ciphertext, key, iv, authTag, aad, provider);
 }
-function decodeBase64Url(value) {
-    if (!/^[A-Za-z0-9_-]*$/.test(value)) {
-        throw new TypeError("Invalid Base64URL value.");
+function decodeField(value, name) {
+    try {
+        return fromBase64Url(value);
     }
-    return new Uint8Array(Buffer.from(value, "base64url"));
+    catch (error) {
+        throw envelopeError(`Invalid encrypted envelope ${name}.`, error);
+    }
+}
+function envelopeError(message, cause) {
+    return cipherError(message, CryptoOperation.DECRYPT, "aes-256-gcm", cause);
 }
 //# sourceMappingURL=cryptoCipher.envelope.js.map

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

@@ -1,3 +1,4 @@
+import type { CryptoProvider } from "../cryptoProvider/index.js";
 import type { CipherOptions, CipherResult } from "./cryptoCipher.core.js";
 /**
  * Encrypts a UTF-8 string using AES-256-GCM.
@@ -6,5 +7,5 @@ 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): Promise<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

@@ -8,8 +8,8 @@ export async function encryptString(plaintext, key, options = {}) {
 /**
  * Decrypts AES-256-GCM ciphertext into a UTF-8 string.
  */
-export async function decryptString(ciphertext, key, iv, authTag, aad) {
-    const plaintext = await decrypt(ciphertext, key, iv, authTag, aad);
+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/cryptoConstants/cryptoConstants.guard.d.ts

@@ -15,6 +15,15 @@ export declare function isKeyDerivationAlgorithm(algorithm: CryptoAlgorithm): bo
  * Returns true when an algorithm is a message authentication algorithm.
  */
 export declare function isMacAlgorithm(algorithm: CryptoAlgorithm): boolean;
+/**
+ * Returns true when an algorithm is a digital signature algorithm.
+ */
+export declare function isSignatureAlgorithm(algorithm: CryptoAlgorithm): boolean;
+/**
+ * Returns true when an algorithm is a symmetric key algorithm
+ * (encryption, MAC or key derivation output).
+ */
+export declare function isSymmetricKeyAlgorithm(algorithm: CryptoAlgorithm): boolean;
 /**
  * Returns true when the supplied value is a supported algorithm.
  */

package/dist/cryptoConstants/cryptoConstants.guard.js

@@ -1,4 +1,4 @@
-import { CryptoAlgorithm, AEAD_ALGORITHMS, HASH_ALGORITHMS, KEY_DERIVATION_ALGORITHMS, MAC_ALGORITHMS, } from "./cryptoConstants.type.js";
+import { CryptoAlgorithm, AEAD_ALGORITHMS, HASH_ALGORITHMS, KEY_DERIVATION_ALGORITHMS, MAC_ALGORITHMS, SIGNATURE_ALGORITHMS, } from "./cryptoConstants.type.js";
 /**
  * Returns true when an algorithm provides authenticated encryption.
  */
@@ -23,6 +23,21 @@ export function isKeyDerivationAlgorithm(algorithm) {
 export function isMacAlgorithm(algorithm) {
     return MAC_ALGORITHMS.includes(algorithm);
 }
+/**
+ * Returns true when an algorithm is a digital signature algorithm.
+ */
+export function isSignatureAlgorithm(algorithm) {
+    return SIGNATURE_ALGORITHMS.includes(algorithm);
+}
+/**
+ * Returns true when an algorithm is a symmetric key algorithm
+ * (encryption, MAC or key derivation output).
+ */
+export function isSymmetricKeyAlgorithm(algorithm) {
+    return (isAeadAlgorithm(algorithm) ||
+        isMacAlgorithm(algorithm) ||
+        isKeyDerivationAlgorithm(algorithm));
+}
 /**
  * Returns true when the supplied value is a supported algorithm.
  */

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

@@ -1,5 +1,10 @@
 /**
  * Password hashing constants.
+ *
+ * Defaults follow current OWASP Password Storage Cheat Sheet guidance:
+ * scrypt N=2^14, r=8, p=1 (minimum) and PBKDF2-HMAC-SHA256 with 600 000
+ * iterations. `LIMITS` bounds parameters that are read back from stored
+ * hashes so that a tampered or foreign record cannot force unbounded work.
  */
 export declare const PASSWORD_HASH: Readonly<{
     readonly SALT_BYTES: 16;
@@ -10,15 +15,43 @@ export declare const PASSWORD_HASH: Readonly<{
         PARALLELIZATION: 1;
     }>;
     readonly PBKDF2: Readonly<{
-        ITERATIONS: 310000;
+        ITERATIONS: 600000;
+        /**
+         * Floor for stored or caller-supplied iteration counts. Kept below the
+         * default so hashes produced by other systems with older (but still
+         * NIST-compliant) parameters remain verifiable; new hashes always use
+         * `ITERATIONS`.
+         */
+        MIN_ITERATIONS: 100000;
         DIGEST: "sha256";
     }>;
+    readonly LIMITS: Readonly<{
+        MIN_SALT_BYTES: 16;
+        MAX_SALT_BYTES: 64;
+        MIN_KEY_BYTES: 16;
+        MAX_KEY_BYTES: 64;
+        MIN_SCRYPT_COST: 2;
+        MAX_SCRYPT_COST: number;
+        MAX_SCRYPT_BLOCK_SIZE: 32;
+        MAX_SCRYPT_PARALLELIZATION: 16;
+        /**
+         * Upper bound on `128 * N * r` (the scrypt working memory in bytes) so
+         * that a stored hash cannot combine the individual maxima into a
+         * multi-gigabyte allocation.
+         */
+        MAX_SCRYPT_MEMORY_BYTES: number;
+        MAX_PBKDF2_ITERATIONS: 10000000;
+    }>;
 }>;
 /**
  * Password policy defaults.
  *
  * These values are intentionally conservative defaults.
  * Applications may impose stricter requirements.
+ *
+ * `MAX_LENGTH` is measured in UTF-16 code units and is enforced by
+ * `hashPassword`/`verifyPassword` to bound the work an unauthenticated
+ * caller can trigger.
  */
 export declare const PASSWORD_POLICY: Readonly<{
     readonly MIN_LENGTH: 8;

package/dist/cryptoConstants/cryptoConstants.security.js

@@ -1,6 +1,11 @@
 import { TimeMs } from "@zudojs/constants";
 /**
  * Password hashing constants.
+ *
+ * Defaults follow current OWASP Password Storage Cheat Sheet guidance:
+ * scrypt N=2^14, r=8, p=1 (minimum) and PBKDF2-HMAC-SHA256 with 600 000
+ * iterations. `LIMITS` bounds parameters that are read back from stored
+ * hashes so that a tampered or foreign record cannot force unbounded work.
  */
 export const PASSWORD_HASH = Object.freeze({
     SALT_BYTES: 16,
@@ -11,15 +16,43 @@ export const PASSWORD_HASH = Object.freeze({
         PARALLELIZATION: 1,
     }),
     PBKDF2: Object.freeze({
-        ITERATIONS: 310_000,
+        ITERATIONS: 600_000,
+        /**
+         * Floor for stored or caller-supplied iteration counts. Kept below the
+         * default so hashes produced by other systems with older (but still
+         * NIST-compliant) parameters remain verifiable; new hashes always use
+         * `ITERATIONS`.
+         */
+        MIN_ITERATIONS: 100_000,
         DIGEST: "sha256",
     }),
+    LIMITS: Object.freeze({
+        MIN_SALT_BYTES: 16,
+        MAX_SALT_BYTES: 64,
+        MIN_KEY_BYTES: 16,
+        MAX_KEY_BYTES: 64,
+        MIN_SCRYPT_COST: 2,
+        MAX_SCRYPT_COST: 2 ** 20,
+        MAX_SCRYPT_BLOCK_SIZE: 32,
+        MAX_SCRYPT_PARALLELIZATION: 16,
+        /**
+         * Upper bound on `128 * N * r` (the scrypt working memory in bytes) so
+         * that a stored hash cannot combine the individual maxima into a
+         * multi-gigabyte allocation.
+         */
+        MAX_SCRYPT_MEMORY_BYTES: 1024 * 1024 * 1024,
+        MAX_PBKDF2_ITERATIONS: 10_000_000,
+    }),
 });
 /**
  * Password policy defaults.
  *
  * These values are intentionally conservative defaults.
  * Applications may impose stricter requirements.
+ *
+ * `MAX_LENGTH` is measured in UTF-16 code units and is enforced by
+ * `hashPassword`/`verifyPassword` to bound the work an unauthenticated
+ * caller can trigger.
  */
 export const PASSWORD_POLICY = Object.freeze({
     MIN_LENGTH: 8,

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

@@ -15,6 +15,8 @@ export declare const TOKEN: Readonly<{
 }>;
 /**
  * Random value constraints.
+ *
+ * `MIN_BYTES` is the entropy floor (128 bits) enforced by `generateToken`.
  */
 export declare const RANDOM: Readonly<{
     readonly MIN_BYTES: 16;

package/dist/cryptoConstants/cryptoConstants.token.js

@@ -15,6 +15,8 @@ export const TOKEN = Object.freeze({
 });
 /**
  * Random value constraints.
+ *
+ * `MIN_BYTES` is the entropy floor (128 bits) enforced by `generateToken`.
  */
 export const RANDOM = Object.freeze({
     MIN_BYTES: 16,

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

@@ -1,10 +1,13 @@
 /**
- * Supported cryptographic algorithms used by Zudojs.
+ * Cryptographic algorithms implemented by Zudojs.
+ *
+ * Every member listed here is implemented by the Node provider. Algorithms
+ * that are not implemented (AES-CBC, ChaCha20-Poly1305, Argon2id, X25519,
+ * bcrypt) are deliberately absent so that the type system and the runtime
+ * agree on what is supported.
  */
 export declare enum CryptoAlgorithm {
     AES_256_GCM = "aes-256-gcm",
-    AES_256_CBC = "aes-256-cbc",
-    CHACHA20_POLY1305 = "chacha20-poly1305",
     SHA_256 = "sha256",
     SHA_384 = "sha384",
     SHA_512 = "sha512",
@@ -15,16 +18,15 @@ export declare enum CryptoAlgorithm {
     HMAC_SHA384 = "hmac-sha384",
     HMAC_SHA512 = "hmac-sha512",
     PBKDF2_SHA256 = "pbkdf2-sha256",
+    PBKDF2_SHA384 = "pbkdf2-sha384",
     PBKDF2_SHA512 = "pbkdf2-sha512",
     SCRYPT = "scrypt",
-    ARGON2ID = "argon2id",
-    ED25519 = "ed25519",
-    X25519 = "x25519"
+    ED25519 = "ed25519"
 }
 /**
  * Algorithms that provide authenticated encryption.
  */
-export declare const AEAD_ALGORITHMS: readonly [CryptoAlgorithm.AES_256_GCM, CryptoAlgorithm.CHACHA20_POLY1305];
+export declare const AEAD_ALGORITHMS: readonly [CryptoAlgorithm.AES_256_GCM];
 /**
  * Algorithms intended for hashing.
  */
@@ -32,13 +34,25 @@ export declare const HASH_ALGORITHMS: readonly [CryptoAlgorithm.SHA_256, CryptoA
 /**
  * Algorithms intended for password/key derivation.
  */
-export declare const KEY_DERIVATION_ALGORITHMS: readonly [CryptoAlgorithm.PBKDF2_SHA256, CryptoAlgorithm.PBKDF2_SHA512, CryptoAlgorithm.SCRYPT, CryptoAlgorithm.ARGON2ID];
+export declare const KEY_DERIVATION_ALGORITHMS: readonly [CryptoAlgorithm.PBKDF2_SHA256, CryptoAlgorithm.PBKDF2_SHA384, CryptoAlgorithm.PBKDF2_SHA512, CryptoAlgorithm.SCRYPT];
 /**
  * Algorithms intended for message authentication.
  */
 export declare const MAC_ALGORITHMS: readonly [CryptoAlgorithm.HMAC_SHA256, CryptoAlgorithm.HMAC_SHA384, CryptoAlgorithm.HMAC_SHA512];
+/**
+ * Key algorithms intended for digital signatures.
+ *
+ * Only Ed25519 keys are representable as a `CryptoKey`. RSA and ECDSA
+ * signing is supported through `SignatureAlgorithm` with PEM/DER key
+ * material rather than through this enum.
+ */
+export declare const SIGNATURE_ALGORITHMS: readonly [CryptoAlgorithm.ED25519];
 /**
  * AES-GCM constants.
+ *
+ * The 96-bit IV and 128-bit authentication tag are the only sizes accepted
+ * by this package: shorter tags weaken forgery resistance and non-96-bit
+ * IVs are GHASH-derived, which shrinks the effective nonce space.
  */
 export declare const AES_GCM: Readonly<{
     readonly KEY_BYTES: 32;
@@ -66,6 +80,7 @@ export declare const KEY_SIZE: Readonly<{
     readonly AES_256_BITS: 256;
     readonly ED25519_BITS: 256;
     readonly MIN_SYMMETRIC_KEY_BITS: 128;
+    readonly MIN_HMAC_KEY_BYTES: 16;
 }>;
 /**
  * Encoding constants.
@@ -77,19 +92,26 @@ export declare const ENCODING: Readonly<{
     readonly UTF8: "utf8";
 }>;
 /**
- * Cryptographic algorithm identifiers.
+ * Cryptographic algorithm identifiers as a plain constant object.
+ *
+ * Mirrors `CryptoAlgorithm` exactly (same names and values) for callers
+ * that prefer `as const` objects over enums.
  */
 export declare const CRYPTO_ALGORITHM: Readonly<{
-    readonly SHA256: "sha256";
-    readonly SHA384: "sha384";
-    readonly SHA512: "sha512";
+    readonly AES_256_GCM: "aes-256-gcm";
+    readonly SHA_256: "sha256";
+    readonly SHA_384: "sha384";
+    readonly SHA_512: "sha512";
     readonly SHA3_256: "sha3-256";
     readonly SHA3_384: "sha3-384";
     readonly SHA3_512: "sha3-512";
-    readonly AES_256_GCM: "aes-256-gcm";
-    readonly ED25519: "ed25519";
+    readonly HMAC_SHA256: "hmac-sha256";
+    readonly HMAC_SHA384: "hmac-sha384";
+    readonly HMAC_SHA512: "hmac-sha512";
     readonly PBKDF2_SHA256: "pbkdf2-sha256";
+    readonly PBKDF2_SHA384: "pbkdf2-sha384";
     readonly PBKDF2_SHA512: "pbkdf2-sha512";
     readonly SCRYPT: "scrypt";
+    readonly ED25519: "ed25519";
 }>;
 //# sourceMappingURL=cryptoConstants.type.d.ts.map