@digitaldefiance/node-express-suite 3.6.14 → 3.6.16

package/src/services/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./backup-code"), exports);
+tslib_1.__exportStar(require("./base"), exports);
+tslib_1.__exportStar(require("./checksum"), exports);
+tslib_1.__exportStar(require("./crc"), exports);
+tslib_1.__exportStar(require("./database-initialization"), exports);
+tslib_1.__exportStar(require("./db-init-cache"), exports);
+tslib_1.__exportStar(require("./direct-login-token"), exports);
+tslib_1.__exportStar(require("./dummy-email-service"), exports);
+tslib_1.__exportStar(require("./fec"), exports);
+tslib_1.__exportStar(require("./fec-usage-example"), exports);
+tslib_1.__exportStar(require("./jwt"), exports);
+tslib_1.__exportStar(require("./key-wrapping"), exports);
+tslib_1.__exportStar(require("./mnemonic"), exports);
+tslib_1.__exportStar(require("./request-user"), exports);
+tslib_1.__exportStar(require("./role"), exports);
+tslib_1.__exportStar(require("./symmetric"), exports);
+tslib_1.__exportStar(require("./system-user"), exports);
+tslib_1.__exportStar(require("./user"), exports);
+tslib_1.__exportStar(require("./xor"), exports);
+//# sourceMappingURL=index.js.map

package/src/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":";;;AAAA,wDAA8B;AAC9B,iDAAuB;AACvB,qDAA2B;AAC3B,gDAAsB;AACtB,oEAA0C;AAC1C,0DAAgC;AAChC,+DAAqC;AACrC,gEAAsC;AACtC,gDAAsB;AACtB,8DAAoC;AACpC,gDAAsB;AACtB,yDAA+B;AAC/B,qDAA2B;AAC3B,yDAA+B;AAC/B,iDAAuB;AACvB,sDAA4B;AAC5B,wDAA8B;AAC9B,iDAAuB;AACvB,gDAAsB"}

package/src/services/jwt.d.ts

@@ -0,0 +1,30 @@
+import { ITokenRole, ITokenUser } from '@digitaldefiance/suite-core-lib';
+import { Types } from '@digitaldefiance/mongoose-types';
+import { IUserDocument } from '../documents/user';
+import { IApplication } from '../interfaces/application';
+import { IJwtSignResponse } from '../interfaces/jwt-sign-response';
+import { BaseService } from './base';
+export declare class JwtService<I extends string | Types.ObjectId = Types.ObjectId, D extends Date = Date, TTokenRole extends ITokenRole<I, D> = ITokenRole<I, D>, TTokenUser extends ITokenUser = ITokenUser, TApplication extends IApplication = IApplication> extends BaseService {
+    private readonly roleService;
+    /**
+     * Constructor for the JWT service
+     * @param application The application object
+     */
+    constructor(application: TApplication);
+    /**
+     * Sign a JWT token for a user
+     * @param userDoc The user document to sign the token for
+     * @param jwtSecret The secret to sign the token with
+     * @param overrideLanguage Optional language to use for role translations
+     * @returns The signed token
+     */
+    signToken(userDoc: IUserDocument<string, I>, jwtSecret: string, overrideLanguage?: string): Promise<IJwtSignResponse<I, D, TTokenRole>>;
+    /**
+     * Verify a JWT token and return the user data
+     * @param token The token to verify
+     * @returns The user data
+     * @throws InvalidTokenError
+     */
+    verifyToken(token: string): Promise<TTokenUser | null>;
+}
+//# sourceMappingURL=jwt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,UAAU,EACX,MAAM,iCAAiC,CAAC;AASzC,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKlD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAUrC,qBAAa,UAAU,CACrB,CAAC,SAAS,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAClD,CAAC,SAAS,IAAI,GAAG,IAAI,EACrB,UAAU,SAAS,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACtD,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1C,YAAY,SAAS,YAAY,GAAG,YAAY,CAChD,SAAQ,WAAW;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAE5D;;;OAGG;gBACS,WAAW,EAAE,YAAY;IAKrC;;;;;;OAMG;IACU,SAAS,CACpB,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAgC9C;;;;;OAKG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAgCpE"}

