@zintrust/core 0.1.28 → 0.1.29

package/src/security/EncryptedEnvelope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+export type EncryptedEnvelopeCipher = 'aes-256-cbc' | 'aes-256-gcm';
+export type EncryptedEnvelopeCipherInput = EncryptedEnvelopeCipher | 'AES-256-CBC' | 'AES-256-GCM';
+export type EncryptedEnvelopePayload = {
+    iv: string;
+    value: string;
+    mac?: string;
+    tag?: string;
+};
+export type EncryptedEnvelopeSerializer<T> = {
+    serialize: (value: T) => string;
+    deserialize: (value: string) => T;
+};
+export type EncryptedEnvelopeKeyring = {
+    primaryKey: Uint8Array;
+    previousKeys: Uint8Array[];
+};
+export type EncryptedEnvelopeEnv = {
+    APP_KEY?: string;
+    APP_PREVIOUS_KEYS?: string;
+    ENCRYPTION_CIPHER?: string;
+};
+export declare const EncryptedEnvelope: Readonly<{
+    normalizeCipher: (cipher: EncryptedEnvelopeCipherInput) => EncryptedEnvelopeCipher;
+    /**
+     * Build a keyring from environment variables.
+     * - Uses APP_KEY
+     * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+     */
+    keyringFromEnv(env?: EncryptedEnvelopeEnv): EncryptedEnvelopeKeyring;
+    /**
+     * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+     */
+    encryptString(plaintext: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+    }): string;
+    /**
+     * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+     * Tries the primary key first, then previous keys.
+     */
+    decryptString(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+    }): string;
+    /**
+     * Encrypt arbitrary values using a caller-provided serializer.
+     * This supports encrypted payloads for frameworks that store serialized values.
+     */
+    encrypt<T>(value: T, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): string;
+    /**
+     * Decrypt into an arbitrary value using a caller-provided serializer.
+     */
+    decrypt<T>(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): T;
+}>;
+export default EncryptedEnvelope;
+//# sourceMappingURL=EncryptedEnvelope.d.ts.map

package/src/security/EncryptedEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedEnvelope.d.ts","sourceRoot":"","sources":["../../../src/security/EncryptedEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AACpE,MAAM,MAAM,4BAA4B,GAAG,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AAEnG,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,UAAU,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AA6LF,eAAO,MAAM,iBAAiB;8BA3LG,4BAA4B,KAAG,uBAAuB;IA8LrF;;;;OAIG;yBAEI,oBAAoB,GACxB,wBAAwB;IAe3B;;OAEG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAC7D,MAAM;IAgCT;;;OAGG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACtF,MAAM;IA0BT;;;OAGG;YACK,CAAC,SACA,CAAC,WACC;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,MAAM;IAQT;;OAEG;YACK,CAAC,aACI,MAAM,WACR;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,CAAC;EASJ,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/security/EncryptedEnvelope.js

