@digitaldefiance/node-express-suite 3.7.5 → 3.8.0

package/src/application.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * @fileoverview Main application class with Express server.
+ * Extends BaseApplication with HTTP/HTTPS server and routing.
+ * @module application
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Application = void 0;
+const tslib_1 = require("tslib");
+const i18n_lib_1 = require("@digitaldefiance/i18n-lib");
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const express_1 = tslib_1.__importDefault(require("express"));
+const fs_1 = require("fs");
+const https_1 = require("https");
+const path_1 = require("path");
+const application_base_1 = require("./application-base");
+const interfaces_1 = require("./interfaces");
+const flexible_csp_1 = require("./interfaces/flexible-csp");
+const middleware_utils_1 = require("./middleware-utils");
+const app_1 = require("./routers/app");
+const services_1 = require("./services");
+const utils_1 = require("./utils");
+class Application extends application_base_1.BaseApplication {
+    expressApp;
+    server = null;
+    _cspConfig;
+    _apiRouterFactory;
+    _appRouterFactory;
+    _initMiddleware;
+    _apiRouter;
+    get environment() {
+        return super.environment;
+    }
+    registerServices() {
+        // Services will be registered by subclasses or ApiRouter
+        // Base implementation does nothing
+    }
+    constructor(environment, apiRouterFactory, schemaMapFactory, databaseInitFunction, initResultHashFunction, cspConfig = {
+        corsWhitelist: [],
+        csp: {
+            defaultSrc: [],
+            imgSrc: [],
+            connectSrc: [],
+            scriptSrc: [],
+            styleSrc: [],
+            fontSrc: [],
+            frameSrc: [],
+        },
+    }, constants = suite_core_lib_1.Constants, appRouterFactory = (apiRouter) => new app_1.AppRouter(apiRouter), customInitMiddleware = middleware_utils_1.initMiddleware) {
+        super(environment, schemaMapFactory, databaseInitFunction, initResultHashFunction, constants);
+        this._apiRouterFactory = apiRouterFactory;
+        this._appRouterFactory = appRouterFactory;
+        this._initMiddleware = customInitMiddleware;
+        this.expressApp = (0, express_1.default)();
+        this.server = null;
+        this._cspConfig = cspConfig;
+        this.registerServices();
+    }
+    async start(mongoUri) {
+        const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)({ constants: this.constants });
+        await super.start(mongoUri, true);
+        if (this.devDatabase) {
+            const result = await this.initializeDevDatabase();
+            services_1.DatabaseInitializationService.printServerInitResults(result, false);
+        }
+        try {
+            this._apiRouter = this._apiRouterFactory(this);
+            if ((0, flexible_csp_1.isFlexibleCSP)(this._cspConfig) || (0, interfaces_1.isCSPConfig)(this._cspConfig)) {
+                this._initMiddleware(this.expressApp, this._cspConfig.corsWhitelist, this._cspConfig.csp);
+            }
+            else if ((0, middleware_utils_1.isHelmetOptions)(this._cspConfig)) {
+                this._initMiddleware(this.expressApp, [], this._cspConfig);
+            }
+            const appRouter = this._appRouterFactory(this._apiRouter);
+            appRouter.init(this.expressApp);
+            this.expressApp.use((err, req, res, _next) => {
+                if (res.headersSent ||
+                    err
+                        ._errorHandlerProcessing) {
+                    return;
+                }
+                err._errorHandlerProcessing = true;
+                const safeHandle = () => {
+                    try {
+                        const handleableError = err instanceof i18n_lib_1.HandleableError
+                            ? err
+                            : new i18n_lib_1.HandleableError(err instanceof Error ? err : new Error(String(err)), { cause: err });
+                        (0, utils_1.handleError)(handleableError, res, utils_1.sendApiMessageResponse, () => { });
+                    }
+                    catch {
+                        res.status(500).json({
+                            message: engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Error_RecursiveErrorHandlingDetected),
+                            error: {
+                                message: err instanceof Error
+                                    ? err.message
+                                    : engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_UnexpectedError),
+                            },
+                        });
+                    }
+                };
+                setImmediate(safeHandle);
+            });
+            const serversReady = [];
+            serversReady.push(new Promise((resolve) => {
+                this.server = this.expressApp.listen(this.environment.port, this.environment.host, () => {
+                    (0, utils_1.debugLog)(this.environment.debug, 'log', `[ ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_Ready)} ] http://${this.environment.host}:${this.environment.port}`);
+                    resolve();
+                });
+            }));
+            if (this.environment.httpsDevCertRoot) {
+                try {
+                    const certRoot = (0, path_1.normalize)(this.environment.httpsDevCertRoot);
+                    if (!(0, path_1.isAbsolute)(certRoot) || certRoot.includes('..')) {
+                        throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_InvalidCertificatePathMustBeAbsolute);
+                    }
+                    const certPath = (0, path_1.normalize)((0, path_1.resolve)(certRoot + '.pem'));
+                    const keyPath = (0, path_1.normalize)((0, path_1.resolve)(certRoot + '-key.pem'));
+                    if (certPath.includes('..') || keyPath.includes('..')) {
+                        throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_InvalidCertificatePathAfterResolution);
+                    }
+                    const options = {
+                        // amazonq-ignore-next-line fixed above
+                        key: (0, fs_1.readFileSync)(keyPath),
+                        // amazonq-ignore-next-line fixed above
+                        cert: (0, fs_1.readFileSync)(certPath),
+                    };
+                    serversReady.push(new Promise((resolve) => {
+                        (0, https_1.createServer)(options, this.expressApp).listen(this.environment.httpsDevPort, this.environment.host, () => {
+                            console.log(`[ ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_Ready)} ] https://${this.environment.host}:${this.environment.httpsDevPort}`);
+                            resolve();
+                        });
+                    }));
+                }
+                catch (err) {
+                    console.error('Failed to start HTTPS server:', err);
+                }
+            }
+            await Promise.all(serversReady);
+            this._ready = true;
+        }
+        catch (err) {
+            console.error(engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Error_FailedToStartApplication), err);
+            if (process.env['NODE_ENV'] === 'test') {
+                throw err;
+            }
+            process.exit(1);
+        }
+    }
+    async stop() {
+        const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)({ constants: this.constants });
+        if (this.server) {
+            (0, utils_1.debugLog)(this.environment.debug, 'log', `[ ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_Stopping)} ] ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_ApplicationAndDatabase)}`);
+            await new Promise((resolve, reject) => {
+                this.server.closeAllConnections?.();
+                this.server.close((err) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            this.server = null;
+        }
+        await super.stop();
+        this._ready = false;
+        (0, utils_1.debugLog)(this.environment.debug, 'log', `[ ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_Stopped)} ] ${engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_ApplicationAndDatabase)}`);
+    }
+}
+exports.Application = Application;
+//# sourceMappingURL=application.js.map

package/src/application.js.map

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

package/src/backup-code.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Backup code implementation with v1.0.0 encryption scheme.
+ * Provides secure backup code generation, encryption, validation using Argon2id and HKDF-SHA256.
+ * @module backup-code
+ */
+import { Member as BackendMember, PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { BackupCodeString, IBackupCode } from '@digitaldefiance/suite-core-lib';
+import { IConstants } from './interfaces';
+/**
+ * Class representing a backup code string with associated operations.
+ *
+ * v1 scheme:
+ * - Code: 32 lowercase alphanumerics (a–z0–9), displayed as 8 groups of 4: xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+ * - Checksum/tag: HKDF-SHA256(codeUtf8, salt, "backup-checksum") → 32 bytes (stored as hex)
+ * - KDF for encryption key: Argon2id(codeUtf8, salt) → 32 bytes
+ * - Encryption: SymmetricService AEAD (encryptedData must embed IV + authTag + ciphertext)
+ * - Wrapping: AEAD blob wrapped with system user's asymmetric key (ECIES)
+ */
+export declare class BackupCode extends BackupCodeString {
+    /** Current backup code scheme version implemented by this service. */
+    static readonly BackupCodeVersion = "1.0.0";
+    private static readonly Argon2Params;
+    constructor(code: string);
+    /**
+     * Generate the configured number of backup codes.
+     * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
+     */
+    static generateBackupCodes(constants?: IConstants): Array<BackupCode>;
+    /**
+     * HKDF-Extract-and-Expand using HMAC-SHA-256.
+     *
+     * PRK = HMAC(salt, ikm)
+     * T(0) = empty
+     * T(i) = HMAC(PRK, T(i-1) || info || i)
+     * OKM = first 'length' bytes of T(1) || T(2) || ...
+     */
+    static hkdfSha256(ikm: Buffer, salt: Buffer, info: Buffer, length: number): Buffer;
+    /**
+     * v1: Derive a 32-byte encryption key from a normalized backup code using Argon2id and the per-code salt.
+     * Uses UTF-8 bytes of the normalized code (not hex).
+     */
+    static getBackupKeyV1(checksumSaltHex: string, normalizedCode: string, constants?: IConstants): Promise<Buffer>;
+    /**
+     * v1: Compute a 32-byte checksum/tag for a normalized code using HKDF-SHA256(codeUtf8, salt, "backup-checksum").
+     */
+    private static computeChecksumV1;
+    encrypt<TID extends PlatformID = Buffer>(backupUser: BackendMember<TID>, systemUser: BackendMember<TID>, constants?: IConstants): Promise<IBackupCode>;
+    /**
+     * v1: Encrypt and wrap backup codes for a user.
+     * - Validates code format (display or normalized)
+     * - Computes HKDF checksum/tag
+     * - Derives Argon2id encryption key (32 bytes) from UTF-8 code
+     * - Encrypts the private key with AEAD and wraps with system user
+     */
+    static encryptBackupCodesV1<TID extends PlatformID = Buffer>(backupUser: BackendMember<TID>, systemUser: BackendMember<TID>, codes: Array<BackupCode>): Promise<Array<IBackupCode>>;
+    /** Delegate to current version. */
+    static encryptBackupCodes<TID extends PlatformID = Buffer>(backupUser: BackendMember<TID>, systemUser: BackendMember<TID>, codes: Array<BackupCode>): Promise<Array<IBackupCode>>;
+    /**
+     * v1: Validate whether a backup code exists (unused) in the provided collection.
+     * Uses constant-time comparison of binary checksums (codeUtf8 + salt).
+     */
+    static validateBackupCodeV1(encryptedBackupCodes: Array<IBackupCode>, backupCode: string, constants?: IConstants): boolean;
+    /**
+     * Validate a backup code against any supported version present in the collection.
+     */
+    static validateBackupCode(encryptedBackupCodes: Array<IBackupCode>, backupCode: string, constants?: IConstants): boolean;
+    /**
+     * Detect the version by matching checksum against stored codes; returns the matched version.
+     */
+    static detectBackupCodeVersion(encryptedBackupCodes: Array<IBackupCode>, backupCode: string, constants?: IConstants): string;
+}
+//# sourceMappingURL=backup-code.d.ts.map

package/src/backup-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-code.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-node-express-suite/src/backup-code.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAEL,MAAM,IAAI,aAAa,EACvB,UAAU,EACX,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,WAAW,EAKZ,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,gBAAgB;IAC9C,sEAAsE;IACtE,gBAAuB,iBAAiB,WAAW;IAEnD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAOzB;gBAEC,IAAI,EAAE,MAAM;IAIxB;;;OAGG;WACoB,mBAAmB,CACxC,SAAS,GAAE,UAA+B,GACzC,KAAK,CAAC,UAAU,CAAC;IAQpB;;;;;;;OAOG;WACW,UAAU,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM;IA2BT;;;OAGG;WACiB,cAAc,CAChC,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,UAA+B,GACzC,OAAO,CAAC,MAAM,CAAC;IAiBlB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAiBnB,OAAO,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM,EAClD,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,SAAS,GAAE,UAA+B,GACzC,OAAO,CAAC,WAAW,CAAC;IAiDvB;;;;;;OAMG;WACiB,oBAAoB,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM,EACtE,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAQ9B,mCAAmC;WACrB,kBAAkB,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM,EAC9D,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,EAC9B,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAI9B;;;OAGG;WACW,oBAAoB,CAChC,oBAAoB,EAAE,KAAK,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,UAA+B,GACzC,OAAO;IA6BV;;OAEG;WACW,kBAAkB,CAC9B,oBAAoB,EAAE,KAAK,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,UAA+B,GACzC,OAAO;IAoBV;;OAEG;WACW,uBAAuB,CACnC,oBAAoB,EAAE,KAAK,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,UAA+B,GACzC,MAAM;CA0CV"}

package/src/backup-code.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * @fileoverview Backup code implementation with v1.0.0 encryption scheme.
+ * Provides secure backup code generation, encryption, validation using Argon2id and HKDF-SHA256.
+ * @module backup-code
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackupCode = void 0;
+const tslib_1 = require("tslib");
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const node_ecies_lib_1 = require("@digitaldefiance/node-ecies-lib");
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const argon2 = tslib_1.__importStar(require("argon2"));
+const crypto_1 = require("crypto");
+const constants_1 = require("./constants");
+const invalid_backup_code_version_1 = require("./errors/invalid-backup-code-version");
+const symmetric_1 = require("./services/symmetric");
+/**
+ * Class representing a backup code string with associated operations.
+ *
+ * v1 scheme:
+ * - Code: 32 lowercase alphanumerics (a–z0–9), displayed as 8 groups of 4: xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+ * - Checksum/tag: HKDF-SHA256(codeUtf8, salt, "backup-checksum") → 32 bytes (stored as hex)
+ * - KDF for encryption key: Argon2id(codeUtf8, salt) → 32 bytes
+ * - Encryption: SymmetricService AEAD (encryptedData must embed IV + authTag + ciphertext)
+ * - Wrapping: AEAD blob wrapped with system user's asymmetric key (ECIES)
+ */
+class BackupCode extends suite_core_lib_1.BackupCodeString {
+    /** Current backup code scheme version implemented by this service. */
+    static BackupCodeVersion = '1.0.0';
+    // Centralized Argon2id parameters (tunable)
+    static Argon2Params = {
+        type: argon2.argon2id,
+        hashLength: 32, // derive AES-256 key
+        timeCost: 3,
+        memoryCost: 65536, // 64 MiB
+        parallelism: 1,
+        raw: true,
+    };
+    constructor(code) {
+        super(code);
+    }
+    /**
+     * Generate the configured number of backup codes.
+     * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
+     */
+    static generateBackupCodes(constants = constants_1.LocalhostConstants) {
+        const codes = [];
+        for (let i = 0; i < constants.BACKUP_CODES.Count; i++) {
+            codes.push(new BackupCode(BackupCode.generateBackupCode()));
+        }
+        return codes;
+    }
+    /**
+     * HKDF-Extract-and-Expand using HMAC-SHA-256.
+     *
+     * PRK = HMAC(salt, ikm)
+     * T(0) = empty
+     * T(i) = HMAC(PRK, T(i-1) || info || i)
+     * OKM = first 'length' bytes of T(1) || T(2) || ...
+     */
+    static hkdfSha256(ikm, salt, info, length) {
+        if (length === 0) {
+            return Buffer.alloc(0);
+        }
+        // HKDF-Extract: PRK = HMAC-Hash(salt, IKM)
+        // If salt is empty, use a string of HashLen zeros
+        const actualSalt = salt.length === 0 ? Buffer.alloc(32, 0) : salt;
+        const prk = (0, crypto_1.createHmac)('sha256', actualSalt).update(ikm).digest();
+        // HKDF-Expand
+        const blocks = [];
+        let prev = Buffer.alloc(0);
+        const n = Math.ceil(length / 32);
+        for (let i = 1; i <= n; i++) {
+            const hmac = (0, crypto_1.createHmac)('sha256', prk);
+            hmac.update(prev);
+            hmac.update(info);
+            hmac.update(Buffer.from([i]));
+            prev = Buffer.from(hmac.digest());
+            blocks.push(prev);
+        }
+        return Buffer.concat(blocks).subarray(0, length);
+    }
+    /**
+     * v1: Derive a 32-byte encryption key from a normalized backup code using Argon2id and the per-code salt.
+     * Uses UTF-8 bytes of the normalized code (not hex).
+     */
+    static async getBackupKeyV1(checksumSaltHex, normalizedCode, constants = constants_1.LocalhostConstants) {
+        if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+            throw new suite_core_lib_1.InvalidBackupCodeError();
+        }
+        const codeBytes = Buffer.from(normalizedCode, 'utf8');
+        const checksumSalt = Buffer.from(checksumSaltHex, 'hex');
+        try {
+            const key = (await argon2.hash(codeBytes, {
+                ...BackupCode.Argon2Params,
+                salt: checksumSalt,
+            }));
+            return key; // 32-byte Buffer
+        }
+        finally {
+            codeBytes.fill(0);
+        }
+    }
+    /**
+     * v1: Compute a 32-byte checksum/tag for a normalized code using HKDF-SHA256(codeUtf8, salt, "backup-checksum").
+     */
+    static computeChecksumV1(normalizedCode, checksumSalt) {
+        const codeBytes = Buffer.from(normalizedCode, 'utf8');
+        try {
+            return BackupCode.hkdfSha256(codeBytes, checksumSalt, Buffer.from('backup-checksum'), 32);
+        }
+        finally {
+            codeBytes.fill(0);
+        }
+    }
+    async encrypt(backupUser, systemUser, constants = constants_1.LocalhostConstants) {
+        if (!backupUser.hasPrivateKey) {
+            throw new suite_core_lib_1.PrivateKeyRequiredError();
+        }
+        if (systemUser.type !== ecies_lib_1.MemberType.System) {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_SystemUserMustBeSystemMemberType);
+        }
+        const raw = this.value ?? '';
+        const normalized = BackupCode.normalizeCode(raw);
+        if (!(constants.BACKUP_CODES.DisplayRegex.test(raw) ||
+            constants.BACKUP_CODES.NormalizedHexRegex.test(normalized))) {
+            throw new suite_core_lib_1.InvalidBackupCodeError();
+        }
+        const checksumSalt = (0, crypto_1.randomBytes)(node_ecies_lib_1.Constants.PBKDF2.SALT_BYTES);
+        const checksumBuf = BackupCode.computeChecksumV1(normalized, checksumSalt);
+        const encryptionKey = await BackupCode.getBackupKeyV1(checksumSalt.toString('hex'), normalized, constants);
+        try {
+            const sealed = symmetric_1.SymmetricService.encryptBuffer(Buffer.from(backupUser.privateKey.value), encryptionKey);
+            const wrappedEncryptedPrivateKey = systemUser
+                .encryptData(sealed.encryptedData)
+                .toString('hex');
+            return {
+                version: BackupCode.BackupCodeVersion,
+                checksumSalt: checksumSalt.toString('hex'),
+                checksum: checksumBuf.toString('hex'),
+                encrypted: wrappedEncryptedPrivateKey,
+            };
+        }
+        finally {
+            encryptionKey.fill(0);
+            checksumBuf.fill(0);
+        }
+    }
+    /**
+     * v1: Encrypt and wrap backup codes for a user.
+     * - Validates code format (display or normalized)
+     * - Computes HKDF checksum/tag
+     * - Derives Argon2id encryption key (32 bytes) from UTF-8 code
+     * - Encrypts the private key with AEAD and wraps with system user
+     */
+    static async encryptBackupCodesV1(backupUser, systemUser, codes) {
+        const encryptedCodes = [];
+        for (const code of codes) {
+            encryptedCodes.push(await code.encrypt(backupUser, systemUser));
+        }
+        return encryptedCodes;
+    }
+    /** Delegate to current version. */
+    static encryptBackupCodes(backupUser, systemUser, codes) {
+        return BackupCode.encryptBackupCodesV1(backupUser, systemUser, codes);
+    }
+    /**
+     * v1: Validate whether a backup code exists (unused) in the provided collection.
+     * Uses constant-time comparison of binary checksums (codeUtf8 + salt).
+     */
+    static validateBackupCodeV1(encryptedBackupCodes, backupCode, constants = constants_1.LocalhostConstants) {
+        const normalizedCode = suite_core_lib_1.BackupCodeString.normalizeCode(backupCode);
+        if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+            return false;
+        }
+        const codeBytes = Buffer.from(normalizedCode, 'utf8');
+        try {
+            for (const code of encryptedBackupCodes) {
+                if (code.version !== BackupCode.BackupCodeVersion)
+                    continue;
+                const checksumSalt = Buffer.from(code.checksumSalt, 'hex');
+                const expected = BackupCode.hkdfSha256(codeBytes, checksumSalt, Buffer.from('backup-checksum'), 32);
+                if (code.checksum.length === expected.length * 2 &&
+                    (0, crypto_1.timingSafeEqual)(Buffer.from(code.checksum, 'hex'), expected)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        finally {
+            codeBytes.fill(0);
+        }
+    }
+    /**
+     * Validate a backup code against any supported version present in the collection.
+     */
+    static validateBackupCode(encryptedBackupCodes, backupCode, constants = constants_1.LocalhostConstants) {
+        const normalizedCode = suite_core_lib_1.BackupCodeString.normalizeCode(backupCode);
+        if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+            return false;
+        }
+        if (encryptedBackupCodes.some((c) => c.version === BackupCode.BackupCodeVersion)) {
+            return this.validateBackupCodeV1(encryptedBackupCodes.filter((c) => c.version === BackupCode.BackupCodeVersion), normalizedCode);
+        }
+        return false;
+    }
+    /**
+     * Detect the version by matching checksum against stored codes; returns the matched version.
+     */
+    static detectBackupCodeVersion(encryptedBackupCodes, backupCode, constants = constants_1.LocalhostConstants) {
+        const normalizedCode = suite_core_lib_1.BackupCodeString.normalizeCode(backupCode);
+        if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+            throw new suite_core_lib_1.InvalidBackupCodeError();
+        }
+        const v1Set = encryptedBackupCodes.filter((c) => c.version === BackupCode.BackupCodeVersion);
+        if (v1Set.length) {
+            const codeBytes = Buffer.from(normalizedCode, 'utf8');
+            try {
+                for (const c of v1Set) {
+                    const checksumSalt = Buffer.from(c.checksumSalt, 'hex');
+                    const expected = BackupCode.hkdfSha256(codeBytes, checksumSalt, Buffer.from('backup-checksum'), 32);
+                    if (c.checksum.length === expected.length * 2 &&
+                        (0, crypto_1.timingSafeEqual)(Buffer.from(c.checksum, 'hex'), expected)) {
+                        return c.version;
+                    }
+                }
+            }
+            finally {
+                // zeroize
+                codeBytes.fill(0);
+            }
+        }
+        const versionsInSet = new Set(encryptedBackupCodes.map((c) => c.version));
+        if (versionsInSet.size > 0 &&
+            !versionsInSet.has(BackupCode.BackupCodeVersion)) {
+            throw new invalid_backup_code_version_1.InvalidBackupCodeVersionError([...versionsInSet][0]);
+        }
+        throw new suite_core_lib_1.InvalidBackupCodeError();
+    }
+}
+exports.BackupCode = BackupCode;
+//# sourceMappingURL=backup-code.js.map

