@digitaldefiance/node-express-suite 3.7.5 → 3.8.0

package/src/services/key-wrapping.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * @fileoverview Service for password-based key wrapping and unwrapping using AES-256-GCM.
+ * Provides secure master key management, password changes, and generic secret wrapping.
+ * @module services/key-wrapping
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyWrappingService = void 0;
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const node_ecies_lib_1 = require("@digitaldefiance/node-ecies-lib");
+const crypto_1 = require("crypto");
+const errors_1 = require("../errors");
+/**
+ * Creates a PBKDF2 service instance from constants.
+ * @param constants Configuration constants
+ * @returns Configured PBKDF2 service
+ */
+function createPbkdf2Service(constants) {
+    return node_ecies_lib_1.Pbkdf2Service.fromConstants(constants);
+}
+/**
+ * Service for password-based key wrapping and unwrapping operations.
+ * Provides secure master key management with AES-256-GCM encryption and PBKDF2 key derivation.
+ * Supports both synchronous and asynchronous operations with deduplication for concurrent requests.
+ */
+class KeyWrappingService {
+    /**
+     * In-flight de-duplication map to share PBKDF2 work across concurrent identical requests.
+     * Stores promises of base64-encoded master key bytes for sharing across callers.
+     * @private
+     */
+    static inFlightUnwraps = new Map();
+    /**
+     * Generates a new random master key and wraps it with the user's password.
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Object containing the master key and wrapped key metadata
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapNewMasterKey(password, constants = node_ecies_lib_1.Constants) {
+        const masterKey = new ecies_lib_1.SecureBuffer((0, crypto_1.randomBytes)(constants.WRAPPED_KEY.MASTER_KEY_SIZE));
+        const wrappedKey = this.wrapMasterKey(masterKey, password, constants);
+        return { masterKey, wrappedKey };
+    }
+    /**
+     * Wraps an existing master key with a password-derived key using AES-256-GCM.
+     * @param masterKey Master key to wrap
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Wrapped key metadata including salt, IV, auth tag, and encrypted key
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapMasterKey(masterKey, password, constants = node_ecies_lib_1.Constants) {
+        if (constants.PasswordRegex.test(password.value ?? '') === false) {
+            throw new errors_1.InvalidNewPasswordError();
+        }
+        const salt = (0, crypto_1.randomBytes)(constants.WRAPPED_KEY.SALT_SIZE);
+        const iterations = constants.WRAPPED_KEY.MIN_ITERATIONS;
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Derive key from password using centralized PBKDF2 service
+        const derivedKey = pbkdf2Service.deriveKeyFromPassword(Buffer.from(password.valueAsUint8Array), salt, iterations, constants.WRAPPED_KEY.SALT_SIZE, 32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        // Encrypt master key
+        const iv = (0, crypto_1.randomBytes)(constants.WRAPPED_KEY.IV_SIZE);
+        const cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+        const encrypted = Buffer.concat([
+            cipher.update(masterKey.value),
+            cipher.final(),
+        ]);
+        const authTag = cipher.getAuthTag();
+        passwordKeySecure.dispose();
+        return {
+            salt: salt.toString('hex'),
+            iv: iv.toString('hex'),
+            authTag: authTag.toString('hex'),
+            encryptedMasterKey: encrypted.toString('hex'),
+            iterations,
+        };
+    }
+    /**
+     * Unwraps a master key using the user's password (synchronous).
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password for unwrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapMasterKey(wrappedKey, password, constants = node_ecies_lib_1.Constants) {
+        const salt = Buffer.from(wrappedKey.salt, 'hex');
+        const iv = Buffer.from(wrappedKey.iv, 'hex');
+        const authTag = Buffer.from(wrappedKey.authTag, 'hex');
+        const encrypted = Buffer.from(wrappedKey.encryptedMasterKey, 'hex');
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Derive the same key from password using centralized PBKDF2 service
+        const derivedKey = pbkdf2Service.deriveKeyFromPassword(Buffer.from(password.valueAsUint8Array), salt, wrappedKey.iterations, salt.length, // Use actual salt size
+        32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        try {
+            const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+            decipher.setAuthTag(authTag);
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final(),
+            ]);
+            return new ecies_lib_1.SecureBuffer(decrypted);
+        }
+        catch {
+            throw new errors_1.InvalidPasswordError();
+        }
+        finally {
+            passwordKeySecure.dispose();
+        }
+    }
+    /**
+     * Async version of unwrapMasterKey that uses libuv threadpool via crypto.pbkdf2
+     * to avoid blocking the event loop during password verification.
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password (SecureString or raw string)
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    async unwrapMasterKeyAsync(wrappedKey, password, constants = node_ecies_lib_1.Constants) {
+        const __perfEnabled = process.env['PERF_LOGS'] === '1';
+        const _t0 = __perfEnabled ? Date.now() : 0;
+        const salt = Buffer.from(wrappedKey.salt, 'hex');
+        const iv = Buffer.from(wrappedKey.iv, 'hex');
+        const authTag = Buffer.from(wrappedKey.authTag, 'hex');
+        const encrypted = Buffer.from(wrappedKey.encryptedMasterKey, 'hex');
+        // Accept either a SecureString (preferred) or a raw password string to avoid
+        // expensive SecureString construction in the hot login path.
+        const pwdBuffer = 
+        // amazonq-ignore-next-line false positive
+        typeof password === 'string'
+            ? Buffer.from(password, 'utf8')
+            : Buffer.from(password.valueAsUint8Array);
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Use centralized PBKDF2 service for async key derivation
+        const derivedKey = await pbkdf2Service.deriveKeyFromPasswordAsync(pwdBuffer, salt, wrappedKey.iterations, salt.length, // Use actual salt size
+        32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        try {
+            const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+            decipher.setAuthTag(authTag);
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final(),
+            ]);
+            if (__perfEnabled)
+                console.warn('[perf] unwrapMasterKeyAsync pbkdf2', 'iters=' + String(wrappedKey.iterations).replace(/[\r\n]/g, ''), 'dt=' + (Date.now() - _t0) + 'ms');
+            return new ecies_lib_1.SecureBuffer(decrypted);
+        }
+        catch {
+            throw new errors_1.InvalidPasswordError();
+        }
+        finally {
+            // Best-effort zero the temporary password buffer
+            try {
+                pwdBuffer.fill(0);
+            }
+            catch {
+                // ignore
+            }
+            passwordKeySecure.dispose();
+        }
+    }
+    /**
+     * Deduplicated async unwrap that coalesces concurrent identical PBKDF2 operations.
+     * Keyed by salt + iterations + password hash to avoid redundant computation.
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password as string
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    async unwrapMasterKeyAsyncDedup(wrappedKey, password, constants = node_ecies_lib_1.Constants) {
+        // Derive a short cache key; avoid storing raw password by hashing
+        const pwdKey = (0, crypto_1.createHash)('sha256')
+            .update(password, 'utf8')
+            .digest('hex')
+            .slice(0, 24);
+        const cacheKey = `${wrappedKey.salt}:${wrappedKey.iterations}:${pwdKey}`;
+        let p = KeyWrappingService.inFlightUnwraps.get(cacheKey);
+        if (!p) {
+            // Compute once, extract raw bytes, dispose the shared SecureBuffer, and cache the bytes
+            p = (async () => {
+                const mk = await this.unwrapMasterKeyAsync(wrappedKey, password, constants);
+                try {
+                    const copy = Buffer.from(mk.value);
+                    const b64 = copy.toString('base64');
+                    // zeroize copy
+                    copy.fill(0);
+                    return b64;
+                }
+                finally {
+                    mk.dispose();
+                }
+            })().finally(() => {
+                // Best-effort cleanup
+                KeyWrappingService.inFlightUnwraps.delete(cacheKey);
+            });
+            KeyWrappingService.inFlightUnwraps.set(cacheKey, p);
+        }
+        const b64 = await p;
+        // Return a fresh SecureBuffer per caller to avoid cross-disposal races
+        const buf = Buffer.from(b64, 'base64');
+        const secure = new ecies_lib_1.SecureBuffer(Buffer.from(buf));
+        buf.fill(0);
+        return secure;
+    }
+    /**
+     * Changes password by re-wrapping the master key with a new password.
+     * @param wrappedKey Current wrapped key metadata
+     * @param oldPassword Current password
+     * @param newPassword New password
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns New wrapped key metadata
+     * @throws {InvalidPasswordError} If old password is incorrect
+     * @throws {InvalidNewPasswordError} If new password doesn't meet requirements
+     */
+    changePassword(wrappedKey, oldPassword, newPassword, constants = node_ecies_lib_1.Constants) {
+        // Unwrap with old password
+        const masterKey = this.unwrapMasterKey(wrappedKey, oldPassword, constants);
+        try {
+            // Re-wrap with new password
+            return this.wrapMasterKey(masterKey, newPassword, constants);
+        }
+        finally {
+            masterKey.dispose();
+        }
+    }
+    /**
+     * Wraps arbitrary secret bytes with a password-derived key using AES-256-GCM.
+     * @param secret Secret data to wrap
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Password-wrapped secret metadata
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapSecret(secret, password, constants = node_ecies_lib_1.Constants) {
+        if (constants.PasswordRegex.test(password.value ?? '') === false) {
+            throw new errors_1.InvalidNewPasswordError();
+        }
+        const salt = (0, crypto_1.randomBytes)(constants.WRAPPED_KEY.SALT_SIZE);
+        const iterations = constants.WRAPPED_KEY.MIN_ITERATIONS;
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Derive key from password using centralized PBKDF2 service
+        const derivedKey = pbkdf2Service.deriveKeyFromPassword(Buffer.from(password.valueAsUint8Array), salt, iterations, constants.WRAPPED_KEY.SALT_SIZE, 32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        try {
+            const iv = (0, crypto_1.randomBytes)(constants.WRAPPED_KEY.IV_SIZE);
+            const cipher = (0, crypto_1.createCipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+            const encrypted = Buffer.concat([
+                cipher.update(secret.value),
+                cipher.final(),
+            ]);
+            const authTag = cipher.getAuthTag();
+            return {
+                salt: salt.toString('hex'),
+                iv: iv.toString('hex'),
+                authTag: authTag.toString('hex'),
+                ciphertext: encrypted.toString('hex'),
+                iterations,
+            };
+        }
+        finally {
+            passwordKeySecure.dispose();
+        }
+    }
+    /**
+     * Unwraps a password-wrapped secret (synchronous).
+     * @param wrapped Password-wrapped secret metadata
+     * @param password User's password for unwrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Unwrapped secret in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapSecret(wrapped, password, constants = node_ecies_lib_1.Constants) {
+        const salt = Buffer.from(wrapped.salt, 'hex');
+        const iv = Buffer.from(wrapped.iv, 'hex');
+        const authTag = Buffer.from(wrapped.authTag, 'hex');
+        const encrypted = Buffer.from(wrapped.ciphertext, 'hex');
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Derive key from password using centralized PBKDF2 service
+        const derivedKey = pbkdf2Service.deriveKeyFromPassword(Buffer.from(password.valueAsUint8Array), salt, wrapped.iterations, salt.length, // Use actual salt size
+        32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        try {
+            const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+            decipher.setAuthTag(authTag);
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final(),
+            ]);
+            return new ecies_lib_1.SecureBuffer(decrypted);
+        }
+        catch {
+            throw new errors_1.InvalidPasswordError();
+        }
+        finally {
+            passwordKeySecure.dispose();
+        }
+    }
+    /**
+     * Unwraps a password-wrapped secret using async PBKDF2 to avoid blocking.
+     * @param wrapped Password-wrapped secret metadata
+     * @param password User's password (SecureString or raw string)
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped secret in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     * @throws {Error} If password is undefined, null, or invalid type
+     */
+    async unwrapSecretAsync(wrapped, password, constants = node_ecies_lib_1.Constants) {
+        const salt = Buffer.from(wrapped.salt, 'hex');
+        const iv = Buffer.from(wrapped.iv, 'hex');
+        const authTag = Buffer.from(wrapped.authTag, 'hex');
+        const encrypted = Buffer.from(wrapped.ciphertext, 'hex');
+        // Validate password parameter before using it
+        // amazonq-ignore-next-line false positive
+        if (typeof password === 'string') {
+            if (password === undefined || password === null) {
+                throw new Error('Password cannot be undefined or null');
+            }
+        }
+        else if (!(password instanceof ecies_lib_1.SecureString)) {
+            throw new Error('Password must be provided as string or SecureString');
+        }
+        const pwdBuffer = 
+        // amazonq-ignore-next-line false positive
+        typeof password === 'string'
+            ? Buffer.from(password, 'utf8')
+            : await (async () => password.valueAsUint8Array)();
+        // Additional safety check
+        if (!pwdBuffer) {
+            throw new Error('Failed to create password buffer - password may be invalid');
+        }
+        const pbkdf2Service = createPbkdf2Service(constants);
+        // Use centralized PBKDF2 service for async key derivation
+        const derivedKey = await pbkdf2Service.deriveKeyFromPasswordAsync(Buffer.from(pwdBuffer), salt, wrapped.iterations, salt.length, // Use actual salt size
+        32, // AES-256 key size
+        'sha256');
+        const passwordKeySecure = new ecies_lib_1.SecureBuffer(derivedKey.hash);
+        try {
+            const decipher = (0, crypto_1.createDecipheriv)('aes-256-gcm', passwordKeySecure.value, iv);
+            decipher.setAuthTag(authTag);
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final(),
+            ]);
+            return new ecies_lib_1.SecureBuffer(decrypted);
+        }
+        catch {
+            throw new errors_1.InvalidPasswordError();
+        }
+        finally {
+            try {
+                pwdBuffer.fill(0);
+            }
+            catch {
+                // ignore
+            }
+            passwordKeySecure.dispose();
+        }
+    }
+}
+exports.KeyWrappingService = KeyWrappingService;
+//# sourceMappingURL=key-wrapping.js.map