package/src/services/jwt.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtService = void 0;
+const jsonwebtoken_1 = require("jsonwebtoken");
+const util_1 = require("util");
+const invalid_jwt_token_1 = require("../errors/invalid-jwt-token");
+const token_expired_1 = require("../errors/token-expired");
+const base_1 = require("./base");
+const role_1 = require("./role");
+const verifyAsync = (0, util_1.promisify)(jsonwebtoken_1.verify);
+class JwtService extends base_1.BaseService {
+    roleService;
+    /**
+     * Constructor for the JWT service
+     * @param application The application object
+     */
+    constructor(application) {
+        super(application);
+        this.roleService = new role_1.RoleService(application);
+    }
+    /**
+     * Sign a JWT token for a user
+     * @param userDoc The user document to sign the token for
+     * @param jwtSecret The secret to sign the token with
+     * @param overrideLanguage Optional language to use for role translations
+     * @returns The signed token
+     */
+    async signToken(userDoc, jwtSecret, overrideLanguage) {
+        // look for roles the user is a member of (the role contains the user id in the user's roles array)
+        const roles = await this.roleService.getUserRoles(userDoc._id);
+        const tokenRoles = this.roleService.rolesToTokenRoles(roles, overrideLanguage);
+        const tokenRoleDTOs = tokenRoles.map((role) => role_1.RoleService.roleToRoleDTO(role));
+        const roleTranslatedNames = tokenRoles.map((role) => role.translatedName);
+        const roleNames = tokenRoles.map((role) => role.name);
+        const tokenUser = {
+            userId: userDoc._id.toString(),
+            roles: tokenRoleDTOs,
+        };
+        // amazonq-ignore-next-line false positive
+        const token = (0, jsonwebtoken_1.sign)(tokenUser, jwtSecret, {
+            algorithm: this.application.constants.JWT.ALGORITHM,
+            allowInsecureKeySizes: false,
+            expiresIn: this.application.constants.JWT.EXPIRATION_SEC,
+        });
+        return {
+            token,
+            tokenUser,
+            roleNames,
+            roleTranslatedNames,
+            roles: tokenRoles,
+            roleDTOs: tokenRoleDTOs,
+        };
+    }
+    /**
+     * Verify a JWT token and return the user data
+     * @param token The token to verify
+     * @returns The user data
+     * @throws InvalidTokenError
+     */
+    async verifyToken(token) {
+        try {
+            const decoded = (await verifyAsync(token, this.application.environment.jwtSecret, {
+                algorithms: [this.application.constants.JWT.ALGORITHM],
+            }));
+            if (typeof decoded === 'object' &&
+                decoded !== null &&
+                'userId' in decoded &&
+                'roles' in decoded) {
+                return {
+                    userId: decoded['userId'],
+                    roles: decoded['roles'],
+                };
+            }
+            else {
+                return null;
+            }
+        }
+        catch (err) {
+            if (err instanceof jsonwebtoken_1.TokenExpiredError) {
+                throw new token_expired_1.TokenExpiredError();
+            }
+            else if (err instanceof jsonwebtoken_1.JsonWebTokenError) {
+                throw err;
+            }
+            throw new invalid_jwt_token_1.InvalidJwtTokenError();
+        }
+    }
+}
+exports.JwtService = JwtService;
+//# sourceMappingURL=jwt.js.map

package/src/services/jwt.js.map

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

package/src/services/key-wrapping.d.ts

@@ -0,0 +1,61 @@
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { IConstants } from '@digitaldefiance/node-ecies-lib';
+export interface WrappedKey {
+    salt: string;
+    iv: string;
+    authTag: string;
+    encryptedMasterKey: string;
+    iterations: number;
+}
+export interface PasswordWrappedSecret {
+    salt: string;
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+    iterations: number;
+}
+export declare class KeyWrappingService {
+    private static inFlightUnwraps;
+    /**
+     * Generates a new master key and wraps it with the user's password
+     */
+    wrapNewMasterKey(password: SecureString, constants?: IConstants): {
+        masterKey: SecureBuffer;
+        wrappedKey: WrappedKey;
+    };
+    /**
+     * Wraps an existing master key with a password-derived key
+     */
+    wrapMasterKey(masterKey: SecureBuffer, password: SecureString, constants?: IConstants): WrappedKey;
+    /**
+     * Unwraps a master key using the user's password
+     */
+    unwrapMasterKey(wrappedKey: WrappedKey, password: SecureString, constants?: IConstants): SecureBuffer;
+    /**
+     * Async version of unwrapMasterKey that uses libuv threadpool via crypto.pbkdf2
+     * to avoid blocking the event loop during password verification.
+     */
+    unwrapMasterKeyAsync(wrappedKey: WrappedKey, password: SecureString | string, constants?: IConstants): Promise<SecureBuffer>;
+    /**
+     * Deduplicated async unwrap that coalesces concurrent identical PBKDF2 operations.
+     * Keyed by salt + iterations + a short hash of the password. Entry is removed after resolve/reject.
+     */
+    unwrapMasterKeyAsyncDedup(wrappedKey: WrappedKey, password: string, constants?: IConstants): Promise<SecureBuffer>;
+    /**
+     * Changes password by re-wrapping the master key
+     */
+    changePassword(wrappedKey: WrappedKey, oldPassword: SecureString, newPassword: SecureString, constants?: IConstants): WrappedKey;
+    /**
+     * Wraps arbitrary secret bytes with a password-derived key (AES-256-GCM)
+     */
+    wrapSecret(secret: SecureBuffer, password: SecureString, constants?: IConstants): PasswordWrappedSecret;
+    /**
+     * Unwraps a password-wrapped secret (sync)
+     */
+    unwrapSecret(wrapped: PasswordWrappedSecret, password: SecureString, constants?: IConstants): SecureBuffer;
+    /**
+     * Unwraps a password-wrapped secret (async PBKDF2)
+     */
+    unwrapSecretAsync(wrapped: PasswordWrappedSecret, password: SecureString | string, constants?: IConstants): Promise<SecureBuffer>;
+}
+//# sourceMappingURL=key-wrapping.d.ts.map