package/src/backup-code.js.map

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

package/src/builders/application-builder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Application builder for fluent application construction.
+ * Provides builder pattern for creating Application instances.
+ * @module builders/application-builder
+ */
+import mongoose from '@digitaldefiance/mongoose-types';
+import { HelmetOptions } from 'helmet';
+import { Application } from '../application';
+import { BaseApplication } from '../application-base';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { ICSPConfig, IFailableResult, IServerInitResult } from '../interfaces';
+import { IConstants } from '../interfaces/constants';
+import { IFlexibleCSP } from '../interfaces/flexible-csp';
+import { initMiddleware } from '../middleware-utils';
+import { AppRouter } from '../routers/app';
+import { BaseRouter } from '../routers/base';
+import { SchemaMap } from '../types';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+/**
+ * Builder for constructing Application instances with fluent API.
+ * @template TID - Platform ID type
+ * @template TModelDocs - Model documents type
+ * @template TInitResults - Initialization results type
+ * @template TConstants - Constants type (defaults to IConstants)
+ */
+export declare class ApplicationBuilder<TID extends PlatformID, TModelDocs extends Record<string, IBaseDocument<any, TID>>, TInitResults extends IServerInitResult<TID>, TConstants extends IConstants = IConstants> {
+    private environment?;
+    private apiRouterFactory?;
+    private appRouterFactory?;
+    private schemaMapFactory?;
+    private databaseInitFunction?;
+    private initResultHashFunction?;
+    private cspConfig?;
+    private constants?;
+    private customInitMiddleware?;
+    withEnvironment(env: Environment<TID>): this;
+    withApiRouter(factory: (app: any) => BaseRouter<TID>): this;
+    withAppRouter(factory: (apiRouter: BaseRouter<TID>) => AppRouter<TID>): this;
+    withSchemaMap(factory: (connection: mongoose.Connection) => SchemaMap<TID, TModelDocs>): this;
+    withDatabaseInit(initFn: (app: BaseApplication<TID, TModelDocs, TInitResults>) => Promise<IFailableResult<TInitResults>>, hashFn: (results: TInitResults) => string): this;
+    withCSP(config: ICSPConfig | HelmetOptions | IFlexibleCSP): this;
+    withConstants(constants: TConstants): this;
+    withMiddleware(middleware: typeof initMiddleware): this;
+    build(): Application<TInitResults, TModelDocs, TID, Environment<TID>, TConstants, AppRouter<TID>>;
+}
+//# sourceMappingURL=application-builder.d.ts.map