package/src/services/key-wrapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-wrapping.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/key-wrapping.ts"],"names":[],"mappings":"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"}

package/src/services/mnemonic.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Mnemonic phrase management service.
+ * Securely stores mnemonic HMACs for uniqueness checking without exposing phrases.
+ * @module services/mnemonic
+ */
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { ClientSession, Model } from '@digitaldefiance/mongoose-types';
+import { IMnemonicDocument } from '../documents/mnemonic';
+import { IConstants } from '../interfaces';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+/**
+ * Service for secure mnemonic phrase storage and validation.
+ * Uses HMAC for uniqueness checking without storing actual mnemonics.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export declare class MnemonicService<TID extends PlatformID = Buffer> {
+    private readonly hmacSecret;
+    private readonly MnemonicModel;
+    private readonly constants;
+    constructor(mnemonicModel: Model<IMnemonicDocument<TID>>, hmacSecret: SecureBuffer, constants: IConstants);
+    /**
+     * Disposes of the secure secrets held by this service.
+     */
+    dispose(): void;
+    /**
+     * Creates a non-reversible HMAC of the mnemonic for fast, indexed lookups.
+     * @param mnemonic The mnemonic to hash, wrapped in a SecureString.
+     */
+    getMnemonicHmac(mnemonic: SecureString): string;
+    /**
+     * Checks if a mnemonic already exists in the database using its HMAC.
+     * @param mnemonic The mnemonic to check, wrapped in a SecureString.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    mnemonicExists(mnemonic: SecureString, session?: ClientSession): Promise<boolean>;
+    /**
+     * Adds a new, unique mnemonic to the database with password-based key wrapping.
+     * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+     * @param password User's password for key wrapping.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    addMnemonicWithPassword(mnemonic: SecureString, _password: SecureString, session?: ClientSession): Promise<{
+        document: IMnemonicDocument<TID> | null;
+    }>;
+    /**
+     * Adds a new, unique mnemonic to the database.
+     * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    addMnemonic(mnemonic: SecureString, session?: ClientSession): Promise<IMnemonicDocument<TID> | null>;
+    /**
+     * Retrieves a mnemonic document by ID.
+     * @param mnemonicId The ID of the mnemonic document.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    getMnemonicDocument(mnemonicId: TID, session?: ClientSession): Promise<IMnemonicDocument<TID> | null>;
+    /**
+     * Decrypts a mnemonic from a document using the service's master encryption key.
+     * @param doc The mnemonic document.
+     */
+    /**
+     * Deletes a mnemonic document by ID.
+     * @param mnemonicId The ID of the mnemonic document.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    deleteMnemonicDocument(mnemonicId: TID, session?: ClientSession): Promise<void>;
+}
+//# sourceMappingURL=mnemonic.d.ts.map

package/src/services/mnemonic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mnemonic.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/mnemonic.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAMvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE;;;;GAIG;AACH,qBAAa,eAAe,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAGrC,aAAa,EAAE,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,EAC5C,UAAU,EAAE,YAAY,EACxB,SAAS,EAAE,UAAU;IAQvB;;OAEG;IACI,OAAO,IAAI,IAAI;IAItB;;;OAGG;IACI,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM;IAOtD;;;;OAIG;IACU,cAAc,CACzB,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,OAAO,CAAC;IAQnB;;;;;OAKG;IACU,uBAAuB,CAClC,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,YAAY,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC;QACT,QAAQ,EAAE,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;KACzC,CAAC;IA2BF;;;;OAIG;IACU,WAAW,CACtB,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAsBzC;;;;OAIG;IACU,mBAAmB,CAC9B,UAAU,EAAE,GAAG,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAMzC;;;OAGG;IAEH;;;;OAIG;IACU,sBAAsB,CACjC,UAAU,EAAE,GAAG,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;CAKjB"}

package/src/services/mnemonic.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * @fileoverview Mnemonic phrase management service.
+ * Securely stores mnemonic HMACs for uniqueness checking without exposing phrases.
+ * @module services/mnemonic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MnemonicService = void 0;
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const crypto_1 = require("crypto");
+/**
+ * Service for secure mnemonic phrase storage and validation.
+ * Uses HMAC for uniqueness checking without storing actual mnemonics.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+class MnemonicService {
+    hmacSecret;
+    MnemonicModel;
+    constants;
+    constructor(mnemonicModel, hmacSecret, constants) {
+        this.MnemonicModel = mnemonicModel;
+        // Immediately wrap secrets in secure containers
+        this.hmacSecret = hmacSecret;
+        this.constants = constants;
+    }
+    /**
+     * Disposes of the secure secrets held by this service.
+     */
+    dispose() {
+        this.hmacSecret.dispose();
+    }
+    /**
+     * Creates a non-reversible HMAC of the mnemonic for fast, indexed lookups.
+     * @param mnemonic The mnemonic to hash, wrapped in a SecureString.
+     */
+    getMnemonicHmac(mnemonic) {
+        // Use the raw secret buffer for the HMAC
+        return (0, crypto_1.createHmac)('sha256', this.hmacSecret.value)
+            .update(mnemonic.valueAsUint8Array) // Use the raw buffer for consistency
+            .digest('hex');
+    }
+    /**
+     * Checks if a mnemonic already exists in the database using its HMAC.
+     * @param mnemonic The mnemonic to check, wrapped in a SecureString.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    async mnemonicExists(mnemonic, session) {
+        const hmac = this.getMnemonicHmac(mnemonic);
+        const count = await this.MnemonicModel.countDocuments({ hmac }).session(session ?? null);
+        return count > 0;
+    }
+    /**
+     * Adds a new, unique mnemonic to the database with password-based key wrapping.
+     * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+     * @param password User's password for key wrapping.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    async addMnemonicWithPassword(mnemonic, _password, session) {
+        if (!mnemonic.value || !this.constants.MnemonicRegex.test(mnemonic.value)) {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Validation_MnemonicRegex);
+        }
+        if (await this.mnemonicExists(mnemonic, session)) {
+            return { document: null };
+        }
+        try {
+            const hmac = this.getMnemonicHmac(mnemonic);
+            const [newDoc] = await this.MnemonicModel.create([
+                {
+                    hmac: hmac,
+                },
+            ], { session });
+            return { document: newDoc };
+        }
+        finally {
+            // nothing to dispose
+        }
+    }
+    /**
+     * Adds a new, unique mnemonic to the database.
+     * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    async addMnemonic(mnemonic, session) {
+        if (!mnemonic.value || !this.constants.MnemonicRegex.test(mnemonic.value)) {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Validation_MnemonicRegex);
+        }
+        if (await this.mnemonicExists(mnemonic, session)) {
+            return null;
+        }
+        const hmac = this.getMnemonicHmac(mnemonic);
+        const [newDoc] = await this.MnemonicModel.create([
+            {
+                hmac: hmac,
+            },
+        ], { session });
+        return newDoc;
+    }
+    /**
+     * Retrieves a mnemonic document by ID.
+     * @param mnemonicId The ID of the mnemonic document.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    async getMnemonicDocument(mnemonicId, session) {
+        return await this.MnemonicModel.findById(mnemonicId).session(session ?? null);
+    }
+    /**
+     * Decrypts a mnemonic from a document using the service's master encryption key.
+     * @param doc The mnemonic document.
+     */
+    /**
+     * Deletes a mnemonic document by ID.
+     * @param mnemonicId The ID of the mnemonic document.
+     * @param session Optional Mongoose session for transaction support.
+     */
+    async deleteMnemonicDocument(mnemonicId, session) {
+        await this.MnemonicModel.findByIdAndDelete(mnemonicId).session(session ?? null);
+    }
+}
+exports.MnemonicService = MnemonicService;
+//# sourceMappingURL=mnemonic.js.map

