@wildo-ai/saas-backend-lib 1.0.1

package/src/files/services/files.backend.service.ts

@@ -0,0 +1,1356 @@
+/**
+ * Files Backend Service
+ *
+ * Manages file metadata and coordinates with storage providers (MinIO/S3).
+ * Files are stored in external storage, this service tracks metadata in MongoDB.
+ *
+ * Features:
+ * - File upload coordination
+ * - File metadata management
+ * - File linking to resources
+ * - File access authorization
+ * - File lifecycle management (status tracking)
+ */
+
+import { injectable, inject } from 'inversify';
+import { CoreResourceOperation, CoreResourceType, ResourceType, ErrorType, ErrorCustomMessageReference, FileUploaderEntityType, type FileUploaderOwnership, ResourcePrimaryScope, Resources_SharedUtils, isWildoBackendError } from '@wildo-ai/saas-models';
+import { File, FileStatus, FILE_STATUS_TRANSITIONS, FileScopeIdentifiers, FileScopeUtils } from '@wildo-ai/saas-models';
+import { resolveFileDisplayNature, type FileDisplayNature, type FileStorageAccepted } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import { ResourceOperationHelperBackendService } from '~wildo-backend-lib/base-classes/services/resource-operations-helper.backend.service';
+import type { BackendResourceRepository } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { RepositoryOptions } from '~wildo-backend-lib/base-classes/models/repositories.backend.schemas';
+import { Types } from 'mongoose';
+import { validateFileId, validateResourceId, validateResourceType, validateFieldName, validateSize, validateUploadedBy, validateUploadedByEntityType, validateOrganizationId, validateContentType, resolveConfiguredMaxFileSize } from '~wildo-backend-lib/files/utils/file-validation.utils';
+import { resolveFileUploaderPrincipal } from '~wildo-backend-lib/files/utils/file-uploader.utils';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { FileStorageRouterBackendService } from '~wildo-backend-lib/files/storage/file-storage-router.backend.service';
+import type { IFileStorageProvider, StorageUploadResult } from '~wildo-backend-lib/files/storage/file-storage-provider.types';
+
+@injectable()
+export class FilesBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger)
+    private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService)
+    private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService)
+    private readonly resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)
+    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)
+    private readonly executionContextCreator: ExecutionContextCreatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceOperationHelperService)
+    private readonly resourceOperationHelper: ResourceOperationHelperBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileStorageRouter)
+    private readonly fileStorageRouter: FileStorageRouterBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService)
+    private readonly appConfigService: AppConfigurationService,
+  ) {
+    this.logDebug = this.logger.debugByType('FilesBackendService');
+    this.logger.setDebugTypeLogging('FilesBackendService', false);
+
+    this.logDebug('FilesBackendService initialized');
+  }
+
+  /**
+   * Get the files repository for internal operations.
+   * Lazy getter to ensure repository is initialized.
+   */
+  private get filesRepository(): BackendResourceRepository<any, any, any> {
+    return this.repositoriesRegistry.getRepositoryOrThrow(CoreResourceType.FILES, {} as ExecutionContext<any>);
+  }
+
+  private getDefaultStorageProvider(): IFileStorageProvider {
+    return this.fileStorageRouter.getDefaultProvider();
+  }
+
+  public getStorageProviderForFile(
+    file: Pick<File, 'fileId' | 'storageProvider' | 'storageRef'>,
+    executionContext: ExecutionContext<any>,
+  ): IFileStorageProvider {
+    if (!file.storageProvider) {
+      this.logDebug('Falling back to default storage provider for legacy file row', {
+        fileId: file.fileId,
+      });
+      return this.getDefaultStorageProvider();
+    }
+
+    const provider = this.fileStorageRouter.getProviderById(file.storageProvider);
+    if (!provider) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'No registered storage provider matches the persisted file routing',
+            fileId: file.fileId,
+            storageProvider: file.storageProvider,
+          },
+        }
+      );
+    }
+
+    return provider;
+  }
+
+  /**
+   * Create an internal execution context for file operations.
+   * Preserves initiatorIds and roles from the provided context.
+   */
+  private async createInternalExecutionContext(
+    operation: CoreResourceOperation,
+    providedContext: ExecutionContext<any>
+  ): Promise<ExecutionContext<any>> {
+    const operationPath = this.resourcesRegistry.getOperationPathDefault(
+      CoreResourceType.FILES,
+      operation
+    );
+
+    const initiatorIds = providedContext.initiatorIds || null;
+    // Create mutable copy of readonly array
+    const initiatorRoles = providedContext.initiatorRoles ? [...providedContext.initiatorRoles] : [];
+
+    return this.executionContextCreator.createForInternalOperation({
+      operation: operationPath,
+      contextResourcesFieldIdentifier: new Map(),
+      initiatorIds,
+      initiatorRoles,
+    });
+  }
+
+  /**
+   * Create a new file record with status PENDING.
+   * Called before upload starts to reserve the fileId.
+   *
+   * Scope can be provided at creation time (when known) or derived later
+   * when linking to a resource via linkFileToResource().
+   *
+   * @param fileData - Initial file data (filename, mimeType, size, etc.)
+   * @param executionContext - Execution context for authorization
+   * @param options - Repository options
+   * @returns Created file record with fileId
+   */
+  async createFile(
+    fileData: {
+      filename: string;
+      originalFilename: string;
+      mimeType: string;
+      size: number;
+      extension?: string;
+      checksum?: string;
+      /** Resolved storage provider. Falls back to default when omitted. */
+      storageProvider?: FileStorageAccepted;
+      // Scope identifiers - segregated (not hierarchical)
+      // If not provided, will be derived when linking to resource
+      scope?: FileScopeIdentifiers;
+      // Legacy: organizationId for backward compatibility
+      // Use scope.organizationId instead for new code
+      organizationId?: string;
+    } & FileUploaderOwnership,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File> {
+    // Validate inputs (CRITICAL: Prevents invalid data propagation)
+    const maxFileSize = resolveConfiguredMaxFileSize(this.appConfigService.config.storage?.maxFileSize);
+    validateContentType(fileData.mimeType, this.errorBuilder, executionContext, 'mimeType');
+    validateSize(fileData.size, maxFileSize, this.errorBuilder, executionContext, 'size');
+    const hasExplicitUploadedBy = fileData.uploadedBy !== undefined;
+    const hasExplicitUploaderEntityType = fileData.uploadedByEntityType !== undefined;
+    if (hasExplicitUploadedBy !== hasExplicitUploaderEntityType) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: 'uploadedBy and uploadedByEntityType must either both be set or both be omitted',
+            uploadedBy: fileData.uploadedBy,
+            uploadedByEntityType: fileData.uploadedByEntityType,
+          },
+        }
+      );
+    }
+
+    if (hasExplicitUploadedBy && hasExplicitUploaderEntityType) {
+      validateUploadedBy(fileData.uploadedBy, this.errorBuilder, executionContext, 'uploadedBy');
+      validateUploadedByEntityType(fileData.uploadedByEntityType, this.errorBuilder, executionContext, 'uploadedByEntityType');
+    }
+
+    // Validate scope if provided
+    if (fileData.scope && !FileScopeUtils.validate(fileData.scope)) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: 'Invalid scope identifiers for the specified primaryScope',
+            scope: fileData.scope,
+          },
+        }
+      );
+    }
+
+    // Derive organizationId from scope or use legacy field
+    const organizationId = fileData.scope?.organizationId || fileData.organizationId;
+    if (organizationId) {
+      validateOrganizationId(organizationId, this.errorBuilder, executionContext, 'organizationId');
+    }
+
+    this.logDebug('Creating file record', {
+      filename: fileData.filename,
+      primaryScope: fileData.scope?.primaryScope,
+      organizationId,
+    });
+
+    // Generate fileId (MongoDB ObjectId as string)
+    const fileId = new Types.ObjectId().toString();
+
+    // Extract extension from filename if not provided
+    const extension = fileData.extension || this.extractExtension(fileData.originalFilename);
+
+    // Build storage key based on scope (if provided) or use fileId as fallback
+    const storageKey = fileData.scope
+      ? FileScopeUtils.buildStoragePath(fileData.scope, fileId)
+      : fileId;
+    const resolvedStorageProviderId = fileData.storageProvider ?? this.getDefaultStorageProvider().providerId;
+
+    const derivedUploader = resolveFileUploaderPrincipal(executionContext);
+    const uploaderPrincipal = hasExplicitUploadedBy && hasExplicitUploaderEntityType
+      ? {
+          uploadedBy: fileData.uploadedBy!,
+          uploadedByEntityType: fileData.uploadedByEntityType!,
+        }
+      : derivedUploader;
+
+    if (
+      hasExplicitUploadedBy
+      && hasExplicitUploaderEntityType
+      && derivedUploader
+      && (
+        fileData.uploadedBy !== derivedUploader.uploadedBy
+        || fileData.uploadedByEntityType !== derivedUploader.uploadedByEntityType
+      )
+    ) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: 'Explicit uploader ownership must match the current execution principal',
+            uploadedBy: fileData.uploadedBy,
+            uploadedByEntityType: fileData.uploadedByEntityType,
+            derivedUploadedBy: derivedUploader.uploadedBy,
+            derivedUploadedByEntityType: derivedUploader.uploadedByEntityType,
+          },
+        }
+      );
+    }
+
+    // Prepare file record data
+    const fileRecord: Partial<File> = {
+      fileId,
+      filename: fileData.filename,
+      originalFilename: fileData.originalFilename,
+      mimeType: fileData.mimeType,
+      size: fileData.size,
+      extension: extension || undefined,
+      checksum: fileData.checksum,
+      storageProvider: resolvedStorageProviderId,
+      storageKey,
+      status: FileStatus.PENDING,
+      uploadedBy: uploaderPrincipal?.uploadedBy,
+      uploadedByEntityType: uploaderPrincipal?.uploadedByEntityType,
+      // Scope identifiers (segregated)
+      primaryScope: fileData.scope?.primaryScope,
+      applicationId: fileData.scope?.applicationId,
+      organizationId: organizationId,
+      userId: fileData.scope?.userId,
+    };
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.CREATE,
+      executionContext
+    );
+
+    // Create file record via repository
+    const createdFile = await this.filesRepository.create<File>(
+      internalContext,
+      fileRecord as File,
+      options
+    );
+
+    this.logDebug('File record created', { fileId: createdFile.fileId });
+    return createdFile;
+  }
+
+  /**
+   * Get file metadata by fileId.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context for authorization
+   * @returns File metadata or null if not found
+   */
+  async getFile(
+    fileId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File | null> {
+    this.logDebug('Getting file record', { fileId });
+
+    // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.READ,
+      executionContext
+    );
+
+    // Read file record via repository
+    const file = await this.filesRepository.read<File>(
+      internalContext,
+      { fileId },
+      options
+    );
+
+    if (!file) {
+      this.logDebug('File not found', { fileId });
+      return null;
+    }
+
+    // Check authorization
+    const hasAccess = await this.authorizeFileAccess(file, executionContext);
+    if (!hasAccess) {
+        throw this.errorBuilder.buildError(
+          ErrorType.AUTHORIZATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+          context: {
+            message: 'Access denied to file',
+            fileId,
+          },
+        }
+      );
+    }
+
+    return file;
+  }
+
+  /**
+   * Get multiple files by their IDs.
+   *
+   * @param fileIds - Array of file identifiers
+   * @param executionContext - Execution context for authorization
+   * @returns Array of file metadata
+   */
+  async batchGetFiles(
+    fileIds: string[],
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File[]> {
+    this.logDebug('Batch getting file records', { fileIds, count: fileIds.length });
+
+    if (fileIds.length === 0) {
+      return [];
+    }
+
+    // Filter and validate fileIds format before query
+    // This optimization prevents unnecessary MongoDB queries when all fileIds are invalid
+    // Uses the same ObjectId regex pattern as validateFileId() utility (case-insensitive)
+    const validFileIds = fileIds.filter(
+      (id) => typeof id === 'string' && id.trim() !== '' && Resources_SharedUtils.isValidResourceId(id.trim())
+    );
+
+    // Early return if no valid fileIds after filtering
+    if (validFileIds.length === 0) {
+      return [];
+    }
+
+    const accessibleScopeFilter = this.buildAccessibleScopeFilter(executionContext);
+    if (!accessibleScopeFilter) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: 'applicationId or organizationId is required in execution context for file access',
+            fileIdsCount: fileIds.length,
+          },
+        }
+      );
+    }
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.READ,
+      executionContext
+    );
+
+    // Add the narrowest tenant-aware filter we can BEFORE fetching.
+    // This prevents cross-tenant prefetches for app-scoped files while preserving
+    // legacy org-scoped rows until all persisted file records carry primaryScope.
+    const files = await this.filesRepository.list<File>(
+      internalContext,
+      {
+        fileId: { $in: validFileIds },
+        ...accessibleScopeFilter,
+      },
+      options
+    );
+
+    // Filter by authorization
+    const authorizedFiles: File[] = [];
+    for (const file of files) {
+      const hasAccess = await this.authorizeFileAccess(file, executionContext);
+      if (hasAccess) {
+        authorizedFiles.push(file);
+      }
+    }
+
+    this.logDebug('Batch get completed', { requested: fileIds.length, found: files.length, authorized: authorizedFiles.length });
+    return authorizedFiles;
+  }
+
+  /**
+   * Update file status (e.g., PENDING -> UPLOADED, UPLOADED -> LINKED).
+   *
+   * @param fileId - File identifier
+   * @param status - New status
+   * @param executionContext - Execution context for authorization
+   * @returns Updated file record
+   */
+  async updateFileStatus(
+    fileId: string,
+    status: FileStatus,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions,
+    storagePlacement?: StorageUploadResult,
+  ): Promise<File> {
+    this.logDebug('Updating file status', { fileId, status });
+
+    // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    // Get current file record
+    const currentFile = await this.getFile(fileId, executionContext, options);
+    if (!currentFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+          context: {
+            message: 'File not found',
+            fileId,
+          },
+        }
+      );
+    }
+
+    const allowedTransitions = FILE_STATUS_TRANSITIONS[currentFile.status];
+    if (!allowedTransitions?.includes(status)) {
+      throw this.errorBuilder.buildError(
+        ErrorType.BUSINESS_RULE,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+          context: {
+            message: 'Invalid file status transition',
+            fileId,
+            currentStatus: currentFile.status,
+            requestedStatus: status,
+            allowedTransitions,
+          },
+        }
+      );
+    }
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.UPDATE,
+      executionContext
+    );
+
+    // Update file status via repository
+    const updatedFile = await this.filesRepository.update<File>(
+      internalContext,
+      { fileId },
+      {
+        status,
+        ...(storagePlacement
+          ? {
+              storageProvider: storagePlacement.provider,
+              storageRef: storagePlacement.storageRef,
+            }
+          : {}),
+        updatedAt: new Date(),
+      } as Partial<File>,
+      options
+    );
+
+    if (!updatedFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'Failed to update file status',
+            fileId,
+            status,
+          },
+        }
+      );
+    }
+
+    this.logDebug('File status updated', { fileId, oldStatus: currentFile.status, newStatus: status });
+    return updatedFile;
+  }
+
+  /**
+   * Link a file to a resource (resource-integrated uploads).
+   * Updates file status to LINKED, stores resource reference, and derives scope
+   * from the parent resource's resourcePrimaryScope.
+   *
+   * Scope derivation:
+   * - APPLICATION: applicationId from execution context
+   * - ORGANIZATIONS: organizationId from execution context
+   * - USER_SELF: organizationId + userId from execution context
+   *
+   * @param fileId - File identifier
+   * @param resourceType - Resource type
+   * @param resourceId - Resource identifier
+   * @param fieldName - Field name on the resource
+   * @param executionContext - Execution context for authorization
+   * @returns Updated file record
+   */
+  async linkFileToResource(
+    fileId: string,
+    resourceType: ResourceType,
+    resourceId: string,
+    fieldName: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File> {
+    this.logDebug('Linking file to resource', { fileId, resourceType, resourceId, fieldName });
+
+    // Validate inputs (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+    validateResourceId(resourceId, this.errorBuilder, executionContext, 'resourceId');
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+    validateFieldName(fieldName, this.errorBuilder, executionContext, 'fieldName');
+
+    // Derive scope from parent resource's resourcePrimaryScope
+    const derivedScope = this.deriveScopeFromParentResource(resourceType, executionContext);
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.UPDATE,
+      executionContext
+    );
+
+    // CRITICAL: Use atomic update with status filter to prevent race conditions (Decision 2.4: Option A)
+    // The repository's update() method internally uses findOneAndUpdate, so it's atomic
+    // Filter includes status check: only updates if file is in UPLOADED status
+    // This ensures no race condition between check and update
+
+    /**
+     * Updates file status, link fields, and scope atomically.
+     *
+     * @note MongoDB updates are atomic, so partial updates are not possible.
+     * If the update fails, the entire operation fails atomically.
+     */
+    const updatedFile = await this.filesRepository.update<File>(
+      internalContext,
+      {
+        fileId: fileId,
+        status: { $in: [FileStatus.UPLOADED, FileStatus.CLEAN, FileStatus.INDEXED] },
+      },
+      {
+        linkedResourceType: resourceType,
+        linkedResourceId: resourceId,
+        linkedFieldName: fieldName,
+        status: FileStatus.LINKED,
+        updatedAt: new Date(),
+        // Scope derived from parent resource
+        primaryScope: derivedScope.primaryScope,
+        applicationId: derivedScope.applicationId,
+        organizationId: derivedScope.organizationId,
+        userId: derivedScope.userId,
+        // Update storageKey if scope wasn't set at creation time
+        storageKey: FileScopeUtils.buildStoragePath(derivedScope, fileId),
+      } as Partial<File>,
+      options
+    );
+
+    if (!updatedFile) {
+      // File was not in a linkable status (race condition or already linked)
+      // Re-fetch to determine the reason and throw appropriate error
+      const currentFile = await this.getFile(fileId, executionContext, options);
+      if (!currentFile) {
+        throw this.errorBuilder.buildError(
+          ErrorType.NOT_FOUND,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+            context: {
+              message: 'File not found',
+              fileId,
+            },
+          }
+        );
+      }
+
+      // Check if already linked to same resource (idempotent case)
+      if (currentFile.status === FileStatus.LINKED &&
+          currentFile.linkedResourceType === resourceType &&
+          currentFile.linkedResourceId === resourceId &&
+          currentFile.linkedFieldName === fieldName) {
+        // Already linked to same resource - idempotent, return current file
+        this.logDebug('File already linked to same resource (idempotent)', {
+          fileId,
+          resourceType,
+          resourceId,
+          fieldName,
+        });
+        return currentFile;
+      }
+
+      // Check if already linked to different resource (error case)
+      if (currentFile.status === FileStatus.LINKED) {
+        throw this.errorBuilder.buildError(
+          ErrorType.BUSINESS_RULE,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+            context: {
+              message: 'File is already linked to a different resource',
+              fileId,
+              currentLinkedResourceType: currentFile.linkedResourceType,
+              currentLinkedResourceId: currentFile.linkedResourceId,
+              currentLinkedFieldName: currentFile.linkedFieldName,
+              requestedResourceType: resourceType,
+              requestedResourceId: resourceId,
+              requestedFieldName: fieldName,
+            },
+          }
+        );
+      }
+
+      // Wrong status (not UPLOADED)
+      throw this.errorBuilder.buildError(
+        ErrorType.BUSINESS_RULE,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.BUSINESS_RULE,
+          context: {
+            message: 'File must be in UPLOADED status before linking to resource',
+            fileId,
+            fileStatus: currentFile.status,
+            expectedStatus: FileStatus.UPLOADED,
+            resourceType,
+            resourceId,
+          },
+        }
+      );
+    }
+
+    this.logDebug('File linked to resource', { fileId, resourceType, resourceId });
+    return updatedFile;
+  }
+
+  /**
+   * Unlink a file from a resource.
+   * Updates file status to ORPHANED and clears resource link fields.
+   *
+   * Note: Due to Mongoose behavior, optional fields set to `undefined` are ignored in updates.
+   * We attempt to clear linked resource fields, but if schema validation prevents this,
+   * the status change to ORPHANED is the authoritative indicator that the file is unlinked.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context for authorization
+   * @returns Updated file record
+   */
+  async unlinkFileFromResource(
+    fileId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File> {
+    this.logDebug('Unlinking file from resource', { fileId });
+
+    // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    // Get current file record
+    const currentFile = await this.getFile(fileId, executionContext, options);
+    if (!currentFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+          context: {
+            message: 'File not found',
+            fileId,
+          },
+        }
+      );
+    }
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.UPDATE,
+      executionContext
+    );
+
+    // Update file to remove resource link and set status to ORPHANED
+    // Note: Mongoose ignores undefined values in updates, and optional string fields don't accept null.
+    // The status change to ORPHANED is the authoritative indicator that the file is no longer linked.
+    // The linked resource fields may remain in the database but are considered stale/invalid when status is ORPHANED.
+    // Future enhancement: If explicit field clearing is required, consider using MongoDB $unset operator
+    // via direct Mongoose model access or repository enhancement.
+    const updateData: Partial<File> = {
+      status: FileStatus.ORPHANED,
+      updatedAt: new Date(),
+    };
+
+    /**
+     * Updates file status and clears link fields atomically.
+     *
+     * @note MongoDB updates are atomic, so partial updates are not possible.
+     * If the update fails, the entire operation fails atomically.
+     */
+    const updatedFile = await this.filesRepository.update<File>(
+      internalContext,
+      { fileId },
+      updateData,
+      options
+    );
+
+    if (!updatedFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'Failed to unlink file from resource',
+            fileId,
+          },
+        }
+      );
+    }
+
+    this.logDebug('File unlinked from resource', { fileId });
+    return updatedFile;
+  }
+
+  /**
+   * Delete a file (soft delete - marks as DELETED).
+   * Physical deletion from storage happens in cleanup batch job.
+   *
+   * @param fileId - File identifier
+   * @param executionContext - Execution context for authorization
+   * @returns Deleted file record
+   */
+  async deleteFile(
+    fileId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File> {
+    this.logDebug('Soft deleting file record', { fileId });
+
+    // Validate fileId format (CRITICAL: Prevents query injection and database errors)
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    // Get current file record
+    const currentFile = await this.getFile(fileId, executionContext, options);
+    if (!currentFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+          context: {
+            message: 'File not found',
+            fileId,
+          },
+        }
+      );
+    }
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.UPDATE,
+      executionContext
+    );
+
+    // Soft delete: update status and set deletedAt
+
+    /**
+     * Updates file status to DELETED atomically.
+     *
+     * @note MongoDB updates are atomic, so partial updates are not possible.
+     * If the update fails, the entire operation fails atomically.
+     */
+    const deletedFile = await this.filesRepository.update<File>(
+      internalContext,
+      { fileId },
+      {
+        status: FileStatus.DELETED,
+        deletedAt: new Date(),
+        updatedAt: new Date(),
+      } as Partial<File>,
+      options
+    );
+
+    if (!deletedFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'Failed to delete file',
+            fileId,
+          },
+        }
+      );
+    }
+
+    this.logDebug('File soft deleted', { fileId });
+    return deletedFile;
+  }
+
+  /**
+   * Permanently delete a file by removing the blob first, then deleting the
+   * metadata row. This is intentionally reserved for post-commit cleanup flows
+   * such as the cleanup batch, not inline resource transactions.
+   */
+  async hardDeleteFile(
+    fileId: string,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File> {
+    this.logDebug('Hard deleting file record and storage', { fileId });
+
+    validateFileId(fileId, this.errorBuilder, executionContext, 'fileId');
+
+    const readContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.READ,
+      executionContext
+    );
+    const currentFile = await this.filesRepository.read<File>(
+      readContext,
+      { fileId },
+      options
+    );
+
+    if (!currentFile) {
+      throw this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+          context: {
+            message: 'File not found',
+            fileId,
+          },
+        }
+      );
+    }
+
+    // Hard-delete now flows through the storage provider seam so future slices can
+    // swap backend resolution without reopening the cleanup contract.
+    try {
+      const storageProvider = this.getStorageProviderForFile(currentFile, executionContext);
+      await storageProvider.delete(currentFile, executionContext);
+    } catch (error) {
+      if (!isWildoBackendError(error) || error.type !== ErrorType.NOT_FOUND) {
+        throw error;
+      }
+
+      this.logDebug('File blob already missing during hard delete, continuing metadata cleanup', {
+        fileId,
+      });
+    }
+
+    const deleteContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.DELETE,
+      executionContext
+    );
+    const deletedFileId = await this.filesRepository.delete(
+      deleteContext,
+      { fileId },
+      options
+    );
+
+    if (!deletedFileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'Failed to hard delete file',
+            fileId,
+          },
+        }
+      );
+    }
+
+    this.logDebug('File hard deleted from storage and metadata', { fileId });
+    return currentFile;
+  }
+
+  /**
+   * List files for a specific resource.
+   *
+   * @param resourceType - Resource type
+   * @param resourceId - Resource identifier
+   * @param fieldName - Optional field name filter
+   * @param executionContext - Execution context for authorization
+   * @returns Array of file metadata
+   */
+  async listFilesForResource(
+    resourceType: ResourceType,
+    resourceId: string,
+    fieldName: string | undefined,
+    executionContext: ExecutionContext<any>,
+    options?: RepositoryOptions
+  ): Promise<File[]> {
+    if (!executionContext) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        {} as ExecutionContext<any>,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'Execution context is required for listFilesForResource',
+          },
+        }
+      );
+    }
+
+    this.logDebug('Listing files for resource', { resourceType, resourceId, fieldName });
+
+    // Validate inputs (CRITICAL: Prevents query injection and database errors)
+    validateResourceId(resourceId, this.errorBuilder, executionContext, 'resourceId');
+    validateResourceType(resourceType, this.errorBuilder, executionContext, 'resourceType');
+    if (fieldName) {
+      validateFieldName(fieldName, this.errorBuilder, executionContext, 'fieldName');
+    }
+
+    const derivedScope = this.deriveScopeFromParentResource(resourceType, executionContext);
+    const scopeFilter = this.buildFilterForFileScope(derivedScope);
+    if (!scopeFilter) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        executionContext,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            message: 'Unable to derive file access scope from execution context',
+          },
+        }
+      );
+    }
+
+    // Build filter
+    // Be defensive against malformed persisted rows where link metadata was
+    // written but status drifted from LINKED. Delete-time cleanup must still be
+    // able to discover those rows by parent ownership.
+    const filter: any = {
+      linkedResourceType: resourceType,
+      linkedResourceId: resourceId,
+      status: {
+        $in: [FileStatus.LINKED, FileStatus.UPLOADED, FileStatus.CLEAN, FileStatus.INDEXED],
+      },
+      ...scopeFilter,
+    };
+
+    if (fieldName) {
+      filter.linkedFieldName = fieldName;
+    }
+
+    // Create internal execution context for repository operation
+    const internalContext = await this.createInternalExecutionContext(
+      CoreResourceOperation.LIST,
+      executionContext
+    );
+
+    // Apply the linked resource's derived scope to the repository query before fetch.
+    // This keeps app-scoped parents from going through an org-only path.
+    const files = await this.filesRepository.list<File>(
+      internalContext,
+      filter,
+      options
+    );
+
+    // Filter by authorization
+    const authorizedFiles: File[] = [];
+    for (const file of files) {
+      const hasAccess = await this.authorizeFileAccess(file, executionContext);
+      if (hasAccess) {
+        authorizedFiles.push(file);
+      }
+    }
+
+    this.logDebug('List files for resource completed', { resourceType, resourceId, found: files.length, authorized: authorizedFiles.length });
+    return authorizedFiles;
+  }
+
+  /**
+   * Authorize file access based on file's primaryScope.
+   *
+   * Access rules by primaryScope:
+   * - APPLICATION: User must have access to the application
+   * - ORGANIZATIONS: User must belong to the organization
+   * - USER_SELF: User must be the owner (userId match) AND belong to the org
+   *
+   * Fallback (no primaryScope): Uses legacy organizationId match
+   *
+   * @param file - File record
+   * @param executionContext - Execution context for authorization
+   * @returns true if access is allowed
+   */
+  async authorizeFileAccess(
+    file: File,
+    executionContext: ExecutionContext<any>
+  ): Promise<boolean> {
+    const accessScope = this.deriveAccessScope(executionContext);
+
+    // Legacy scope-less rows are tolerated only when they still carry a concrete
+    // organization owner. Missing organization ownership is treated as malformed
+    // persisted data and must fail closed.
+    if (!file.primaryScope) {
+      if (!file.organizationId || !accessScope.organizationId) {
+        this.logDebug('File access denied: missing organization ownership on legacy file', {
+          fileOrganizationId: file.organizationId,
+          requestOrganizationId: accessScope.organizationId,
+        });
+        return false;
+      }
+
+      if (file.organizationId !== accessScope.organizationId) {
+        this.logDebug('File access denied: organization mismatch (legacy)', {
+          fileOrganizationId: file.organizationId,
+          requestOrganizationId: accessScope.organizationId,
+        });
+        return false;
+      }
+      return true;
+    }
+
+    // Scope-based authorization
+    switch (file.primaryScope) {
+      case ResourcePrimaryScope.APPLICATION:
+        if (!file.applicationId || file.applicationId !== accessScope.applicationId) {
+          this.logDebug('File access denied: application mismatch', {
+            fileApplicationId: file.applicationId,
+            requestApplicationId: accessScope.applicationId,
+          });
+          return false;
+        }
+        return true;
+
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        // ORGANIZATIONS scope: user must belong to the organization
+        if (file.organizationId !== accessScope.organizationId) {
+          this.logDebug('File access denied: organization mismatch', {
+            fileOrganizationId: file.organizationId,
+            requestOrganizationId: accessScope.organizationId,
+          });
+          return false;
+        }
+        return true;
+
+      case ResourcePrimaryScope.USER_SELF:
+        // USER_SELF scope: user must be the owner AND belong to the org
+        if (file.organizationId !== accessScope.organizationId) {
+          this.logDebug('File access denied: organization mismatch (USER_SELF)', {
+            fileOrganizationId: file.organizationId,
+            requestOrganizationId: accessScope.organizationId,
+          });
+          return false;
+        }
+        if (file.userId !== accessScope.userId) {
+          this.logDebug('File access denied: user mismatch', {
+            fileUserId: file.userId,
+            requestUserId: accessScope.userId,
+          });
+          return false;
+        }
+        return true;
+
+      default:
+        // Unknown scope - deny access
+        this.logDebug('File access denied: unknown primaryScope', {
+          primaryScope: file.primaryScope,
+        });
+        return false;
+    }
+  }
+
+  /**
+   * Convert File record to FileMetadata response format.
+   * Used by the getMetadata endpoint.
+   *
+   * @param file - File record
+   * @returns FileMetadata object
+   */
+  toMetadataResponse(file: File): {
+    fileId: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    extension?: string;
+    checksum?: string;
+    url?: string;
+    thumbnailUrl?: string;
+    nature: FileDisplayNature;
+    width?: number;
+    height?: number;
+    duration?: number;
+    pageCount?: number;
+    uploadedAt: Date;
+    uploadedBy?: string;
+    uploadedByEntityType?: FileUploaderEntityType;
+  } {
+    // Infer nature from MIME type if not stored on the file record
+    // Uses the shared resolveFileDisplayNature() utility (single source of truth)
+    const nature: FileDisplayNature = (file.nature as FileDisplayNature) ?? resolveFileDisplayNature(undefined, file.mimeType);
+
+    return {
+      fileId: file.fileId,
+      filename: file.originalFilename || file.filename,
+      size: file.size,
+      mimeType: file.mimeType,
+      extension: file.extension,
+      checksum: file.checksum,
+      url: file.url,
+      thumbnailUrl: file.thumbnailUrl,
+      nature,
+      width: file.width,
+      height: file.height,
+      duration: file.duration,
+      pageCount: file.pageCount,
+      uploadedAt: file.uploadedAt,
+      uploadedBy: file.uploadedBy,
+      uploadedByEntityType: file.uploadedByEntityType,
+    };
+  }
+
+  /**
+   * Derive access scope from execution context.
+   * Extracts all scope identifiers for authorization checks.
+   *
+   * @param executionContext - Execution context
+   * @returns Access scope information with all identifiers
+   */
+  protected deriveAccessScope(executionContext: ExecutionContext<any>): {
+    applicationId?: string;
+    organizationId?: string;
+    userId?: string;
+  } {
+    const organizationId = this.resourceOperationHelper.getInitiatorId(executionContext, 'organization');
+    const userId = this.resourceOperationHelper.getInitiatorId(executionContext, 'user');
+    const applicationId = executionContext.applicationId;
+
+    return {
+      applicationId,
+      organizationId,
+      userId,
+    };
+  }
+
+  /**
+   * Build the narrowest repository filter we can from the caller's accessible scope.
+   * This keeps prefetching tenant-aware even before per-row authorization runs.
+   */
+  protected buildAccessibleScopeFilter(
+    executionContext: ExecutionContext<any>,
+  ): Record<string, unknown> | null {
+    const accessScope = this.deriveAccessScope(executionContext);
+    const scopeBranches: Record<string, unknown>[] = [];
+
+    if (accessScope.applicationId) {
+      scopeBranches.push({
+        primaryScope: ResourcePrimaryScope.APPLICATION,
+        applicationId: accessScope.applicationId,
+      });
+    }
+
+    if (accessScope.organizationId) {
+      // Keep legacy org-only rows reachable until all file rows carry primaryScope.
+      scopeBranches.push({
+        organizationId: accessScope.organizationId,
+      });
+    }
+
+    if (scopeBranches.length === 0) {
+      return null;
+    }
+
+    return scopeBranches.length === 1 ? scopeBranches[0] : { $or: scopeBranches };
+  }
+
+  protected buildFilterForFileScope(
+    scope: FileScopeIdentifiers,
+  ): Record<string, unknown> | null {
+    switch (scope.primaryScope) {
+      case ResourcePrimaryScope.APPLICATION:
+        return scope.applicationId
+          ? {
+              primaryScope: ResourcePrimaryScope.APPLICATION,
+              applicationId: scope.applicationId,
+            }
+          : null;
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        return scope.organizationId
+          ? {
+              organizationId: scope.organizationId,
+            }
+          : null;
+      case ResourcePrimaryScope.USER_SELF:
+        return scope.organizationId && scope.userId
+          ? {
+              primaryScope: ResourcePrimaryScope.USER_SELF,
+              organizationId: scope.organizationId,
+              userId: scope.userId,
+            }
+          : null;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Derive file scope from parent resource's resourcePrimaryScope.
+   *
+   * Scope derivation rules:
+   * - APPLICATION: sets applicationId from execution context
+   * - ORGANIZATIONS: sets organizationId from execution context
+   * - USER_SELF: sets organizationId + userId from execution context
+   *
+   * @param resourceType - Parent resource type
+   * @param executionContext - Execution context for scope values
+   * @returns FileScopeIdentifiers derived from parent resource
+   */
+  protected deriveScopeFromParentResource(
+    resourceType: ResourceType,
+    executionContext: ExecutionContext<any>
+  ): FileScopeIdentifiers {
+    // Get parent resource configuration to find its primaryScope
+    const resourceConfig = this.resourcesRegistry.getResourceConfiguration(resourceType);
+
+    // Get primaryScope from resource configuration
+    // Default to ORGANIZATIONS if not specified
+    const primaryScope = resourceConfig?.resourcePrimaryScope || ResourcePrimaryScope.ORGANIZATIONS;
+
+    const accessScope = this.deriveAccessScope(executionContext);
+
+    switch (primaryScope) {
+      case ResourcePrimaryScope.APPLICATION:
+        if (!accessScope.applicationId) {
+          throw this.errorBuilder.buildError(
+            ErrorType.VALIDATION,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.VALIDATION,
+              context: {
+                message: 'Application ID is required for APPLICATION-scoped resources',
+                resourceType,
+              },
+            }
+          );
+        }
+        return {
+          primaryScope: ResourcePrimaryScope.APPLICATION,
+          applicationId: accessScope.applicationId,
+        };
+
+      case ResourcePrimaryScope.ORGANIZATIONS:
+        if (!accessScope.organizationId) {
+          throw this.errorBuilder.buildError(
+            ErrorType.VALIDATION,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.VALIDATION,
+              context: {
+                message: 'Organization ID is required for ORGANIZATIONS-scoped resources',
+                resourceType,
+              },
+            }
+          );
+        }
+        return {
+          primaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+          organizationId: accessScope.organizationId,
+        };
+
+      case ResourcePrimaryScope.USER_SELF:
+        if (!accessScope.organizationId || !accessScope.userId) {
+          throw this.errorBuilder.buildError(
+            ErrorType.VALIDATION,
+            executionContext,
+            {
+              customMessageReference: ErrorCustomMessageReference.VALIDATION,
+              context: {
+                message: 'Organization ID and User ID are required for USER_SELF-scoped resources',
+                resourceType,
+              },
+            }
+          );
+        }
+        return {
+          primaryScope: ResourcePrimaryScope.USER_SELF,
+          organizationId: accessScope.organizationId,
+          userId: accessScope.userId,
+        };
+
+      default:
+        throw this.errorBuilder.buildError(
+          ErrorType.CONFIGURATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+              message: 'File scope derivation only supports APPLICATION, ORGANIZATIONS, and USER_SELF resources',
+              resourceType,
+              primaryScope,
+            },
+          }
+        );
+    }
+  }
+
+  /**
+   * Extract file extension from filename.
+   *
+   * @param filename - Filename with or without extension
+   * @returns Extension without dot, or empty string if none
+   */
+  private extractExtension(filename: string): string {
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1 || lastDot === filename.length - 1) {
+      return '';
+    }
+    return filename.substring(lastDot + 1).toLowerCase();
+  }
+}