package/src/builders/application-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-builder.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/builders/application-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AAKvD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAEL,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE;;;;;;GAMG;AACH,qBAAa,kBAAkB,CAC7B,GAAG,SAAS,UAAU,EACtB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAC1D,YAAY,SAAS,iBAAiB,CAAC,GAAG,CAAC,EAC3C,UAAU,SAAS,UAAU,GAAG,UAAU;IAE1C,OAAO,CAAC,WAAW,CAAC,CAAmB;IACvC,OAAO,CAAC,gBAAgB,CAAC,CAA8C;IACvE,OAAO,CAAC,gBAAgB,CAAC,CAAiD;IAC1E,OAAO,CAAC,gBAAgB,CAAC,CAEO;IAChC,OAAO,CAAC,oBAAoB,CAAC,CAEe;IAC5C,OAAO,CAAC,sBAAsB,CAAC,CAAoC;IACnE,OAAO,CAAC,SAAS,CAAC,CAA4C;IAC9D,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAwB;IAErD,eAAe,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI;IAK5C,aAAa,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI;IAK3D,aAAa,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI;IAK5E,aAAa,CACX,OAAO,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,GACvE,IAAI;IAKP,gBAAgB,CACd,MAAM,EAAE,CACN,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,YAAY,CAAC,KAChD,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,EAC3C,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,GACxC,IAAI;IAMP,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,IAAI;IAKhE,aAAa,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;IAK1C,cAAc,CAAC,UAAU,EAAE,OAAO,cAAc,GAAG,IAAI;IAKvD,KAAK,IAAI,WAAW,CAClB,YAAY,EACZ,UAAU,EACV,GAAG,EACH,WAAW,CAAC,GAAG,CAAC,EAChB,UAAU,EACV,SAAS,CAAC,GAAG,CAAC,CACf;CAkCF"}