package/src/services/mnemonic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mnemonic.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/mnemonic.ts"],"names":[],"mappings":"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"}

package/src/services/request-user.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Service for transforming user documents into request user DTOs and backend objects.
+ * Handles serialization and deserialization of user data for API requests and JWT tokens.
+ * @module services/request-user
+ */
+import { IRequestUserDTO, ITokenRole } from '@digitaldefiance/suite-core-lib';
+import { IUserDocument } from '../documents';
+import { IRequestUserBackendObject } from '../interfaces/backend-objects/request-user';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+/**
+ * Service for converting between user documents, DTOs, and backend objects.
+ * Provides transformation methods for user data in different contexts (API, JWT, database).
+ * @template TID Platform-specific ID type (Buffer, ObjectId, etc.)
+ * @template _TTokenRole Token role type implementing ITokenRole
+ */
+export declare class RequestUserService<TID extends PlatformID, _TTokenRole extends ITokenRole<TID>> {
+    /**
+     * Converts a user document and roles into a request user DTO for API responses.
+     * Calculates combined role privileges and serializes IDs to strings.
+     * @template TID Platform-specific ID type
+     * @template TLanguage Site language string literal type
+     * @template TTokenRole Token role type
+     * @template TRequestUserDTO Request user DTO type
+     * @param userDoc User document from database
+     * @param roles Array of token roles for the user
+     * @returns Request user DTO suitable for API responses
+     * @throws {Error} If user document is missing _id
+     */
+    static makeRequestUserDTO<TID extends PlatformID, TLanguage extends string, TTokenRole extends ITokenRole<TID>, TRequestUserDTO extends IRequestUserDTO>(userDoc: IUserDocument<TLanguage, TID> | (Pick<IUserDocument<TLanguage, TID>, keyof IUserDocument<TLanguage, TID>> & {
+        _id: PlatformID;
+    }), roles: TTokenRole[]): TRequestUserDTO;
+    /**
+     * Hydrates a request user DTO back into a backend object with typed IDs and dates.
+     * Converts string IDs to platform-specific types and reconstitutes Date objects.
+     * @template TID Platform-specific ID type
+     * @template TLanguage Site language string literal type
+     * @template TRequestUserDTO Request user DTO type with site language
+     * @param requestUser Request user DTO from API or JWT
+     * @returns Backend object with typed IDs and dates
+     */
+    static hydrateRequestUser<TID extends PlatformID, TLanguage extends string, TRequestUserDTO extends IRequestUserDTO & {
+        siteLanguage: TLanguage;
+    }>(requestUser: TRequestUserDTO): IRequestUserBackendObject<TLanguage, TID>;
+}
+//# sourceMappingURL=request-user.d.ts.map