@@ -0,0 +1,256 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+import { Env } from '../config/env.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual, } from '../node-singletons/crypto.js';
+const normalizeCipher = (cipher) => {
+    const normalized = cipher.toLowerCase();
+    if (normalized === 'aes-256-cbc')
+        return 'aes-256-cbc';
+    if (normalized === 'aes-256-gcm')
+        return 'aes-256-gcm';
+    throw ErrorFactory.createValidationError('Unsupported ENCRYPTION_CIPHER', {
+        cipher,
+        supported: ['aes-256-cbc', 'aes-256-gcm'],
+    });
+};
+const normalizeBase64ForCompare = (value) => {
+    const trimmed = value.trim();
+    // Remove base64 padding without regex (avoids any regex backtracking concerns).
+    let end = trimmed.length;
+    while (end > 0 && trimmed.codePointAt(end - 1) === 61) {
+        end -= 1;
+    }
+    return trimmed.slice(0, end);
+};
+const decodeBase64 = (input, label) => {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    // Note: Buffer.from(..., 'base64') does not reliably throw on invalid input.
+    // Validate by re-encoding and comparing (ignoring padding).
+    const decoded = Buffer.from(trimmed, 'base64');
+    if (decoded.length === 0) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    const roundTrip = decoded.toString('base64');
+    if (normalizeBase64ForCompare(roundTrip) !== normalizeBase64ForCompare(trimmed)) {
+        throw ErrorFactory.createValidationError(`Invalid base64 for ${label}`);
+    }
+    return decoded;
+};
+const CIPHER_KEY_BYTES = Object.freeze({
+    'aes-256-cbc': 32,
+    'aes-256-gcm': 32,
+});
+const expectedKeyBytesForCipher = (cipher) => CIPHER_KEY_BYTES[cipher];
+const parseKey = (key, cipher) => {
+    const trimmed = key.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Missing APP_KEY');
+    }
+    const raw = trimmed.startsWith('base64:') ? trimmed.slice('base64:'.length) : trimmed;
+    const bytes = decodeBase64(raw, 'APP_KEY');
+    const expectedBytes = expectedKeyBytesForCipher(cipher);
+    if (bytes.length !== expectedBytes) {
+        throw ErrorFactory.createValidationError('Invalid APP_KEY length for cipher', {
+            cipher,
+            expectedBytes,
+            actualBytes: bytes.length,
+        });
+    }
+    return new Uint8Array(bytes);
+};
+const parsePreviousKeys = (raw, cipher) => {
+    const value = (raw ?? '').trim();
+    if (value.length === 0)
+        return [];
+    const items = (() => {
+        if (value.startsWith('[')) {
+            try {
+                const parsed = JSON.parse(value);
+                if (!Array.isArray(parsed))
+                    return [];
+                return parsed.filter((v) => typeof v === 'string');
+            }
+            catch {
+                return [];
+            }
+        }
+        return value
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    })();
+    return items.map((k) => parseKey(k, cipher));
+};
+const parsePayload = (payload) => {
+    const decoded = Buffer.from(payload, 'base64').toString('utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not JSON)');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (not an object)');
+    }
+    const record = parsed;
+    const iv = typeof record['iv'] === 'string' ? record['iv'] : '';
+    const value = typeof record['value'] === 'string' ? record['value'] : '';
+    const mac = typeof record['mac'] === 'string' ? record['mac'] : undefined;
+    const tag = typeof record['tag'] === 'string' ? record['tag'] : undefined;
+    if (iv.length === 0 || value.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid encrypted envelope payload (missing iv/value)');
+    }
+    return { iv, value, mac, tag };
+};
+const computeMacHex = (key, ivBase64, valueBase64) => {
+    // Envelope MAC: mac = HMAC-SHA256(iv + value, key), where iv/value are base64 strings.
+    return createHmac('sha256', Buffer.from(key))
+        .update(ivBase64 + valueBase64, 'utf8')
+        .digest('hex');
+};
+const timingSafeEqualsHex = (a, b) => {
+    const aBuf = Buffer.from(a, 'utf8');
+    const bBuf = Buffer.from(b, 'utf8');
+    if (aBuf.length !== bBuf.length)
+        return false;
+    return timingSafeEqual(aBuf, bBuf);
+};
+const ivLengthFor = (cipher) => {
+    // OpenSSL defaults for these ciphers.
+    if (cipher === 'aes-256-gcm')
+        return 12;
+    return 16;
+};
+const decryptWithKey = (payload, cipher, key) => {
+    const iv = decodeBase64(payload.iv, 'iv');
+    const ciphertext = decodeBase64(payload.value, 'value');
+    if (cipher === 'aes-256-cbc') {
+        const expected = payload.mac ?? '';
+        if (expected.length === 0) {
+            throw ErrorFactory.createValidationError('Missing mac for aes-256-cbc envelope');
+        }
+        const actual = computeMacHex(key, payload.iv, payload.value);
+        if (!timingSafeEqualsHex(actual, expected)) {
+            throw ErrorFactory.createSecurityError('Invalid MAC');
+        }
+        const decipher = createDecipheriv('aes-256-cbc', Buffer.from(key), iv);
+        const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plain.toString('utf8');
+    }
+    const tagB64 = (payload.tag ?? '').trim();
+    if (tagB64.length === 0) {
+        throw ErrorFactory.createValidationError('Missing tag for aes-256-gcm envelope');
+    }
+    const tag = decodeBase64(tagB64, 'tag');
+    const decipher = createDecipheriv('aes-256-gcm', Buffer.from(key), iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plain.toString('utf8');
+};
+export const EncryptedEnvelope = Object.freeze({
+    normalizeCipher,
+    /**
+     * Build a keyring from environment variables.
+     * - Uses APP_KEY
+     * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+     */
+    keyringFromEnv(env = Env) {
+        const cipherRaw = (env.ENCRYPTION_CIPHER ?? '').trim();
+        if (cipherRaw.length === 0) {
+            throw ErrorFactory.createConfigError('ENCRYPTION_CIPHER must be set', {
+                key: 'ENCRYPTION_CIPHER',
+            });
+        }
+        const cipher = normalizeCipher(cipherRaw);
+        const primaryKey = parseKey(env.APP_KEY ?? '', cipher);
+        const previousKeys = parsePreviousKeys(env.APP_PREVIOUS_KEYS, cipher);
+        return { primaryKey, previousKeys };
+    },
+    /**
+     * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+     */
+    encryptString(plaintext, options) {
+        const cipher = normalizeCipher(options.cipher);
+        const key = parseKey(options.key, cipher);
+        const iv = randomBytes(ivLengthFor(cipher));
+        if (cipher === 'aes-256-cbc') {
+            const c = createCipheriv('aes-256-cbc', Buffer.from(key), iv);
+            const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+            const ivB64 = iv.toString('base64');
+            const valueB64 = ciphertext.toString('base64');
+            const mac = computeMacHex(key, ivB64, valueB64);
+            const envelope = { iv: ivB64, value: valueB64, mac, tag: '' };
+            return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+        }
+        const c = createCipheriv('aes-256-gcm', Buffer.from(key), iv);
+        const ciphertext = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+        const tag = c.getAuthTag();
+        const envelope = {
+            iv: iv.toString('base64'),
+            value: ciphertext.toString('base64'),
+            mac: '',
+            tag: tag.toString('base64'),
+        };
+        return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+    },
+    /**
+     * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+     * Tries the primary key first, then previous keys.
+     */
+    decryptString(encrypted, options) {
+        const cipher = normalizeCipher(options.cipher);
+        const primaryKey = parseKey(options.key, cipher);
+        const previous = (options.previousKeys ?? []).map((k) => parseKey(k, cipher));
+        const payload = parsePayload(encrypted);
+        const keys = [primaryKey, ...previous];
+        let lastError;
+        for (const key of keys) {
+            try {
+                return decryptWithKey(payload, cipher, key);
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw ErrorFactory.createSecurityError('Unable to decrypt encrypted envelope with provided keyring', {
+            cause: lastError instanceof Error ? lastError.message : String(lastError),
+        });
+    },
+    /**
+     * Encrypt arbitrary values using a caller-provided serializer.
+     * This supports encrypted payloads for frameworks that store serialized values.
+     */
+    encrypt(value, options) {
+        const serialized = options.serializer.serialize(value);
+        return EncryptedEnvelope.encryptString(serialized, {
+            cipher: options.cipher,
+            key: options.key,
+        });
+    },
+    /**
+     * Decrypt into an arbitrary value using a caller-provided serializer.
+     */
+    decrypt(encrypted, options) {
+        const serialized = EncryptedEnvelope.decryptString(encrypted, {
+            cipher: options.cipher,
+            key: options.key,
+            previousKeys: options.previousKeys,
+        });
+        return options.serializer.deserialize(serialized);
+    },
+});
+export default EncryptedEnvelope;

package/src/security/Encryptor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Encryptor
+ * Password hashing with dual support: PBKDF2 (default) and optional bcrypt
+ */
+/**
+ * Hash algorithm selector
+ */
+export type HashAlgorithm = 'pbkdf2' | 'bcrypt';
+export interface IEncryptor {
+    hash(password: string): Promise<string>;
+    verify(password: string, hash: string): Promise<boolean>;
+    getAlgorithm(): HashAlgorithm;
+}
+export declare const Encryptor: IEncryptor;
+//# sourceMappingURL=Encryptor.d.ts.map

package/src/security/Encryptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Encryptor.d.ts","sourceRoot":"","sources":["../../../src/security/Encryptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAsMhD,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,YAAY,IAAI,aAAa,CAAC;CAC/B;AAuCD,eAAO,MAAM,SAAS,EAAE,UAItB,CAAC"}

package/src/security/Encryptor.js

@@ -0,0 +1,199 @@
+/**
+ * Encryptor
+ * Password hashing with dual support: PBKDF2 (default) and optional bcrypt
+ */
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import * as crypto from '../node-singletons/crypto.js';
+import { promisify } from '../node-singletons/util.js';
+function isBcryptModule(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record['hash'] === 'function' && typeof record['compare'] === 'function';
+}
+let algorithm = 'pbkdf2';
+let bcrypt;
+let loadingPromise;
+async function loadBcrypt() {
+    try {
+        const imported = await import('bcrypt');
+        const module = imported;
+        const candidate = module.default ?? module;
+        if (!isBcryptModule(candidate)) {
+            throw ErrorFactory.createConfigError('Invalid bcrypt module shape');
+        }
+        bcrypt = candidate;
+        algorithm = 'bcrypt';
+    }
+    catch (error) {
+        Logger.error('bcrypt not installed, falling back to PBKDF2', error);
+        ErrorFactory.createSecurityError('bcrypt not installed, falling back to PBKDF2', error);
+        // bcrypt not installed, will use PBKDF2
+        algorithm = 'pbkdf2';
+    }
+}
+async function ensureLoaded() {
+    if (bcrypt !== undefined)
+        return;
+    if (loadingPromise !== undefined)
+        return loadingPromise;
+    loadingPromise = loadBcrypt();
+    return loadingPromise;
+}
+/**
+ * Timing-safe string comparison
+ */
+function timingSafeEquals(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+    }
+    return result === 0;
+}
+/**
+ * Hash with PBKDF2 (default)
+ */
+async function hashPbkdf2(password) {
+    const iterations = 600000; // OWASP recommended for SHA-256
+    const salt = crypto.randomBytes(32).toString('hex');
+    const keyLength = 64;
+    const digest = 'sha256';
+    const pbkdf2Fn = (() => {
+        try {
+            const maybe = crypto.pbkdf2;
+            return typeof maybe === 'function' ? maybe : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const pbkdf2SyncFn = (() => {
+        try {
+            const maybe = crypto.pbkdf2Sync;
+            return typeof maybe === 'function' ? maybe : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    let hashHex = '';
+    if (pbkdf2Fn) {
+        const pbkdf2Async = promisify(pbkdf2Fn);
+        hashHex = (await pbkdf2Async(password, salt, iterations, keyLength, digest)).toString('hex');
+    }
+    else if (pbkdf2SyncFn) {
+        hashHex = pbkdf2SyncFn(password, salt, iterations, keyLength, digest).toString('hex');
+    }
+    else {
+        throw ErrorFactory.createSecurityError('PBKDF2 is not available in this runtime');
+    }
+    // Format: algorithm$iterations$salt$hash
+    return `pbkdf2$${iterations}$${salt}$${hashHex}`;
+}
+/**
+ * Verify PBKDF2 hash
+ */
+async function verifyPbkdf2(password, passwordHash) {
+    const parts = passwordHash.split('$');
+    const iterationsStr = parts[1];
+    const salt = parts[2];
+    const storedHash = parts[3];
+    if (iterationsStr === undefined || salt === undefined || storedHash === undefined) {
+        return false;
+    }
+    try {
+        const iterations = Number.parseInt(iterationsStr, 10);
+        const keyLength = 64;
+        const digest = 'sha256';
+        const pbkdf2Fn = (() => {
+            try {
+                const maybe = crypto.pbkdf2;
+                return typeof maybe === 'function' ? maybe : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const pbkdf2SyncFn = (() => {
+            try {
+                const maybe = crypto.pbkdf2Sync;
+                return typeof maybe === 'function' ? maybe : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        let computed = '';
+        if (pbkdf2Fn) {
+            const pbkdf2Async = promisify(pbkdf2Fn);
+            computed = (await pbkdf2Async(password, salt, iterations, keyLength, digest)).toString('hex');
+        }
+        else if (pbkdf2SyncFn) {
+            computed = pbkdf2SyncFn(password, salt, iterations, keyLength, digest).toString('hex');
+        }
+        else {
+            throw ErrorFactory.createSecurityError('PBKDF2 is not available in this runtime');
+        }
+        return timingSafeEquals(computed, storedHash);
+    }
+    catch (error) {
+        Logger.error('PBKDF2 verification failed', error);
+        ErrorFactory.createSecurityError('PBKDF2 verification failed', error);
+        return false;
+    }
+}
+/**
+ * Hash with bcrypt
+ */
+async function hashBcrypt(bcryptModule, password) {
+    const rounds = 12;
+    return bcryptModule.hash(password, rounds);
+}
+/**
+ * Verify bcrypt hash
+ */
+async function verifyBcrypt(bcryptModule, password, passwordHash) {
+    return bcryptModule.compare(password, passwordHash);
+}
+/**
+ * Encryptor handles password hashing and verification
+ * Refactored to Functional Object pattern
+ */
+const hash = async (password) => {
+    await ensureLoaded();
+    if (algorithm === 'bcrypt' && bcrypt !== undefined) {
+        return hashBcrypt(bcrypt, password);
+    }
+    return hashPbkdf2(password);
+};
+/**
+ * Verify password against hash
+ */
+const verify = async (password, passwordHash) => {
+    await ensureLoaded();
+    // Detect hash format
+    if (passwordHash.startsWith('$2')) {
+        // bcrypt hash format
+        if (bcrypt !== undefined) {
+            return verifyBcrypt(bcrypt, password, passwordHash);
+        }
+        throw ErrorFactory.createConfigError('bcrypt not available to verify hash');
+    }
+    // PBKDF2 hash format (algorithm$iterations$salt$hash)
+    return verifyPbkdf2(password, passwordHash);
+};
+/**
+ * Get current algorithm
+ */
+const getAlgorithm = () => {
+    return algorithm;
+};
+export const Encryptor = Object.freeze({
+    hash,
+    verify,
+    getAlgorithm,
+});

package/src/security/Hash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hash
+ * bcrypt-based password hashing utility.
+ *
+ * Runtime-aware: uses dynamic import for bcrypt.
+ */
+export declare const Hash: Readonly<{
+    isValidHash(hash: string): boolean;
+    hash(plaintext: string): Promise<string>;
+    hashWithRounds(plaintext: string, rounds: number): Promise<string>;
+    verify(plaintext: string, hashed: string): Promise<boolean>;
+}>;
+export default Hash;
+//# sourceMappingURL=Hash.d.ts.map

package/src/security/Hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hash.d.ts","sourceRoot":"","sources":["../../../src/security/Hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+CH,eAAO,MAAM,IAAI;sBACG,MAAM,GAAG,OAAO;oBAIZ,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;8BAUd,MAAM,UAAU,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;sBAgBhD,MAAM,UAAU,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;EAWjE,CAAC;AAEH,eAAe,IAAI,CAAC"}

package/src/security/Hash.js

@@ -0,0 +1,81 @@
+/**
+ * Hash
+ * bcrypt-based password hashing utility.
+ *
+ * Runtime-aware: uses dynamic import for bcrypt.
+ */
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+function isBcryptModule(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record['hash'] === 'function' && typeof record['compare'] === 'function';
+}
+let bcrypt;
+let loadingPromise;
+async function loadBcrypt() {
+    const imported = await import('bcrypt');
+    const module = imported;
+    const candidate = module.default ?? module;
+    if (!isBcryptModule(candidate)) {
+        throw ErrorFactory.createConfigError('Invalid bcrypt module shape');
+    }
+    bcrypt = candidate;
+}
+async function ensureBcrypt() {
+    if (bcrypt !== undefined)
+        return bcrypt;
+    loadingPromise ??= loadBcrypt().catch((error) => {
+        Logger.error('bcrypt unavailable', error);
+        throw ErrorFactory.createConfigError('bcrypt unavailable', error);
+    });
+    await loadingPromise;
+    if (bcrypt === undefined) {
+        throw ErrorFactory.createConfigError('bcrypt unavailable');
+    }
+    return bcrypt;
+}
+const BCRYPT_HASH_RE = /^\$2[aby]\$\d{2}\$[./A-Za-z0-9]{53}$/;
+export const Hash = Object.freeze({
+    isValidHash(hash) {
+        return BCRYPT_HASH_RE.test(hash);
+    },
+    async hash(plaintext) {
+        const bcryptModule = await ensureBcrypt();
+        try {
+            return await bcryptModule.hash(plaintext, 12);
+        }
+        catch (error) {
+            Logger.error('Password hashing failed', error);
+            throw ErrorFactory.createSecurityError('Password hashing failed', error);
+        }
+    },
+    async hashWithRounds(plaintext, rounds) {
+        const bcryptModule = await ensureBcrypt();
+        const normalizedRounds = Number.isFinite(rounds) ? Math.trunc(rounds) : 0;
+        if (normalizedRounds <= 0) {
+            throw ErrorFactory.createConfigError('Invalid bcrypt rounds', { rounds });
+        }
+        try {
+            return await bcryptModule.hash(plaintext, normalizedRounds);
+        }
+        catch (error) {
+            Logger.error('Password hashing failed', error);
+            throw ErrorFactory.createSecurityError('Password hashing failed', error);
+        }
+    },
+    async verify(plaintext, hashed) {
+        if (!Hash.isValidHash(hashed))
+            return false;
+        try {
+            const bcryptModule = await ensureBcrypt();
+            return await bcryptModule.compare(plaintext, hashed);
+        }
+        catch (error) {
+            Logger.error('Password verify failed', error);
+            return false;
+        }
+    },
+});
+export default Hash;