@digitaldefiance/node-express-suite 1.0.23 → 1.0.24

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,67 @@
+import { Member as BackendMember } 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(backupUser: BackendMember, systemUser: BackendMember, 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(backupUser: BackendMember, systemUser: BackendMember, codes: Array<BackupCode>): Promise<Array<IBackupCode>>;
+    /** Delegate to current version. */
+    static encryptBackupCodes(backupUser: BackendMember, systemUser: BackendMember, 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":"AACA,OAAO,EAEL,MAAM,IAAI,aAAa,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,WAAW,EAGZ,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,UAAsB,GAChC,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,UAAsB,GAChC,OAAO,CAAC,MAAM,CAAC;IAiBlB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAiBnB,OAAO,CAClB,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,EACzB,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,WAAW,CAAC;IA8CvB;;;;;;OAMG;WACiB,oBAAoB,CACtC,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,EACzB,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,GACvB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAQ9B,mCAAmC;WACrB,kBAAkB,CAC9B,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,EACzB,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,UAAsB,GAChC,OAAO;IA6BV;;OAEG;WACW,kBAAkB,CAC9B,oBAAoB,EAAE,KAAK,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,UAAsB,GAChC,OAAO;IAoBV;;OAEG;WACW,uBAAuB,CACnC,oBAAoB,EAAE,KAAK,CAAC,WAAW,CAAC,EACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,UAAsB,GAChC,MAAM;CA0CV"}

package/src/backup-code.js

@@ -0,0 +1,238 @@
+"use strict";
+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.Constants) {
+        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.Constants) {
+        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.Constants) {
+        if (!backupUser.hasPrivateKey) {
+            throw new suite_core_lib_1.PrivateKeyRequiredError();
+        }
+        if (systemUser.type !== ecies_lib_1.MemberType.System) {
+            throw new Error('System user must be of MemberType.System');
+        }
+        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);
+        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.Constants) {
+        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.Constants) {
+        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.Constants) {
+        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/constants.d.ts

@@ -0,0 +1,16 @@
+import { IFECConsts } from './interfaces';
+import { IChecksumConsts } from './interfaces/checksum-consts';
+import { IConstants } from './interfaces/constants';
+import { IJwtConsts } from './interfaces/jwt-consts';
+/**
+ * Constants for checksum operations
+ * These values are critical for data integrity and MUST NOT be changed
+ * in an already established system as it will break all existing checksums.
+ */
+export declare const CHECKSUM: IChecksumConsts;
+export declare const JWT: IJwtConsts;
+export declare const FEC: IFECConsts;
+export declare const ECIES: Readonly<import("@digitaldefiance/ecies-lib").IECIESConstants>;
+export declare const createExpressConstants: (siteDomain: string, overrides?: Partial<IConstants>) => IConstants;
+export declare const Constants: IConstants;
+//# sourceMappingURL=constants.d.ts.map

package/src/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-node-express-suite/src/constants.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,eAYZ,CAAC;AAEZ,eAAO,MAAM,GAAG,EAAE,UAUR,CAAC;AAEX,eAAO,MAAM,GAAG,EAAE,UAKR,CAAC;AAGX,eAAO,MAAM,KAAK,gEAA+B,CAAC;AAElD,eAAO,MAAM,sBAAsB,GACjC,YAAY,MAAM,EAClB,YAAY,OAAO,CAAC,UAAU,CAAC,KAC9B,UAQF,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAAgD,CAAC"}

package/src/constants.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Constants = exports.createExpressConstants = exports.ECIES = exports.FEC = exports.JWT = exports.CHECKSUM = void 0;
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+/**
+ * Constants for checksum operations
+ * These values are critical for data integrity and MUST NOT be changed
+ * in an already established system as it will break all existing checksums.
+ */
+exports.CHECKSUM = Object.freeze({
+    /** Default hash bits for SHA3 */
+    SHA3_DEFAULT_HASH_BITS: 512,
+    /** Length of a SHA3 checksum buffer in bytes */
+    SHA3_BUFFER_LENGTH: 64,
+    /** algorithm to use for checksum */
+    ALGORITHM: 'sha3-512',
+    /** encoding to use for checksum */
+    ENCODING: 'hex',
+});
+exports.JWT = {
+    /**
+     * Algorithm to use for JWT
+     */
+    ALGORITHM: 'HS256',
+    /**
+     * The expiration time for a JWT token in seconds
+     */
+    EXPIRATION_SEC: 86400,
+};
+exports.FEC = {
+    /**
+     * Maximum size of a single shard
+     */
+    MAX_SHARD_SIZE: 1048576,
+};
+// use defaults from ecies-lib
+exports.ECIES = Object.freeze(ecies_lib_1.ECIES);
+const createExpressConstants = (siteDomain, overrides) => {
+    return Object.freeze({
+        ...(0, suite_core_lib_1.createConstants)(siteDomain, overrides),
+        CHECKSUM: exports.CHECKSUM,
+        JWT: exports.JWT,
+        FEC: exports.FEC,
+        ECIES: exports.ECIES,
+    });
+};
+exports.createExpressConstants = createExpressConstants;
+exports.Constants = (0, exports.createExpressConstants)('localhost');
+if (exports.CHECKSUM.SHA3_BUFFER_LENGTH !== exports.CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8 ||
+    exports.CHECKSUM.SHA3_BUFFER_LENGTH !== exports.CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8) {
+    throw new Error('Invalid checksum constants');
+}
+//# sourceMappingURL=constants.js.map

package/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-node-express-suite/src/constants.ts"],"names":[],"mappings":";;;AAAA,0DAAoE;AACpE,oEAAkE;AAMlE;;;;GAIG;AACU,QAAA,QAAQ,GAAoB,MAAM,CAAC,MAAM,CAAC;IACrD,iCAAiC;IACjC,sBAAsB,EAAE,GAAY;IAEpC,gDAAgD;IAChD,kBAAkB,EAAE,EAAW;IAE/B,oCAAoC;IACpC,SAAS,EAAE,UAAmB;IAE9B,mCAAmC;IACnC,QAAQ,EAAE,KAAc;CAChB,CAAC,CAAC;AAEC,QAAA,GAAG,GAAe;IAC7B;;OAEG;IACH,SAAS,EAAE,OAAgB;IAE3B;;OAEG;IACH,cAAc,EAAE,KAAc;CACtB,CAAC;AAEE,QAAA,GAAG,GAAe;IAC7B;;OAEG;IACH,cAAc,EAAE,OAAgB;CACxB,CAAC;AAEX,8BAA8B;AACjB,QAAA,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAa,CAAC,CAAC;AAE3C,MAAM,sBAAsB,GAAG,CACpC,UAAkB,EAClB,SAA+B,EACnB,EAAE;IACd,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAA,gCAAe,EAAC,UAAU,EAAE,SAAS,CAAC;QACzC,QAAQ,EAAE,gBAAQ;QAClB,GAAG,EAAE,WAAG;QACR,GAAG,EAAE,WAAG;QACR,KAAK,EAAE,aAAK;KACJ,CAAC,CAAC;AACd,CAAC,CAAC;AAXW,QAAA,sBAAsB,0BAWjC;AAEW,QAAA,SAAS,GAAe,IAAA,8BAAsB,EAAC,WAAW,CAAC,CAAC;AAEzE,IACE,gBAAQ,CAAC,kBAAkB,KAAK,gBAAQ,CAAC,sBAAsB,GAAG,CAAC;IACnE,gBAAQ,CAAC,kBAAkB,KAAK,gBAAQ,CAAC,sBAAsB,GAAG,CAAC,EACnE,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;AAChD,CAAC"}

package/src/controllers/base.d.ts

@@ -0,0 +1,63 @@
+import { PluginI18nEngine } from '@digitaldefiance/i18n-lib';
+import { IRequestUserDTO } from '@digitaldefiance/suite-core-lib';
+import { NextFunction, Request, Response, Router } from 'express';
+import { ClientSession, Types } from 'mongoose';
+import { IUserDocument } from '../documents/user';
+import { IApplication } from '../interfaces/application';
+import { ApiResponse, FlexibleValidationChain, RouteConfig, TransactionCallback } from '../types';
+import { TransactionOptions } from '../utils';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+export declare abstract class BaseController<T extends ApiResponse, H extends object, TLanguage extends string> {
+    readonly router: Router;
+    private activeRequest;
+    private activeResponse;
+    readonly application: IApplication<any, Types.ObjectId, IBaseDocument<any, Types.ObjectId>, Environment, IConstants>;
+    protected routeDefinitions: RouteConfig<H, TLanguage>[];
+    protected readonly pluginEngine: PluginI18nEngine<TLanguage>;
+    protected handlers: H;
+    private static validationRegistry;
+    constructor(application: IApplication<any, Types.ObjectId, IBaseDocument<any, Types.ObjectId>, Environment, IConstants>);
+    /**
+     * Register validation functions in the allowlist.
+     * Override this method to register custom validation functions.
+     */
+    protected registerValidationFunctions(): void;
+    protected abstract initRouteDefinitions(): void;
+    private getAuthenticationMiddleware;
+    private getCryptoAuthenticationMiddleware;
+    private getValidationMiddleware;
+    private createValidationHandler;
+    private createDynamicValidationHandler;
+    private createRequestHandler;
+    /**
+     * Initializes the routes for the controller.
+     */
+    private initializeRoutes;
+    /**
+     * Authenticates the request by checking the token. Also populates the request with the user object.
+     * @param route The route config
+     * @param req The request object
+     * @param res The response object
+     * @param next The next function
+     */
+    protected authenticateRequest(route: RouteConfig<H, TLanguage>, req: Request, res: Response<T>, next: NextFunction): Promise<void>;
+    private handleBooleanFields;
+    /**
+     * If express-validator flagged any errors, throw an error.
+     * @param req The request object
+     * @param res The response object
+     * @param next The next function
+     * @param validationArray An array of express validation chains that were applied to the request.
+     * @returns
+     */
+    protected checkRequestValidationAndThrow(req: Request, res: Response, next: NextFunction, validationArray?: FlexibleValidationChain<TLanguage>): void;
+    get user(): IRequestUserDTO;
+    get validatedBody(): Record<string, any>;
+    get req(): Request;
+    get res(): Response;
+    protected validateAndFetchRequestUser(req: Request): Promise<IUserDocument<TLanguage>>;
+    withTransaction<T>(callback: TransactionCallback<T>, session?: ClientSession, options?: TransactionOptions, ...args: any): Promise<T>;
+}
+//# sourceMappingURL=base.d.ts.map

package/src/controllers/base.d.ts.map

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