package/src/services/request-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-user.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/request-user.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EAEf,UAAU,EACX,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAEvF,OAAO,EAEL,UAAU,EACX,MAAM,iCAAiC,CAAC;AAEzC;;;;;GAKG;AACH,qBAAa,kBAAkB,CAC7B,GAAG,SAAS,UAAU,EACtB,WAAW,SAAS,UAAU,CAAC,GAAG,CAAC;IAEnC;;;;;;;;;;;OAWG;WACW,kBAAkB,CAC9B,GAAG,SAAS,UAAU,EACtB,SAAS,SAAS,MAAM,EACxB,UAAU,SAAS,UAAU,CAAC,GAAG,CAAC,EAClC,eAAe,SAAS,eAAe,EAEvC,OAAO,EACH,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,GAC7B,CAAC,IAAI,CACH,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,EAC7B,MAAM,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,CACpC,GAAG;QACF,GAAG,EAAE,UAAU,CAAC;KACjB,CAAC,EACN,KAAK,EAAE,UAAU,EAAE,GAClB,eAAe;IA8BlB;;;;;;;;OAQG;WACW,kBAAkB,CAC9B,GAAG,SAAS,UAAU,EACtB,SAAS,SAAS,MAAM,EACxB,eAAe,SAAS,eAAe,GAAG;QAAE,YAAY,EAAE,SAAS,CAAA;KAAE,EACrE,WAAW,EAAE,eAAe,GAAG,yBAAyB,CAAC,SAAS,EAAE,GAAG,CAAC;CA2B3E"}