package/src/services/key-wrapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-wrapping.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/key-wrapping.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAEL,UAAU,EAEX,MAAM,iCAAiC,CAAC;AAazC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,kBAAkB;IAG7B,OAAO,CAAC,MAAM,CAAC,eAAe,CAA2C;IAEzE;;OAEG;IACI,gBAAgB,CACrB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC;QACD,SAAS,EAAE,YAAY,CAAC;QACxB,UAAU,EAAE,UAAU,CAAC;KACxB;IAQD;;OAEG;IACI,aAAa,CAClB,SAAS,EAAE,YAAY,EACvB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,UAAU;IAyCb;;OAEG;IACI,eAAe,CACpB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,YAAY;IAuCf;;;OAGG;IACU,oBAAoB,CAC/B,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;IA6DxB;;;OAGG;IACU,yBAAyB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;IAuCxB;;OAEG;IACI,cAAc,CACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,SAAS,GAAE,UAAsB,GAChC,UAAU;IAcb;;OAEG;IACI,UAAU,CACf,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,qBAAqB;IAuCxB;;OAEG;IACI,YAAY,CACjB,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,YAAY;IAoCf;;OAEG;IACU,iBAAiB,CAC5B,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;CA+DzB"}

package/src/services/key-wrapping.js

@@ -0,0 +1,310 @@
+"use strict";
+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");
+function createPbkdf2Service(constants) {
+    return node_ecies_lib_1.Pbkdf2Service.fromConstants(constants);
+}
+class KeyWrappingService {
+    // In-flight de-duplication map to share PBKDF2 work across concurrent identical requests
+    // Store a promise of the raw master key bytes, so each caller can get an independent SecureBuffer
+    static inFlightUnwraps = new Map();
+    /**
+     * Generates a new master key and wraps it with the user's password
+     */
+    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
+     */
+    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
+     */
+    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.
+     */
+    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 + a short hash of the password. Entry is removed after resolve/reject.
+     */
+    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
+     */
+    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);
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            masterKey.dispose();
+        }
+    }
+    /**
+     * Wraps arbitrary secret bytes with a password-derived key (AES-256-GCM)
+     */
+    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 (sync)
+     */
+    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 (async PBKDF2)
+     */
+    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,61 @@
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { ClientSession, Model, Types } from '@digitaldefiance/mongoose-types';
+import { IMnemonicDocument } from '../documents/mnemonic';
+import { IConstants } from '../interfaces';
+/**
+ * Encrypts and stores mnemonics securely, using an HMAC to check for
+ * uniqueness without exposing the mnemonic itself.
+ */
+export declare class MnemonicService<I extends string | Types.ObjectId = Types.ObjectId> {
+    private readonly hmacSecret;
+    private readonly MnemonicModel;
+    private readonly constants;
+    constructor(mnemonicModel: Model<IMnemonicDocument<I>>, 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<I> | 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<I> | 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: I, session?: ClientSession): Promise<IMnemonicDocument<I> | 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: I, 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,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAMxE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;GAGG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ;IAC7E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;gBAGrC,aAAa,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAC1C,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,CAAC,CAAC,GAAG,IAAI,CAAC;KACvC,CAAC;IA2BF;;;;OAIG;IACU,WAAW,CACtB,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAsBvC;;;;OAIG;IACU,mBAAmB,CAC9B,UAAU,EAAE,CAAC,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAMvC;;;OAGG;IAEH;;;;OAIG;IACU,sBAAsB,CACjC,UAAU,EAAE,CAAC,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;CAKjB"}