@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/utils.ts

@@ -0,0 +1,1116 @@
+/**
+ * @fileoverview Utility functions for Express application including validation, transactions, error handling, and data encoding.
+ * Provides comprehensive helpers for API responses, MongoDB transactions, validation, and cryptographic operations.
+ * @module utils
+ */
+
+import { I18nEngine } from '@digitaldefiance/i18n-lib';
+import {
+  ClientSession,
+  Connection,
+  Types,
+} from '@digitaldefiance/mongoose-types';
+import { NextFunction, Request, Response } from 'express';
+import { Result, ValidationError } from 'express-validator';
+import { existsSync, readdirSync, writeSync } from 'fs';
+import { resolve } from 'path';
+import { z, ZodType } from 'zod';
+import { ExpressValidationError } from './errors/express-validation';
+import { MongooseValidationError } from './errors/mongoose-validation';
+import { IApiErrorResponse, IApplication } from './interfaces';
+import { IApiExpressValidationErrorResponse } from './interfaces/api-express-validation-error-response';
+import { IApiMongoValidationErrorResponse } from './interfaces/api-mongo-validation-error-response';
+import { IMongoErrors } from './interfaces/mongo-errors';
+import { RequiredStringKeys } from './interfaces/required-string-keys';
+import { ApiResponse, SendFunction, TransactionCallback } from './types';
+
+/** Debug message type for console output */
+export type DEBUG_TYPE = 'error' | 'warn' | 'log';
+
+/**
+ * Conditionally prints debug messages to console.
+ * @param debug Whether to print debug messages
+ * @param type Type of message (error, warn, or log)
+ * @param args Arguments to print
+ */
+export function debugLog(
+  debug: boolean,
+  type: DEBUG_TYPE = 'log',
+  ...args: unknown[]
+): void {
+  if (debug && type === 'error') {
+    console.error(...args);
+  } else if (debug && type === 'warn') {
+    console.warn(...args);
+  } else if (debug && type === 'log') {
+    console.log(...args);
+  }
+}
+
+/**
+ * Prints debug messages directly to stdout/stderr bypassing Node streams.
+ * Uses fs.writeSync to avoid Nx interception.
+ * @param debug Whether to print debug messages
+ * @param type Type of message (error, warn, or log)
+ * @param args Arguments to print
+ */
+export function directLog(
+  debug: boolean,
+  type: DEBUG_TYPE = 'log',
+  ...args: any[]
+): void {
+  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
+    writeSync(2, buffer);
+  } else {
+    // File descriptor 1 is stdout
+    writeSync(1, buffer);
+  }
+}
+
+/**
+ * Gets value at a dotted path from an object.
+ * @param obj Object to traverse
+ * @param path Array of keys representing the path
+ * @returns Value at path or undefined
+ */
+export function getValueAtPath(
+  obj: unknown,
+  path: (string | number)[],
+): unknown {
+  return path.reduce<unknown>((acc, key) => {
+    if (acc == null) return undefined;
+    try {
+      if (
+        typeof acc === 'object' &&
+        acc !== null &&
+        (typeof key === 'string' || typeof key === 'number')
+      ) {
+        return (acc as Record<string | number, unknown>)[key];
+      }
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  }, obj);
+}
+
+/**
+ * Maps Zod validation issues to express-validator ValidationError format.
+ * @param issues Zod validation issues
+ * @param source Source object being validated
+ * @param location Location of validation (body, query, params, etc.)
+ * @returns Array of express-validator ValidationErrors
+ */
+export function mapZodIssuesToValidationErrors(
+  issues: z.ZodError<unknown>['issues'],
+  source: unknown,
+  location: 'body' | 'cookies' | 'headers' | 'params' | 'query' = 'body',
+): ValidationError[] {
+  return issues.map((issue) => ({
+    type: 'field',
+    location,
+    path: issue.path
+      .filter((p) => typeof p === 'string' || typeof p === 'number')
+      .join('.'),
+    value: getValueAtPath(source, issue.path as (string | number)[]),
+    msg: issue.message,
+  }));
+}
+
+/**
+ * Validates request body against Zod schema and executes callback with validated data.
+ * @template T Zod schema type
+ * @template TResult Callback return type
+ * @param req Express request
+ * @param schema Zod schema for validation
+ * @param callback Callback to execute with validated data
+ * @returns Promise resolving to callback result
+ * @throws {MissingValidatedDataError} If validated body is missing
+ * @throws {ExpressValidationError} If validation fails
+ */
+export async function requireValidatedFieldsAsync<
+  T extends ZodType<any, any, any>,
+  TResult = void,
+>(
+  req: Request,
+  schema: T,
+  callback: (data: z.output<T>) => Promise<TResult>,
+): Promise<TResult> {
+  if (req.validatedBody === undefined) {
+    throw new MissingValidatedDataError();
+  }
+
+  try {
+    const validatedData = schema.parse(req.validatedBody) as z.output<T>;
+    return await callback(validatedData);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new ExpressValidationError(
+        mapZodIssuesToValidationErrors(
+          error.issues,
+          req.validatedBody ?? {},
+          'body',
+        ),
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Checks if at least one of the required fields is present in validated body.
+ * @template T Callback return type
+ * @param req Express request
+ * @param fields Array of field names to check
+ * @param callback Callback to execute if validation passes
+ * @returns Promise resolving to callback result
+ * @throws {MissingValidatedDataError} If none of the fields are present
+ */
+export async function requireOneOfValidatedFieldsAsync<T = void>(
+  req: Request,
+  fields: string[],
+  callback: () => Promise<T>,
+): Promise<T> {
+  if (req.validatedBody === undefined) {
+    throw new MissingValidatedDataError();
+  }
+  const validatedBody = req.validatedBody;
+  if (!fields.some((field) => validatedBody?.[field] !== undefined)) {
+    throw new MissingValidatedDataError(fields);
+  }
+  return await callback();
+}
+
+/**
+ * Validates required fields are present in validated body (synchronous).
+ * @template T Callback return type
+ * @param req Express request
+ * @param fields Array of required field names
+ * @param callback Callback to execute if validation passes
+ * @returns Callback result
+ * @throws {MissingValidatedDataError} If any required field is missing
+ */
+export function requireValidatedFieldsOrThrow<T = void>(
+  req: Request,
+  fields: string[],
+  callback: () => T,
+): T {
+  if (req.validatedBody === undefined) {
+    throw new MissingValidatedDataError();
+  }
+  const validatedBody = req.validatedBody;
+  fields.forEach((field) => {
+    if (validatedBody[field] === undefined) {
+      throw new MissingValidatedDataError(field);
+    }
+  });
+  return callback();
+}
+
+/**
+ * Checks if a value is a valid MongoDB ObjectId string.
+ * @param id Value to check
+ * @returns True if valid ObjectId string
+ */
+export function isValidStringObjectId(id: unknown): boolean {
+  return typeof id === 'string' && Types.ObjectId.isValid(id);
+}
+
+/**
+ * Default number of retry attempts for transactions.
+ * Uses fewer retries in test environment for faster feedback.
+ */
+export const DEFAULT_RETRY_ATTEMPTS =
+  process.env['NODE_ENV'] === 'test' ? 2 : 3;
+/**
+ * Default transaction timeout in milliseconds.
+ * Uses shorter timeout in test environment for faster failure detection.
+ */
+export const DEFAULT_TRANSACTION_TIMEOUT =
+  process.env['NODE_ENV'] === 'test' ? 15000 : 60000;
+
+/**
+ * Default transaction lock request timeout in milliseconds.
+ */
+export const DEFAULT_TRANSACTION_LOCK_REQUEST_TIMEOUT =
+  process.env['NODE_ENV'] === 'test' ? 10000 : 30000;
+
+/** Transaction configuration options */
+export interface TransactionOptions<TID extends PlatformID = Buffer> {
+  application?: IApplication<TID>;
+  timeoutMs?: number;
+  retryAttempts?: number;
+  baseDelay?: number;
+  debugLogEnabled?: boolean;
+}
+
+/**
+ * Gets the default base delay for transaction retries from environment variables
+ * @returns The base delay in milliseconds
+ */
+export function getDefaultBaseDelay(): number {
+  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
+ */
+export async function withTransaction<T, TID extends PlatformID = Buffer>(
+  connection: Connection,
+  useTransaction: boolean,
+  session: ClientSession | undefined,
+  callback: TransactionCallback<T>,
+  options: TransactionOptions<TID> = {},
+  ...args: any
+): Promise<T> {
+  const engine = getSuiteCoreI18nEngine(
+    options.application
+      ? { constants: options.application.constants }
+      : undefined,
+  );
+  const isTestEnvironment = process.env['NODE_ENV'] === 'test';
+  const {
+    timeoutMs = DEFAULT_TRANSACTION_TIMEOUT,
+    retryAttempts = 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(
+        SuiteCoreComponentId,
+        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<never>((_, reject) => {
+        setTimeout(() => {
+          reject(
+            new Error(
+              engine.translate(
+                SuiteCoreComponentId,
+                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: any) {
+      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(
+            SuiteCoreComponentId,
+            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 TranslatableSuiteError(
+    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
+ */
+export function sendApiMessageResponse<T extends ApiResponse>(
+  status: number,
+  response: T,
+  res: Response<T>,
+): void {
+  res.status(status).json(response);
+}
+
+/**
+ * Sends an API response with the given status, message, and error.
+ * @param status
+ * @param message
+ * @param error
+ * @param res
+ */
+export function sendApiErrorResponse(
+  status: number,
+  message: string,
+  error: unknown,
+  res: Response,
+): void {
+  sendApiMessageResponse<IApiErrorResponse>(status, { message, error }, res);
+}
+
+/**
+ * Sends an API response with the given status and validation errors.
+ * @param status
+ * @param errors
+ * @param res
+ */
+export function sendApiExpressValidationErrorResponse(
+  status: number,
+  errors: ValidationError[],
+  res: Response,
+  application?: IApplication,
+): void {
+  const engine = getSuiteCoreI18nEngine(
+    application ? { constants: application.constants } : undefined,
+  );
+  sendApiMessageResponse<IApiExpressValidationErrorResponse>(
+    status,
+    {
+      message: engine.translate(
+        SuiteCoreComponentId,
+        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
+ */
+export function sendApiMongoValidationErrorResponse(
+  status: number,
+  message: string,
+  errors: IMongoErrors,
+  res: Response,
+): void {
+  sendApiMessageResponse<IApiMongoValidationErrorResponse>(
+    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
+ */
+export function sendRawJsonResponse<T>(
+  status: number,
+  response: T,
+  res: Response<T>,
+) {
+  res.status(status).json(response);
+}
+
+function isRecursiveError(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    '_handlingInProgress' in error &&
+    !!(error as { _handlingInProgress?: boolean })._handlingInProgress
+  );
+}
+
+function markErrorAsHandling(error: unknown): void {
+  if (error && typeof error === 'object') {
+    (error as { _handlingInProgress?: boolean })._handlingInProgress = true;
+  }
+}
+
+function getSafeErrorMessage(
+  message?: string,
+  application?: IApplication,
+): string {
+  if (message && typeof message === 'string' && message.trim() !== '') {
+    return message;
+  }
+  const engine = getSuiteCoreI18nEngine(
+    application ? { constants: application.constants } : undefined,
+  );
+  try {
+    const translated = engine.translate(
+      SuiteCoreComponentId,
+      SuiteCoreStringKey.Common_UnexpectedError,
+    );
+    return translated &&
+      typeof translated === 'string' &&
+      translated.trim() !== ''
+      ? translated
+      : 'An unexpected error occurred';
+  } catch {
+    return 'An unexpected error occurred';
+  }
+}
+
+function convertToHandleableError(error: unknown): {
+  handleableError: HandleableError;
+  alreadyHandled: boolean;
+  errorType: string;
+} {
+  if (error instanceof HandleableError) {
+    return {
+      handleableError: error,
+      alreadyHandled: error.handled,
+      errorType: error.name,
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      handleableError: new HandleableError(error),
+      alreadyHandled: false,
+      errorType: error.name,
+    };
+  }
+  const unknownMessage = getSafeErrorMessage(
+    typeof error === 'object' &&
+      error !== null &&
+      'message' in (error as object)
+      ? ((error as Record<string, unknown>)['message'] as string | undefined)
+      : undefined,
+  );
+  const unknownError = new Error(unknownMessage);
+  return {
+    handleableError: new HandleableError(unknownError, { sourceData: error }),
+    alreadyHandled: false,
+    errorType: 'UnexpectedError',
+  };
+}
+
+function sendErrorResponse<TStringKey extends keyof RequiredStringKeys>(
+  error: unknown,
+  handleableError: HandleableError,
+  errorType: string,
+  send: SendFunction<
+    | IApiErrorResponse
+    | IApiExpressValidationErrorResponse
+    | IApiMongoValidationErrorResponse
+  >,
+  res: Response,
+): void {
+  const engine = I18nEngine.getInstance();
+  if (error instanceof ExpressValidationError) {
+    // amazonq-ignore-next-line false positive
+    send(
+      handleableError.statusCode,
+      {
+        message: engine.translate('core', 'ValidationError' as TStringKey),
+        errors:
+          error.errors instanceof Result ? error.errors.array() : error.errors,
+        errorType: 'ExpressValidationError',
+      },
+      res,
+    );
+  } else if (error instanceof MongooseValidationError) {
+    // amazonq-ignore-next-line false positive
+    send(
+      handleableError.statusCode,
+      {
+        message: engine.translate('core', 'ValidationError' as TStringKey),
+        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,
+    );
+  }
+}
+
+export function handleError(
+  error: unknown,
+  res: Response,
+  send: SendFunction<
+    | IApiErrorResponse
+    | IApiExpressValidationErrorResponse
+    | IApiMongoValidationErrorResponse
+  >,
+  _next: NextFunction,
+): void {
+  if (isRecursiveError(error)) {
+    const fallbackError = new 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 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;
+  }
+}
+
+export function locatePEMRoot(devRootDir: string): string | undefined {
+  try {
+    const normalizedDir = resolve(devRootDir);
+    if (
+      normalizedDir.includes('..') ||
+      !normalizedDir.startsWith(resolve('.'))
+    ) {
+      return undefined;
+    }
+    const files = readdirSync(normalizedDir);
+    const pemFiles = files.filter(
+      (file: string) =>
+        // 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: string) => {
+      const resolved = 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 (!existsSync(roots[0] + '.pem') || !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
+ */
+export function lengthEncodeData(buffer: Buffer): Buffer {
+  const lengthType: LengthEncodingType = getLengthEncodingTypeForLength(
+    buffer.length,
+  );
+  const lengthTypeSize: number = getLengthForLengthType(lengthType);
+  const result: Buffer = Buffer.alloc(1 + lengthTypeSize + buffer.length);
+  result.writeUInt8(lengthType, 0);
+  switch (lengthType) {
+    case LengthEncodingType.UInt8:
+      result.writeUInt8(buffer.length, 1);
+      break;
+    case LengthEncodingType.UInt16:
+      result.writeUInt16BE(buffer.length, 1);
+      break;
+    case LengthEncodingType.UInt32:
+      result.writeUInt32BE(buffer.length, 1);
+      break;
+    case LengthEncodingType.UInt64:
+      result.writeBigUInt64BE(BigInt(buffer.length), 1);
+      break;
+  }
+  buffer.copy(result, 1 + lengthTypeSize);
+  return result;
+}
+
+export function decodeLengthEncodedData(buffer: Buffer): {
+  data: Buffer;
+  totalLength: number;
+} {
+  if (buffer.length < 1) {
+    throw new RangeError('Buffer is too short to read length type.');
+  }
+  const lengthType: LengthEncodingType = getLengthEncodingTypeFromValue(
+    buffer.readUint8(0),
+  );
+  const lengthTypeSize: number = getLengthForLengthType(lengthType);
+
+  if (buffer.length < 1 + lengthTypeSize) {
+    throw new RangeError('Buffer is too short to read the full length value.');
+  }
+
+  let length: number | bigint;
+  switch (lengthType) {
+    case LengthEncodingType.UInt8:
+      length = buffer.readUint8(1);
+      break;
+    case LengthEncodingType.UInt16:
+      length = buffer.readUint16BE(1);
+      break;
+    case LengthEncodingType.UInt32:
+      length = buffer.readUint32BE(1);
+      break;
+    case 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 TranslatableSuiteError(
+        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,
+  };
+}
+
+import { HandleableError } from '@digitaldefiance/i18n-lib';
+import {
+  getSuiteCoreI18nEngine,
+  SuiteCoreComponentId,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import moment from 'moment-timezone';
+import { BackupCode } from './backup-code';
+import { LengthEncodingType } from './enumerations/length-encoding-type';
+import { MissingValidatedDataError } from './errors';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+export function isValidTimezone(timezone: string): boolean {
+  return moment.tz.zone(timezone) !== null;
+}
+
+/**
+ * Omits keys from an object
+ */
+export function omit<T extends object, K extends keyof T>(
+  obj: T,
+  keys: K[],
+): Omit<T, K> {
+  const keysToOmit = new Set(keys);
+  return Object.keys(obj).reduce((result, key) => {
+    if (!keysToOmit.has(key as K)) {
+      result[key as keyof T] = obj[key as keyof T];
+    }
+    return result;
+  }, {} as T) as Omit<T, K>;
+}
+
+/**
+ * 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
+ */
+export function validateEnumCollection<T extends Record<string, any>>(
+  collection: Record<string, unknown>,
+  enumObject: T,
+  collectionName?: string,
+  enumName?: string,
+): void {
+  // 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(
+        ', ',
+      )}]`,
+    );
+  }
+}
+
+export function uint8ArrayToBase64(uint8Array: Uint8Array): string {
+  let binaryString = '';
+  for (let i = 0; i < uint8Array.length; i++) {
+    binaryString += String.fromCharCode(uint8Array[i]);
+  }
+  return btoa(binaryString);
+}
+
+export function base64ToUint8Array(base64String: string): Uint8Array {
+  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;
+}
+
+export function uint8ArrayToHex(uint8Array: Uint8Array): string {
+  return Array.from(uint8Array)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export function hexToUint8Array(hexString: string): Uint8Array {
+  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)
+ */
+export function crc16(data: Uint8Array): Uint8Array {
+  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)
+ */
+export function stringToUint8Array(str: string): Uint8Array {
+  return new TextEncoder().encode(str);
+}
+
+/**
+ * Convert Uint8Array to string (UTF-8 decoding)
+ */
+export function uint8ArrayToString(array: Uint8Array): string {
+  return new TextDecoder().decode(array);
+}
+
+/**
+ * Secure random bytes generation
+ */
+export function randomBytes(length: number): Uint8Array {
+  return crypto.getRandomValues(new Uint8Array(length));
+}
+
+/**
+ * Compare two Uint8Arrays for equality
+ */
+export function arraysEqual(a: Uint8Array, b: Uint8Array): boolean {
+  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
+ */
+export function concatUint8Arrays(...arrays: Uint8Array[]): Uint8Array {
+  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
+ */
+export function getLengthEncodingTypeForLength(
+  length: number | bigint,
+): LengthEncodingType {
+  if (typeof length === 'number') {
+    if (length < 256) {
+      return LengthEncodingType.UInt8;
+    } else if (length < 65536) {
+      return LengthEncodingType.UInt16;
+    } else if (length < 4294967296) {
+      return LengthEncodingType.UInt32;
+    } else if (length < Number.MAX_SAFE_INTEGER) {
+      return LengthEncodingType.UInt64;
+    } else {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_LengthExceedsMaximum,
+      );
+    }
+  } else if (typeof length === 'bigint') {
+    if (length < 256n) {
+      return LengthEncodingType.UInt8;
+    } else if (length < 65536n) {
+      return LengthEncodingType.UInt16;
+    } else if (length < 4294967296n) {
+      return LengthEncodingType.UInt32;
+    } else if (length < 18446744073709551616n) {
+      return LengthEncodingType.UInt64;
+    } else {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_LengthExceedsMaximum,
+      );
+    }
+  } else {
+    throw new TranslatableSuiteError(
+      SuiteCoreStringKey.Error_LengthIsInvalidType,
+    );
+  }
+}
+
+/**
+ * Get the length encoding type for a given value
+ * @param value The value to evaluate
+ * @returns The corresponding LengthEncodingType
+ */
+export function getLengthEncodingTypeFromValue(
+  value: number,
+): LengthEncodingType {
+  for (const length of Object.values(LengthEncodingType)) {
+    if (length === value) {
+      return length;
+    }
+  }
+  throw new TranslatableSuiteError(
+    SuiteCoreStringKey.Error_LengthIsInvalidType,
+  );
+}
+
+/**
+ * Get the length in bytes for a given LengthEncodingType
+ * @param type The LengthEncodingType to evaluate
+ * @returns The length in bytes
+ */
+export function getLengthForLengthType(type: LengthEncodingType): number {
+  switch (type) {
+    case LengthEncodingType.UInt8:
+      return 1;
+    case LengthEncodingType.UInt16:
+      return 2;
+    case LengthEncodingType.UInt32:
+      return 4;
+    case LengthEncodingType.UInt64:
+      return 8;
+    default:
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_LengthIsInvalidType,
+      );
+  }
+}
+
+export function parseBackupCodes(
+  user: 'admin' | 'member' | 'system',
+  environment: Record<string, string | undefined>,
+): BackupCode[] {
+  const envVarMap: Record<'admin' | 'member' | 'system', string> = {
+    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: string) => new BackupCode(code.trim())) ||
+    [];
+  return backupCodes;
+}