package/src/builders/application-builder.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * @fileoverview Application builder for fluent application construction.
+ * Provides builder pattern for creating Application instances.
+ * @module builders/application-builder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplicationBuilder = void 0;
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const application_1 = require("../application");
+/**
+ * Builder for constructing Application instances with fluent API.
+ * @template TID - Platform ID type
+ * @template TModelDocs - Model documents type
+ * @template TInitResults - Initialization results type
+ * @template TConstants - Constants type (defaults to IConstants)
+ */
+class ApplicationBuilder {
+    environment;
+    apiRouterFactory;
+    appRouterFactory;
+    schemaMapFactory;
+    databaseInitFunction;
+    initResultHashFunction;
+    cspConfig;
+    constants;
+    customInitMiddleware;
+    withEnvironment(env) {
+        this.environment = env;
+        return this;
+    }
+    withApiRouter(factory) {
+        this.apiRouterFactory = factory;
+        return this;
+    }
+    withAppRouter(factory) {
+        this.appRouterFactory = factory;
+        return this;
+    }
+    withSchemaMap(factory) {
+        this.schemaMapFactory = factory;
+        return this;
+    }
+    withDatabaseInit(initFn, hashFn) {
+        this.databaseInitFunction = initFn;
+        this.initResultHashFunction = hashFn;
+        return this;
+    }
+    withCSP(config) {
+        this.cspConfig = config;
+        return this;
+    }
+    withConstants(constants) {
+        this.constants = constants;
+        return this;
+    }
+    withMiddleware(middleware) {
+        this.customInitMiddleware = middleware;
+        return this;
+    }
+    build() {
+        if (!this.environment)
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_EnvironmentIsRequired);
+        if (!this.apiRouterFactory)
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_ApiRouterFactoryIsRequired);
+        if (!this.schemaMapFactory)
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_SchemaMapFactoryIsRequired);
+        if (!this.databaseInitFunction)
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_DatabaseInitFunctionIsRequired);
+        if (!this.initResultHashFunction)
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_InitResultHashFunctionIsRequired);
+        return new application_1.Application(this.environment, this.apiRouterFactory, this.schemaMapFactory, this.databaseInitFunction, this.initResultHashFunction, this.cspConfig, this.constants, this.appRouterFactory, this.customInitMiddleware);
+    }
+}
+exports.ApplicationBuilder = ApplicationBuilder;
+//# sourceMappingURL=application-builder.js.map