@digitaldefiance/node-express-suite 3.6.21 → 3.6.24

package/src/utils.js

@@ -0,0 +1,818 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TRANSACTION_LOCK_REQUEST_TIMEOUT = exports.DEFAULT_TRANSACTION_TIMEOUT = exports.DEFAULT_RETRY_ATTEMPTS = void 0;
+exports.debugLog = debugLog;
+exports.directLog = directLog;
+exports.getValueAtPath = getValueAtPath;
+exports.mapZodIssuesToValidationErrors = mapZodIssuesToValidationErrors;
+exports.requireValidatedFieldsAsync = requireValidatedFieldsAsync;
+exports.requireOneOfValidatedFieldsAsync = requireOneOfValidatedFieldsAsync;
+exports.requireValidatedFieldsOrThrow = requireValidatedFieldsOrThrow;
+exports.isValidStringId = isValidStringId;
+exports.getDefaultBaseDelay = getDefaultBaseDelay;
+exports.withTransaction = withTransaction;
+exports.sendApiMessageResponse = sendApiMessageResponse;
+exports.sendApiErrorResponse = sendApiErrorResponse;
+exports.sendApiExpressValidationErrorResponse = sendApiExpressValidationErrorResponse;
+exports.sendApiMongoValidationErrorResponse = sendApiMongoValidationErrorResponse;
+exports.sendRawJsonResponse = sendRawJsonResponse;
+exports.handleError = handleError;
+exports.locatePEMRoot = locatePEMRoot;
+exports.lengthEncodeData = lengthEncodeData;
+exports.decodeLengthEncodedData = decodeLengthEncodedData;
+exports.isValidTimezone = isValidTimezone;
+exports.omit = omit;
+exports.validateEnumCollection = validateEnumCollection;
+exports.uint8ArrayToBase64 = uint8ArrayToBase64;
+exports.base64ToUint8Array = base64ToUint8Array;
+exports.uint8ArrayToHex = uint8ArrayToHex;
+exports.hexToUint8Array = hexToUint8Array;
+exports.crc16 = crc16;
+exports.stringToUint8Array = stringToUint8Array;
+exports.uint8ArrayToString = uint8ArrayToString;
+exports.randomBytes = randomBytes;
+exports.arraysEqual = arraysEqual;
+exports.concatUint8Arrays = concatUint8Arrays;
+exports.getLengthEncodingTypeForLength = getLengthEncodingTypeForLength;
+exports.getLengthEncodingTypeFromValue = getLengthEncodingTypeFromValue;
+exports.getLengthForLengthType = getLengthForLengthType;
+exports.parseBackupCodes = parseBackupCodes;
+const tslib_1 = require("tslib");
+const i18n_lib_1 = require("@digitaldefiance/i18n-lib");
+const mongoose_types_1 = require("@digitaldefiance/mongoose-types");
+const express_validator_1 = require("express-validator");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const zod_1 = require("zod");
+const express_validation_1 = require("./errors/express-validation");
+const mongoose_validation_1 = require("./errors/mongoose-validation");
+/**
+ * Optionally prints certain debug messages
+ * @param debug Whether to print debug messages
+ * @param type What type of message to print
+ * @param args Any args to print
+ */
+function debugLog(debug, type = 'log', ...args) {
+    if (debug && type === 'error') {
+        console.error(...args);
+    }
+    else if (debug && type === 'warn') {
+        console.warn(...args);
+    }
+    else if (debug && type === 'log') {
+        console.log(...args);
+    }
+}
+/**
+ * Optionally prints certain debug messages
+ * @param debug Whether to print debug messages
+ * @param type What type of message to print
+ * @param args Any args to print
+ */
+function directLog(debug, type = 'log', ...args) {
+    if (!debug)
+        return;
+    // Format the message
+    const message = args
+        .map((arg) => typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg))
+        .join(' ');
+    // Use fs.writeSync to write directly to the file descriptors
+    // This bypasses Node's stream handling and Nx's interception
+    const buffer = Buffer.from(message + '\n', 'utf8');
+    if (type === 'error' || type === 'warn') {
+        // File descriptor 2 is stderr
+        (0, fs_1.writeSync)(2, buffer);
+    }
+    else {
+        // File descriptor 1 is stdout
+        (0, fs_1.writeSync)(1, buffer);
+    }
+}
+// Helper: get value at a dotted path from an object
+function getValueAtPath(obj, path) {
+    return path.reduce((acc, key) => {
+        if (acc == null)
+            return undefined;
+        try {
+            if (typeof acc === 'object' &&
+                acc !== null &&
+                (typeof key === 'string' || typeof key === 'number')) {
+                return acc[key];
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }, obj);
+}
+// Helper: map Zod issues to express-validator ValidationError[]
+function mapZodIssuesToValidationErrors(issues, source, location = 'body') {
+    return issues.map((issue) => ({
+        type: 'field',
+        location,
+        path: issue.path
+            .filter((p) => typeof p === 'string' || typeof p === 'number')
+            .join('.'),
+        value: getValueAtPath(source, issue.path),
+        msg: issue.message,
+    }));
+}
+/**
+ * Verifies the required fields were validated by express-validator and sends an error response if not or calls the callback if they are
+ * @param req The request object
+ * @param fields The fields to check
+ * @param callback The callback to call if the fields are valid
+ * @returns The result of the callback
+ */
+async function requireValidatedFieldsAsync(req, schema, callback) {
+    if (req.validatedBody === undefined) {
+        throw new errors_1.MissingValidatedDataError();
+    }
+    try {
+        const validatedData = schema.parse(req.validatedBody);
+        return await callback(validatedData);
+    }
+    catch (error) {
+        if (error instanceof zod_1.z.ZodError) {
+            throw new express_validation_1.ExpressValidationError(mapZodIssuesToValidationErrors(error.issues, req.validatedBody ?? {}, 'body'));
+        }
+        throw error;
+    }
+}
+/**
+ * Verifies at least one of the required fields were validated by express-validator and sends an error response if not or calls the callback if they are
+ * @param req The request object
+ * @param fields The fields to check
+ * @param callback The callback to call if the fields are valid
+ * @returns The result of the callback
+ */
+async function requireOneOfValidatedFieldsAsync(req, fields, callback) {
+    if (req.validatedBody === undefined) {
+        throw new errors_1.MissingValidatedDataError();
+    }
+    const validatedBody = req.validatedBody;
+    if (!fields.some((field) => validatedBody?.[field] !== undefined)) {
+        throw new errors_1.MissingValidatedDataError(fields);
+    }
+    return await callback();
+}
+/**
+ * Verifies the required fields were validated by express-validator and throws an error if not or calls the callback if they are
+ * @param req The request object
+ * @param fields The fields to check
+ * @param callback The callback to call if the fields are valid
+ * @returns The result of the callback
+ */
+function requireValidatedFieldsOrThrow(req, fields, callback) {
+    if (req.validatedBody === undefined) {
+        throw new errors_1.MissingValidatedDataError();
+    }
+    const validatedBody = req.validatedBody;
+    fields.forEach((field) => {
+        if (validatedBody[field] === undefined) {
+            throw new errors_1.MissingValidatedDataError(field);
+        }
+    });
+    return callback();
+}
+/**
+ * Checks if the given id is a valid string id
+ * @param id The id to check
+ * @returns True if the id is a valid string id
+ */
+function isValidStringId(id) {
+    return typeof id === 'string' && mongoose_types_1.Types.ObjectId.isValid(id);
+}
+/**
+ * The default number of retry attempts for transactions
+ * Use fewer retries in test environment for faster feedback
+ */
+exports.DEFAULT_RETRY_ATTEMPTS = process.env['NODE_ENV'] === 'test' ? 2 : 3;
+/**
+ * The default transaction timeout in milliseconds
+ * Use shorter timeout in test environment for faster failure detection
+ */
+exports.DEFAULT_TRANSACTION_TIMEOUT = process.env['NODE_ENV'] === 'test' ? 15000 : 60000;
+/**
+ * The default transaction lock request timeout in milliseconds
+ */
+exports.DEFAULT_TRANSACTION_LOCK_REQUEST_TIMEOUT = process.env['NODE_ENV'] === 'test' ? 10000 : 30000;
+/**
+ * Gets the default base delay for transaction retries from environment variables
+ * @returns The base delay in milliseconds
+ */
+function getDefaultBaseDelay() {
+    const envValue = process.env['MONGO_TRANSACTION_RETRY_BASE_DELAY'];
+    if (envValue) {
+        const parsed = parseInt(envValue);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    // Fallback to hardcoded values if environment variable is not set or invalid
+    return process.env['NODE_ENV'] === 'test' ? 25 : 100;
+}
+/**
+ * Wraps a callback in a transaction if necessary
+ * @param connection The mongoose connection
+ * @param useTransaction Whether to use a transaction
+ * @param session The session to use
+ * @param callback The callback to wrap
+ * @param options Transaction options including timeout and retry attempts
+ * @param args The arguments to pass to the callback
+ * @returns The result of the callback
+ */
+async function withTransaction(connection, useTransaction, session, callback, options = {}, ...args) {
+    const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)(options.application
+        ? { constants: options.application.constants }
+        : undefined);
+    const isTestEnvironment = process.env['NODE_ENV'] === 'test';
+    const { timeoutMs = exports.DEFAULT_TRANSACTION_TIMEOUT, retryAttempts = exports.DEFAULT_RETRY_ATTEMPTS, // Use consistent retry attempts
+    baseDelay = getDefaultBaseDelay(), debugLogEnabled, } = options;
+    if (!useTransaction) {
+        return await callback(session, undefined, ...args);
+    }
+    const needSession = useTransaction && session === undefined;
+    const client = connection.getClient();
+    if (!client) {
+        // If no client is available, fall back to non-transactional execution
+        debugLog(debugLogEnabled === true, 'warn', engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Admin_NoMongoDbClientFoundFallingBack));
+        return await callback(session, undefined, ...args);
+    }
+    let attempt = 0;
+    while (attempt < retryAttempts) {
+        const s = needSession ? await client.startSession() : session;
+        try {
+            if (needSession && s !== undefined) {
+                await s.startTransaction({
+                    maxCommitTimeMS: timeoutMs,
+                });
+            }
+            // Race the callback against the timeout
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionTimeoutTemplate, { timeMs: timeoutMs })));
+                }, timeoutMs);
+            });
+            const result = await Promise.race([callback(s, ...args), timeoutPromise]);
+            if (needSession && s !== undefined)
+                await s.commitTransaction();
+            return result;
+        }
+        catch (error) {
+            if (needSession && s !== undefined && s.inTransaction())
+                await s.abortTransaction();
+            // Check if this is a transient transaction error that can be retried
+            const isTransientError = error?.errorLabelSet?.has('TransientTransactionError') ||
+                error?.errorLabelSet?.has('UnknownTransactionCommitResult') ||
+                error?.code === 251 || // NoSuchTransaction
+                error?.code === 112 || // WriteConflict
+                error?.code === 11000 || // DuplicateKey - very common in concurrent initialization
+                error?.code === 16500 || // TransactionAborted
+                error?.code === 244 || // TransactionTooOld
+                error?.code === 246 || // ExceededTimeLimit
+                error?.code === 13436 || // TransactionTooLargeForCache
+                error?.code === 50 || // MaxTimeMSExpired
+                error?.message?.includes('Transaction') ||
+                error?.message?.includes('aborted') ||
+                error?.message?.includes('WriteConflict') ||
+                error?.message?.includes('NoSuchTransaction') ||
+                error?.message?.includes('TransactionTooOld') ||
+                error?.message?.includes('ExceededTimeLimit') ||
+                error?.message?.includes('duplicate key error') ||
+                error?.message?.includes('E11000') ||
+                (error?.code === 11000 && error?.message?.includes('duplicate')); // More specific duplicate key handling
+            if (isTransientError && attempt < retryAttempts - 1) {
+                attempt++;
+                const jitter = Math.random() * 0.3; // Reduced jitter
+                const actualBaseDelay = isTestEnvironment
+                    ? Math.floor(baseDelay * 0.5)
+                    : baseDelay; // Shorter base delay in tests
+                const delay = Math.floor(actualBaseDelay * (1 + attempt * 0.5) * (1 + jitter)); // Linear backoff instead of exponential
+                debugLog(debugLogEnabled === true, 'warn', engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionFailedTransientTemplate, {
+                    delayMs: delay,
+                    attempt,
+                    attempts: retryAttempts,
+                }, undefined));
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            if (needSession && s !== undefined)
+                await s.endSession();
+        }
+    }
+    const jitter = Math.random() * 0.3; // Reduced jitter
+    const actualBaseDelay = isTestEnvironment
+        ? Math.floor(baseDelay * 0.5)
+        : baseDelay; // Shorter base delay in tests
+    const delay = Math.floor(actualBaseDelay * (1 + attempt * 0.5) * (1 + jitter)); // Linear backoff instead of exponential
+    throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionFailedTransientTemplate, {
+        delayMs: delay,
+        attempt,
+        attempts: retryAttempts,
+    });
+}
+/**
+ * Sends an API response with the given status and response object.
+ * @param status
+ * @param response
+ * @param res
+ */
+function sendApiMessageResponse(status, response, res) {
+    res.status(status).json(response);
+}
+/**
+ * Sends an API response with the given status, message, and error.
+ * @param status
+ * @param message
+ * @param error
+ * @param res
+ */
+function sendApiErrorResponse(status, message, error, res) {
+    sendApiMessageResponse(status, { message, error }, res);
+}
+/**
+ * Sends an API response with the given status and validation errors.
+ * @param status
+ * @param errors
+ * @param res
+ */
+function sendApiExpressValidationErrorResponse(status, errors, res, application) {
+    const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)(application ? { constants: application.constants } : undefined);
+    sendApiMessageResponse(status, {
+        message: engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.ValidationError),
+        errors,
+    }, res);
+}
+/**
+ * Sends an API response with the given status, message, and MongoDB validation errors.
+ * @param status
+ * @param message
+ * @param errors
+ * @param res
+ */
+function sendApiMongoValidationErrorResponse(status, message, errors, res) {
+    sendApiMessageResponse(status, { message, errors }, res);
+}
+/**
+ * Sends a raw JSON response with the given status and response object.
+ * @param status The status code
+ * @param response The response data
+ * @param res The response object
+ */
+function sendRawJsonResponse(status, response, res) {
+    res.status(status).json(response);
+}
+function isRecursiveError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        '_handlingInProgress' in error &&
+        !!error._handlingInProgress);
+}
+function markErrorAsHandling(error) {
+    if (error && typeof error === 'object') {
+        error._handlingInProgress = true;
+    }
+}
+function getSafeErrorMessage(message, application) {
+    if (message && typeof message === 'string' && message.trim() !== '') {
+        return message;
+    }
+    const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)(application ? { constants: application.constants } : undefined);
+    try {
+        const translated = engine.translate(suite_core_lib_1.SuiteCoreComponentId, suite_core_lib_1.SuiteCoreStringKey.Common_UnexpectedError);
+        return translated &&
+            typeof translated === 'string' &&
+            translated.trim() !== ''
+            ? translated
+            : 'An unexpected error occurred';
+    }
+    catch {
+        return 'An unexpected error occurred';
+    }
+}
+function convertToHandleableError(error) {
+    if (error instanceof i18n_lib_2.HandleableError) {
+        return {
+            handleableError: error,
+            alreadyHandled: error.handled,
+            errorType: error.name,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            handleableError: new i18n_lib_2.HandleableError(error),
+            alreadyHandled: false,
+            errorType: error.name,
+        };
+    }
+    const unknownMessage = getSafeErrorMessage(typeof error === 'object' &&
+        error !== null &&
+        'message' in error
+        ? error['message']
+        : undefined);
+    const unknownError = new Error(unknownMessage);
+    return {
+        handleableError: new i18n_lib_2.HandleableError(unknownError, { sourceData: error }),
+        alreadyHandled: false,
+        errorType: 'UnexpectedError',
+    };
+}
+function sendErrorResponse(error, handleableError, errorType, send, res) {
+    const engine = i18n_lib_1.I18nEngine.getInstance();
+    if (error instanceof express_validation_1.ExpressValidationError) {
+        // amazonq-ignore-next-line false positive
+        send(handleableError.statusCode, {
+            message: engine.translate('core', 'ValidationError'),
+            errors: error.errors instanceof express_validator_1.Result ? error.errors.array() : error.errors,
+            errorType: 'ExpressValidationError',
+        }, res);
+    }
+    else if (error instanceof mongoose_validation_1.MongooseValidationError) {
+        // amazonq-ignore-next-line false positive
+        send(handleableError.statusCode, {
+            message: engine.translate('core', 'ValidationError'),
+            errors: error.errors,
+            errorType: 'MongooseValidationError',
+        }, res);
+    }
+    else {
+        // amazonq-ignore-next-line false positive
+        send(handleableError.statusCode, {
+            message: handleableError.message,
+            error: {
+                message: handleableError.message,
+                statusCode: handleableError.statusCode,
+                ...(handleableError.stack && { stack: handleableError.stack }),
+            },
+            errorType: errorType,
+        }, res);
+    }
+}
+function handleError(error, res, send, _next) {
+    if (isRecursiveError(error)) {
+        const fallbackError = new i18n_lib_2.HandleableError(new Error('Recursive error handling detected'));
+        // amazonq-ignore-next-line false positive
+        send(fallbackError.statusCode, {
+            message: fallbackError.message,
+            error: fallbackError,
+            errorType: 'RecursiveError',
+        }, res);
+        return;
+    }
+    markErrorAsHandling(error);
+    const { handleableError, alreadyHandled: _alreadyHandled, errorType, } = convertToHandleableError(error);
+    if (!(error instanceof express_validation_1.ExpressValidationError)) {
+        console.error('[handleError]', 'type=' + errorType.replace(/[\r\n]/g, ''), 'status=' + String(handleableError.statusCode).replace(/[\r\n]/g, ''), 'message=' + (handleableError.message || '').replace(/[\r\n]/g, ''));
+        if (error instanceof Error && error.stack) {
+            debugLog(true, 'error', '[handleError] stack:', error.stack);
+        }
+    }
+    if (!res.headersSent) {
+        sendErrorResponse(error, handleableError, errorType, send, res);
+        handleableError.handled = true;
+    }
+}
+function locatePEMRoot(devRootDir) {
+    try {
+        const normalizedDir = (0, path_1.resolve)(devRootDir);
+        if (normalizedDir.includes('..') ||
+            !normalizedDir.startsWith((0, path_1.resolve)('.'))) {
+            return undefined;
+        }
+        const files = (0, fs_1.readdirSync)(normalizedDir);
+        const pemFiles = files.filter((file) => 
+        // Prevent path traversal by rejecting files with path separators
+        !file.includes('/') &&
+            !file.includes('\\') &&
+            !file.includes('..') &&
+            (file.match(/localhost\+\d+-key\.pem$/) ||
+                file.match(/localhost\+\d+\.pem$/)));
+        if (pemFiles.length < 2) {
+            return undefined;
+        }
+        const roots = pemFiles.map((file) => {
+            const resolved = (0, path_1.resolve)(normalizedDir, file);
+            if (!resolved.startsWith(normalizedDir)) {
+                return undefined;
+            }
+            const result = /(.*)\/(localhost\+\d+)(.*)\.pem/.exec(resolved);
+            return result ? `${result[1]}/${result[2]}` : undefined;
+        });
+        if (roots.some((root) => root !== roots[0])) {
+            return undefined;
+        }
+        if (!(0, fs_1.existsSync)(roots[0] + '.pem') || !(0, fs_1.existsSync)(roots[0] + '-key.pem')) {
+            return undefined;
+        }
+        return roots[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Encodes the length of the data in the buffer
+ * @param buffer The buffer to encode
+ * @returns The encoded buffer
+ */
+function lengthEncodeData(buffer) {
+    const lengthType = getLengthEncodingTypeForLength(buffer.length);
+    const lengthTypeSize = getLengthForLengthType(lengthType);
+    const result = Buffer.alloc(1 + lengthTypeSize + buffer.length);
+    result.writeUInt8(lengthType, 0);
+    switch (lengthType) {
+        case length_encoding_type_1.LengthEncodingType.UInt8:
+            result.writeUInt8(buffer.length, 1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt16:
+            result.writeUInt16BE(buffer.length, 1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt32:
+            result.writeUInt32BE(buffer.length, 1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt64:
+            result.writeBigUInt64BE(BigInt(buffer.length), 1);
+            break;
+    }
+    buffer.copy(result, 1 + lengthTypeSize);
+    return result;
+}
+function decodeLengthEncodedData(buffer) {
+    if (buffer.length < 1) {
+        throw new RangeError('Buffer is too short to read length type.');
+    }
+    const lengthType = getLengthEncodingTypeFromValue(buffer.readUint8(0));
+    const lengthTypeSize = getLengthForLengthType(lengthType);
+    if (buffer.length < 1 + lengthTypeSize) {
+        throw new RangeError('Buffer is too short to read the full length value.');
+    }
+    let length;
+    switch (lengthType) {
+        case length_encoding_type_1.LengthEncodingType.UInt8:
+            length = buffer.readUint8(1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt16:
+            length = buffer.readUint16BE(1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt32:
+            length = buffer.readUint32BE(1);
+            break;
+        case length_encoding_type_1.LengthEncodingType.UInt64:
+            length = buffer.readBigUInt64BE(1);
+            if (Number(length) > Number.MAX_SAFE_INTEGER) {
+                throw new RangeError('Length exceeds maximum safe integer value');
+            }
+            break;
+        default:
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthIsInvalidType);
+    }
+    const totalLength = 1 + lengthTypeSize + Number(length);
+    if (totalLength > buffer.length) {
+        throw new RangeError('Buffer is too short for declared data length');
+    }
+    return {
+        data: buffer.subarray(1 + lengthTypeSize, totalLength),
+        totalLength,
+    };
+}
+const i18n_lib_2 = require("@digitaldefiance/i18n-lib");
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const moment_timezone_1 = tslib_1.__importDefault(require("moment-timezone"));
+const backup_code_1 = require("./backup-code");
+const length_encoding_type_1 = require("./enumerations/length-encoding-type");
+const errors_1 = require("./errors");
+function isValidTimezone(timezone) {
+    return moment_timezone_1.default.tz.zone(timezone) !== null;
+}
+/**
+ * Omits keys from an object
+ */
+function omit(obj, keys) {
+    const keysToOmit = new Set(keys);
+    return Object.keys(obj).reduce((result, key) => {
+        if (!keysToOmit.has(key)) {
+            result[key] = obj[key];
+        }
+        return result;
+    }, {});
+}
+/**
+ * Validates that a collection contains exactly the keys from an enum
+ * @param collection The collection to validate
+ * @param enumObject The enum object to validate against
+ * @param collectionName Optional name for the collection (for better error messages)
+ * @param enumName Optional name for the enum (for better error messages)
+ * @throws Error if collection has missing, extra, or invalid keys
+ */
+function validateEnumCollection(collection, enumObject, collectionName, enumName) {
+    // For numeric enums, filter out reverse mappings (number -> string)
+    const enumKeys = Object.keys(enumObject).filter((key) => isNaN(Number(key)));
+    const allEnumValues = enumKeys.map((key) => enumObject[key]);
+    const collectionKeys = Object.keys(collection);
+    const collectionLabel = collectionName || 'Collection';
+    const enumLabel = enumName || `enum with keys [${enumKeys.join(', ')}]`;
+    if (collectionKeys.length !== allEnumValues.length) {
+        throw new Error(`${collectionLabel} must contain exactly ${allEnumValues.length} keys to match ${enumLabel}. Found ${collectionKeys.length} keys: [${collectionKeys.join(', ')}]`);
+    }
+    const invalidKeys = collectionKeys.filter((key) => !allEnumValues.includes(key));
+    if (invalidKeys.length > 0) {
+        throw new Error(`${collectionLabel} contains invalid keys for ${enumLabel}: [${invalidKeys.join(', ')}]. Valid keys are: [${allEnumValues.join(', ')}]`);
+    }
+    const missingKeys = allEnumValues.filter((value) => !(value in collection));
+    if (missingKeys.length > 0) {
+        throw new Error(`${collectionLabel} is missing required keys for ${enumLabel}: [${missingKeys.join(', ')}]`);
+    }
+}
+function uint8ArrayToBase64(uint8Array) {
+    let binaryString = '';
+    for (let i = 0; i < uint8Array.length; i++) {
+        binaryString += String.fromCharCode(uint8Array[i]);
+    }
+    return btoa(binaryString);
+}
+function base64ToUint8Array(base64String) {
+    const binaryString = atob(base64String);
+    const len = binaryString.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+}
+function uint8ArrayToHex(uint8Array) {
+    return Array.from(uint8Array)
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+function hexToUint8Array(hexString) {
+    const len = hexString.length;
+    const bytes = new Uint8Array(len / 2);
+    for (let i = 0; i < len; i += 2) {
+        bytes[i / 2] = parseInt(hexString.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Utility functions for browser ECIES implementation
+ */
+/**
+ * CRC16-CCITT implementation for data integrity checking
+ * Uses the same algorithm as the server-side implementation (CRC16-CCITT-FALSE)
+ */
+function crc16(data) {
+    let crc = 0xffff; // Initial value for CRC16-CCITT-FALSE
+    const polynomial = 0x1021; // CRC16-CCITT polynomial
+    for (let i = 0; i < data.length; i++) {
+        crc ^= data[i] << 8;
+        for (let j = 0; j < 8; j++) {
+            if (crc & 0x8000) {
+                crc = (crc << 1) ^ polynomial;
+            }
+            else {
+                crc = crc << 1;
+            }
+            crc &= 0xffff; // Keep it 16-bit
+        }
+    }
+    const result = new Uint8Array(2);
+    result[0] = (crc >>> 8) & 0xff; // Big-endian
+    result[1] = crc & 0xff;
+    return result;
+}
+/**
+ * Convert string to Uint8Array (UTF-8 encoding)
+ */
+function stringToUint8Array(str) {
+    return new TextEncoder().encode(str);
+}
+/**
+ * Convert Uint8Array to string (UTF-8 decoding)
+ */
+function uint8ArrayToString(array) {
+    return new TextDecoder().decode(array);
+}
+/**
+ * Secure random bytes generation
+ */
+function randomBytes(length) {
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+/**
+ * Compare two Uint8Arrays for equality
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+function concatUint8Arrays(...arrays) {
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const array of arrays) {
+        result.set(array, offset);
+        offset += array.length;
+    }
+    return result;
+}
+/**
+ * Get the length encoding type for a given length
+ * @param length The length to evaluate
+ * @returns The corresponding LengthEncodingType
+ */
+function getLengthEncodingTypeForLength(length) {
+    if (typeof length === 'number') {
+        if (length < 256) {
+            return length_encoding_type_1.LengthEncodingType.UInt8;
+        }
+        else if (length < 65536) {
+            return length_encoding_type_1.LengthEncodingType.UInt16;
+        }
+        else if (length < 4294967296) {
+            return length_encoding_type_1.LengthEncodingType.UInt32;
+        }
+        else if (length < Number.MAX_SAFE_INTEGER) {
+            return length_encoding_type_1.LengthEncodingType.UInt64;
+        }
+        else {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthExceedsMaximum);
+        }
+    }
+    else if (typeof length === 'bigint') {
+        if (length < 256n) {
+            return length_encoding_type_1.LengthEncodingType.UInt8;
+        }
+        else if (length < 65536n) {
+            return length_encoding_type_1.LengthEncodingType.UInt16;
+        }
+        else if (length < 4294967296n) {
+            return length_encoding_type_1.LengthEncodingType.UInt32;
+        }
+        else if (length < 18446744073709551616n) {
+            return length_encoding_type_1.LengthEncodingType.UInt64;
+        }
+        else {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthExceedsMaximum);
+        }
+    }
+    else {
+        throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthIsInvalidType);
+    }
+}
+/**
+ * Get the length encoding type for a given value
+ * @param value The value to evaluate
+ * @returns The corresponding LengthEncodingType
+ */
+function getLengthEncodingTypeFromValue(value) {
+    for (const length of Object.values(length_encoding_type_1.LengthEncodingType)) {
+        if (length === value) {
+            return length;
+        }
+    }
+    throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthIsInvalidType);
+}
+/**
+ * Get the length in bytes for a given LengthEncodingType
+ * @param type The LengthEncodingType to evaluate
+ * @returns The length in bytes
+ */
+function getLengthForLengthType(type) {
+    switch (type) {
+        case length_encoding_type_1.LengthEncodingType.UInt8:
+            return 1;
+        case length_encoding_type_1.LengthEncodingType.UInt16:
+            return 2;
+        case length_encoding_type_1.LengthEncodingType.UInt32:
+            return 4;
+        case length_encoding_type_1.LengthEncodingType.UInt64:
+            return 8;
+        default:
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_LengthIsInvalidType);
+    }
+}
+function parseBackupCodes(user, environment) {
+    const envVarMap = {
+        admin: 'ADMIN_BACKUP_CODES',
+        member: 'MEMBER_BACKUP_CODES',
+        system: 'SYSTEM_BACKUP_CODES',
+    };
+    const envVar = envVarMap[user];
+    const envValue = environment[envVar];
+    const backupCodes = envValue?.split(',').map((code) => new backup_code_1.BackupCode(code.trim())) ||
+        [];
+    return backupCodes;
+}
+//# sourceMappingURL=utils.js.map