@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/files/services/files.backend.service.js

@@ -0,0 +1,987 @@
+/**
+ * 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)
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import { CoreResourceOperation, CoreResourceType, ErrorType, ErrorCustomMessageReference, ResourcePrimaryScope, Resources_SharedUtils, isWildoBackendError } from '@wildo-ai/saas-models';
+import { FileStatus, FILE_STATUS_TRANSITIONS, FileScopeUtils } from '@wildo-ai/saas-models';
+import { resolveFileDisplayNature } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
+import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service.js';
+import { ResourceOperationHelperBackendService } from '../../base-classes/services/resource-operations-helper.backend.service.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { Types } from 'mongoose';
+import { validateFileId, validateResourceId, validateResourceType, validateFieldName, validateSize, validateUploadedBy, validateUploadedByEntityType, validateOrganizationId, validateContentType, resolveConfiguredMaxFileSize } from '../../files/utils/file-validation.utils.js';
+import { resolveFileUploaderPrincipal } from '../../files/utils/file-uploader.utils.js';
+import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
+import { FileStorageRouterBackendService } from '../../files/storage/file-storage-router.backend.service.js';
+let FilesBackendService = class FilesBackendService {
+    logger;
+    errorBuilder;
+    resourcesRegistry;
+    repositoriesRegistry;
+    executionContextCreator;
+    resourceOperationHelper;
+    fileStorageRouter;
+    appConfigService;
+    logDebug;
+    constructor(logger, errorBuilder, resourcesRegistry, repositoriesRegistry, executionContextCreator, resourceOperationHelper, fileStorageRouter, appConfigService) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.resourcesRegistry = resourcesRegistry;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.executionContextCreator = executionContextCreator;
+        this.resourceOperationHelper = resourceOperationHelper;
+        this.fileStorageRouter = fileStorageRouter;
+        this.appConfigService = appConfigService;
+        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.
+     */
+    get filesRepository() {
+        return this.repositoriesRegistry.getRepositoryOrThrow(CoreResourceType.FILES, {});
+    }
+    getDefaultStorageProvider() {
+        return this.fileStorageRouter.getDefaultProvider();
+    }
+    getStorageProviderForFile(file, executionContext) {
+        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.
+     */
+    async createInternalExecutionContext(operation, providedContext) {
+        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, executionContext, options) {
+        // 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 = {
+            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(internalContext, fileRecord, 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, executionContext, options) {
+        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(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, executionContext, options) {
+        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(internalContext, {
+            fileId: { $in: validFileIds },
+            ...accessibleScopeFilter,
+        }, options);
+        // Filter by authorization
+        const authorizedFiles = [];
+        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, status, executionContext, options, storagePlacement) {
+        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(internalContext, { fileId }, {
+            status,
+            ...(storagePlacement
+                ? {
+                    storageProvider: storagePlacement.provider,
+                    storageRef: storagePlacement.storageRef,
+                }
+                : {}),
+            updatedAt: new Date(),
+        }, 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, resourceType, resourceId, fieldName, executionContext, options) {
+        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(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),
+        }, 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, executionContext, options) {
+        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 = {
+            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(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, executionContext, options) {
+        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(internalContext, { fileId }, {
+            status: FileStatus.DELETED,
+            deletedAt: new Date(),
+            updatedAt: new Date(),
+        }, 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, executionContext, options) {
+        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(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, resourceId, fieldName, executionContext, options) {
+        if (!executionContext) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, {}, {
+                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 = {
+            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(internalContext, filter, options);
+        // Filter by authorization
+        const authorizedFiles = [];
+        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, executionContext) {
+        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) {
+        // Infer nature from MIME type if not stored on the file record
+        // Uses the shared resolveFileDisplayNature() utility (single source of truth)
+        const nature = file.nature ?? 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
+     */
+    deriveAccessScope(executionContext) {
+        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.
+     */
+    buildAccessibleScopeFilter(executionContext) {
+        const accessScope = this.deriveAccessScope(executionContext);
+        const scopeBranches = [];
+        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 };
+    }
+    buildFilterForFileScope(scope) {
+        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
+     */
+    deriveScopeFromParentResource(resourceType, executionContext) {
+        // 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
+     */
+    extractExtension(filename) {
+        const lastDot = filename.lastIndexOf('.');
+        if (lastDot === -1 || lastDot === filename.length - 1) {
+            return '';
+        }
+        return filename.substring(lastDot + 1).toLowerCase();
+    }
+};
+FilesBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ResourceOperationHelperService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.FileStorageRouter)),
+    __param(7, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __metadata("design:paramtypes", [Function, ErrorBuilderBackendService,
+        ResourcesRegistryBackendService,
+        RepositoriesRegistryHandlerBackendService,
+        ExecutionContextCreatorBackendService,
+        ResourceOperationHelperBackendService,
+        FileStorageRouterBackendService,
+        AppConfigurationService])
+], FilesBackendService);
+export { FilesBackendService };
+//# sourceMappingURL=files.backend.service.js.map