@wildo-ai/saas-backend-lib 1.0.1

package/src/files/utils/file-validation.utils.ts

@@ -0,0 +1,753 @@
+/**
+ * File Validation Utilities
+ *
+ * Centralized validation functions for file-related inputs.
+ * All validation functions throw WildoError_Backend with VALIDATION error type.
+ */
+
+import { ErrorType, ErrorCustomMessageReference, FileUploaderEntityType, Resources_SharedUtils } from '@wildo-ai/saas-models';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+/**
+ * AppId format regex (alphanumeric + underscore/hyphen, no path separators)
+ */
+const APP_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * MIME type format regex (type/subtype with optional parameters)
+ */
+const MIME_TYPE_REGEX = /^[a-z]+\/[a-z0-9][a-z0-9!#$&\-\^_.]*$/i;
+
+/**
+ * Field name format regex for canonical file-field paths.
+ * Supports dotted nested schema paths (`profile.avatar`) while intentionally
+ * rejecting runtime array indices (`attachments[0].file`).
+ */
+const FIELD_NAME_REGEX = /^[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*$/;
+
+/**
+ * Maximum file size: 100MB (default, can be overridden via app-configuration)
+ *
+ * This is the platform-wide default maximum file size.
+ * Individual file constraints can be more restrictive (see DEFAULT_FILE_CONSTRAINT in file-constraint.types.ts).
+ * Applications can override this via app-configuration.storage.maxFileSize.
+ */
+export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+
+/**
+ * Resolve the effective max file size from app configuration.
+ *
+ * The runtime config is the source of truth when present, but file-entry points
+ * still need a defensive fallback for tests and early bootstrap seams that may
+ * not hydrate storage config.
+ */
+export function resolveConfiguredMaxFileSize(configuredMaxFileSize?: number | null): number {
+  return (
+    typeof configuredMaxFileSize === 'number'
+    && Number.isFinite(configuredMaxFileSize)
+    && configuredMaxFileSize > 0
+  )
+    ? configuredMaxFileSize
+    : DEFAULT_MAX_FILE_SIZE;
+}
+
+/**
+ * Validate fileId format (MongoDB ObjectId or UUID)
+ *
+ * Supports both:
+ * - MongoDB ObjectId: 24 hexadecimal characters
+ * - PostgreSQL UUID: 36 characters with dashes (8-4-4-4-12)
+ *
+ * @param fileId - The file ID to validate
+ * @param errorBuilder - Error builder service for creating errors
+ * @param executionContext - Optional execution context for error handling
+ * @param fieldName - Optional field name for error messages (defaults to 'fileId')
+ * @returns True if valid (never reached if validation fails - function throws)
+ * @throws WildoError_Backend if validation fails
+ *
+ * @note Returns `boolean` for consistency with `validateResourceId` pattern,
+ *       but return value is never used (function throws on error)
+ */
+export function validateFileId(
+  fileId: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'fileId'
+): boolean {
+  // Check for null or undefined
+  if (fileId === null || fileId === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  // Check if it's a string
+  if (typeof fileId !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_string',
+          actualType: typeof fileId,
+          message: `${fieldName} must be a string, got ${typeof fileId}`
+        }
+      }
+    );
+  }
+
+  // Use database-agnostic validation (accepts both ObjectId and UUID)
+  if (!Resources_SharedUtils.isValidResourceId(fileId)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'invalid_format',
+          value: fileId,
+          message: `${fieldName} must be a valid resource ID (MongoDB ObjectId or UUID), got invalid format`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate appId format (alphanumeric + underscore/hyphen, no path separators)
+ *
+ * @param appId - The app ID to validate
+ * @param errorBuilder - Error builder service for creating errors
+ * @param executionContext - Optional execution context for error handling
+ * @param fieldName - Optional field name for error messages (defaults to 'appId')
+ * @returns True if valid, throws WildoError_Backend if invalid
+ * @throws WildoError_Backend if validation fails
+ */
+export function validateAppId(
+  appId: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'appId'
+): boolean {
+  // Check for null or undefined
+  if (appId === null || appId === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.APP_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  // Check if it's a string
+  if (typeof appId !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.APP_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_string',
+          actualType: typeof appId,
+          message: `${fieldName} must be a string, got ${typeof appId}`
+        }
+      }
+    );
+  }
+
+  // Check if it's non-empty
+  if (appId.trim() === '') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.APP_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'empty_string',
+          message: `${fieldName} cannot be empty`
+        }
+      }
+    );
+  }
+
+  // Check format (alphanumeric + underscore/hyphen, no path separators)
+  if (!APP_ID_REGEX.test(appId)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.APP_ID_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'invalid_format',
+          value: appId,
+          message: `${fieldName} contains invalid characters. Only alphanumeric characters, underscores, and hyphens are allowed`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate resourceId format (MongoDB ObjectId)
+ * Reuses validateFileId logic since both are ObjectIds
+ */
+export function validateResourceId(
+  resourceId: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'resourceId'
+): boolean {
+  return validateFileId(resourceId, errorBuilder, executionContext, fieldName);
+}
+
+/**
+ * Validate organizationId format (MongoDB ObjectId)
+ * Reuses validateFileId logic since both are ObjectIds
+ */
+export function validateOrganizationId(
+  organizationId: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'organizationId'
+): boolean {
+  return validateFileId(organizationId, errorBuilder, executionContext, fieldName);
+}
+
+/**
+ * Validate resourceType (should be a valid ResourceType enum value)
+ * Note: This is a basic check - full validation requires ResourceRegistry
+ */
+export function validateResourceType(
+  resourceType: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'resourceType'
+): boolean {
+  if (resourceType === null || resourceType === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  if (typeof resourceType !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'not_string',
+          actualType: typeof resourceType,
+          message: `${fieldName} must be a string, got ${typeof resourceType}`
+        }
+      }
+    );
+  }
+
+  if (resourceType.trim() === '') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'empty_string',
+          message: `${fieldName} cannot be empty`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate fieldName (non-empty canonical dotted path)
+ */
+export function validateFieldName(
+  fieldName: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldNameParam: string = 'fieldName'
+): boolean {
+  if (fieldName === null || fieldName === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName: fieldNameParam,
+          reason: 'null_or_undefined',
+          message: `${fieldNameParam} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  if (typeof fieldName !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName: fieldNameParam,
+          reason: 'not_string',
+          actualType: typeof fieldName,
+          message: `${fieldNameParam} must be a string, got ${typeof fieldName}`
+        }
+      }
+    );
+  }
+
+  if (fieldName.trim() === '') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName: fieldNameParam,
+          reason: 'empty_string',
+          message: `${fieldNameParam} cannot be empty`
+        }
+      }
+    );
+  }
+
+  // Optional: Validate canonical dotted format (no runtime array indices)
+  if (!FIELD_NAME_REGEX.test(fieldName)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName: fieldNameParam,
+          reason: 'invalid_format',
+          value: fieldName,
+          message: `${fieldNameParam} contains invalid characters. Only alphanumeric characters, underscores, and dot-separated nested path segments are allowed`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate contentType (MIME type format)
+ */
+export function validateContentType(
+  contentType: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'contentType'
+): boolean {
+  if (contentType === null || contentType === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  if (typeof contentType !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'not_string',
+          actualType: typeof contentType,
+          message: `${fieldName} must be a string, got ${typeof contentType}`
+        }
+      }
+    );
+  }
+
+  if (contentType.trim() === '') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'empty_string',
+          message: `${fieldName} cannot be empty`
+        }
+      }
+    );
+  }
+
+  // Validate MIME type format (basic check)
+  // Remove parameters (e.g., "text/plain; charset=utf-8" -> "text/plain")
+  const mimeTypeWithoutParams = contentType.split(';')[0].trim();
+  if (!MIME_TYPE_REGEX.test(mimeTypeWithoutParams)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'invalid_mime_type_format',
+          value: contentType,
+          message: `${fieldName} must be a valid MIME type (e.g., "text/plain", "image/jpeg")`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate contentLength (positive number <= maxFileSize)
+ */
+export function validateContentLength(
+  contentLength: unknown,
+  maxFileSize: number,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'contentLength'
+): boolean {
+  if (contentLength === null || contentLength === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONTENT_LENGTH_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  // Convert to number if string
+  const numValue = typeof contentLength === 'string' ? parseInt(contentLength, 10) : Number(contentLength);
+
+  if (typeof numValue !== 'number' || isNaN(numValue)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONTENT_LENGTH_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_number',
+          actualValue: contentLength,
+          message: `${fieldName} must be a number, got ${typeof contentLength}`
+        }
+      }
+    );
+  }
+
+  if (!isFinite(numValue)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONTENT_LENGTH_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_finite',
+          actualValue: numValue,
+          message: `${fieldName} must be a finite number`
+        }
+      }
+    );
+  }
+
+  if (numValue <= 0) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONTENT_LENGTH_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_positive',
+          actualValue: numValue,
+          message: `${fieldName} must be greater than 0, got ${numValue}`
+        }
+      }
+    );
+  }
+
+  if (numValue > maxFileSize) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.CONTENT_LENGTH_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'exceeds_max_size',
+          actualValue: numValue,
+          maxFileSize,
+          message: `${fieldName} exceeds maximum file size of ${maxFileSize} bytes (${Math.round(maxFileSize / 1024 / 1024)}MB), got ${numValue} bytes`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate size (positive number <= maxFileSize)
+ * Same as validateContentLength but with different field name
+ */
+export function validateSize(
+  size: unknown,
+  maxFileSize: number,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'size'
+): boolean {
+  return validateContentLength(size, maxFileSize, errorBuilder, executionContext, fieldName);
+}
+
+/**
+ * Validate uploadedBy (optional resource ID)
+ */
+export function validateUploadedBy(
+  uploadedBy: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'uploadedBy'
+): boolean {
+  // Optional field - if undefined or null, return true
+  if (uploadedBy === null || uploadedBy === undefined) {
+    return true;
+  }
+
+  // If provided, must be a valid resource ID.
+  return validateFileId(uploadedBy, errorBuilder, executionContext, fieldName);
+}
+
+/**
+ * Validate uploadedByEntityType (optional enum value)
+ */
+export function validateUploadedByEntityType(
+  uploadedByEntityType: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'uploadedByEntityType'
+): boolean {
+  if (uploadedByEntityType === null || uploadedByEntityType === undefined) {
+    return true;
+  }
+
+  if (typeof uploadedByEntityType !== 'string') {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'not_string',
+          actualType: typeof uploadedByEntityType,
+          message: `${fieldName} must be a string enum value, got ${typeof uploadedByEntityType}`,
+        }
+      }
+    );
+  }
+
+  if (!Object.values(FileUploaderEntityType).includes(uploadedByEntityType as FileUploaderEntityType)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: {
+          fieldName,
+          reason: 'invalid_enum_value',
+          value: uploadedByEntityType,
+          allowedValues: Object.values(FileUploaderEntityType),
+          message: `${fieldName} must be a valid FileUploaderEntityType value`,
+        }
+      }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Sanitize filename for safe use in HTTP headers
+ *
+ * @param filename - The filename to sanitize
+ * @returns Sanitized filename safe for use in Content-Disposition header
+ */
+/**
+ * Sanitize filename for safe use in HTTP headers
+ *
+ * @param filename - The filename to sanitize
+ * @returns Sanitized filename safe for use in Content-Disposition header
+ */
+export function sanitizeFilename(filename: string): string {
+  if (!filename || typeof filename !== 'string') {
+    return 'file';
+  }
+
+  // Remove control characters (\x00-\x1F), quotes, newlines
+  let sanitized = filename
+    .replace(/[\x00-\x1F]/g, '') // Remove control characters
+    .replace(/["']/g, '') // Remove quotes
+    .replace(/[\n\r]/g, '') // Remove newlines
+    .replace(/[/\\]/g, '_') // Replace path separators with underscore
+    .trim();
+
+  // Limit length to 255 characters
+  if (sanitized.length > 255) {
+    // Keep extension if present
+    const lastDot = sanitized.lastIndexOf('.');
+    if (lastDot > 0) {
+      const extension = sanitized.substring(lastDot);
+      const nameWithoutExt = sanitized.substring(0, lastDot);
+      sanitized = nameWithoutExt.substring(0, 255 - extension.length) + extension;
+    } else {
+      sanitized = sanitized.substring(0, 255);
+    }
+  }
+
+  // If empty after sanitization, use default
+  if (sanitized === '') {
+    sanitized = 'file';
+  }
+
+  return sanitized;
+}
+
+/**
+ * Validate stream is readable and not destroyed
+ */
+export function validateStream(
+  stream: unknown,
+  errorBuilder: ErrorBuilderBackendService,
+  executionContext?: ExecutionContext<any>,
+  fieldName: string = 'stream'
+): boolean {
+  if (stream === null || stream === undefined) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.STREAM_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'null_or_undefined',
+          message: `${fieldName} cannot be null or undefined`
+        }
+      }
+    );
+  }
+
+  // Check if it's a Readable stream (has readable property)
+  if (typeof stream !== 'object' || !('readable' in stream)) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.STREAM_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'not_readable_stream',
+          actualType: typeof stream,
+          message: `${fieldName} must be a Readable stream`
+        }
+      }
+    );
+  }
+
+  const readableStream = stream as { readable?: boolean; destroyed?: boolean };
+
+  // Check if stream is readable
+  if (readableStream.readable === false) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.STREAM_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'stream_not_readable',
+          message: `${fieldName} stream is not readable`
+        }
+      }
+    );
+  }
+
+  // Check if stream is destroyed
+  if (readableStream.destroyed === true) {
+    throw errorBuilder.buildError(
+      ErrorType.VALIDATION,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.STREAM_VALIDATION_FAILED,
+        context: {
+          fieldName,
+          reason: 'stream_destroyed',
+          message: `${fieldName} stream has been destroyed`
+        }
+      }
+    );
+  }
+
+  return true;
+}
+