@wildo-ai/saas-backend-lib 1.0.1

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

@@ -0,0 +1,885 @@
+/**
+ * Unit Tests for FilesBackendService
+ *
+ * Tests file operations:
+ * - File creation
+ * - File linking (success, idempotent, error cases)
+ * - File unlinking
+ * - File deletion
+ * - Status transitions
+ */
+
+import 'reflect-metadata';
+import { Container } from 'inversify';
+import {
+  CoreResourceOperation,
+  CoreResourceType,
+  ResourceType,
+  ErrorType,
+  ErrorSeverity,
+  ErrorCustomMessageReference,
+  ExecutionContext_ExecutionType,
+  File,
+  FileStorageAccepted,
+  FileUploaderEntityType,
+  FileStatus,
+  ResourcePrimaryScope,
+} from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { MockResourceOperationHelperBackendService } from '~wildo-backend-lib/base-classes/services/__tests__/mock-resource-operation-helper.service';
+import { FilesBackendService } from '~wildo-backend-lib/files/services/files.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import {
+  MockExecutionContextCreatorBackendService,
+  MockFileRepositoryService,
+  MockRepositoriesRegistryHandlerBackendService,
+  MockResourcesRegistryBackendService,
+} from '~wildo-backend-lib/testing';
+import { MockAppConfigurationService } from '~wildo-backend-lib/config/services/__tests__/mock-app-configuration.service';
+import { MockThrowingErrorBuilderService } from '~wildo-backend-lib/errors/services/__tests__/mock-error-builder.service';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+import { Types } from 'mongoose';
+
+// =============================================================================
+// TEST SUITE
+// =============================================================================
+
+describe('FilesBackendService', () => {
+  let container: Container;
+  let filesService: FilesBackendService;
+  let mockLogger: MockLoggerService;
+  let mockErrorBuilder: MockThrowingErrorBuilderService;
+  let mockResourcesRegistry: MockResourcesRegistryBackendService;
+  let mockRepositoriesRegistry: MockRepositoriesRegistryHandlerBackendService;
+  let mockExecutionContextCreator: MockExecutionContextCreatorBackendService;
+  let mockResourceOperationHelper: MockResourceOperationHelperBackendService;
+  let mockStorageProvider: { providerId: FileStorageAccepted; delete: ReturnType<typeof vi.fn> };
+  let mockFileStorageRouter: { getDefaultProvider: ReturnType<typeof vi.fn>; getProviderById: ReturnType<typeof vi.fn> };
+  let mockRepository: MockFileRepositoryService;
+  let mockAppConfigService: MockAppConfigurationService;
+
+  let executionContext: ExecutionContext<any>;
+  const testApplicationId = '507f1f77bcf86cd799439099';
+  const testOrganizationId = '507f1f77bcf86cd799439011';
+  const testUserId = '507f1f77bcf86cd799439012';
+  const testResourceType = 'todos' as ResourceType;
+  const testResourceId = '507f1f77bcf86cd799439013';
+  const testFieldName = 'attachments';
+
+  beforeEach(() => {
+    container = new Container();
+
+    // Create mock instances
+    mockLogger = new MockLoggerService();
+    mockErrorBuilder = new MockThrowingErrorBuilderService();
+    mockResourcesRegistry = new MockResourcesRegistryBackendService();
+    mockRepositoriesRegistry = new MockRepositoriesRegistryHandlerBackendService();
+    mockExecutionContextCreator = new MockExecutionContextCreatorBackendService();
+    mockResourceOperationHelper = new MockResourceOperationHelperBackendService();
+    mockStorageProvider = {
+      providerId: FileStorageAccepted.WILDO_MANAGED,
+      delete: vi.fn(async () => undefined),
+    };
+    mockFileStorageRouter = {
+      getDefaultProvider: vi.fn(() => mockStorageProvider),
+      getProviderById: vi.fn((providerId: string) => (
+        providerId === FileStorageAccepted.WILDO_MANAGED ? mockStorageProvider : undefined
+      )),
+    };
+    mockRepository = new MockFileRepositoryService();
+    mockAppConfigService = new MockAppConfigurationService();
+    mockRepositoriesRegistry.setRepository(CoreResourceType.FILES, mockRepository);
+
+    // Bind mocks
+    container.bind(SAAS_SERVICE_TYPES.Logger).toConstantValue(mockLogger as any);
+    container.bind(SAAS_SERVICE_TYPES.ErrorBuilderService).toConstantValue(mockErrorBuilder as any);
+    container.bind(SAAS_SERVICE_TYPES.ResourceRegistryService).toConstantValue(mockResourcesRegistry as any);
+    container.bind(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService).toConstantValue(mockRepositoriesRegistry as any);
+    container.bind(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService).toConstantValue(mockExecutionContextCreator as any);
+    container.bind(SAAS_SERVICE_TYPES.ResourceOperationHelperService).toConstantValue(mockResourceOperationHelper as any);
+    container.bind(SAAS_SERVICE_TYPES.FileStorageRouter).toConstantValue(mockFileStorageRouter as any);
+    container.bind(SAAS_SERVICE_TYPES.AppConfigService).toConstantValue(mockAppConfigService as any);
+
+    // Bind service under test
+    container.bind(SAAS_SERVICE_TYPES.FilesBackendService).to(FilesBackendService).inSingletonScope();
+
+    filesService = container.get(SAAS_SERVICE_TYPES.FilesBackendService);
+
+    // Create test execution context
+    executionContext = {
+      operation: {
+        resourceType: CoreResourceType.FILES,
+        operation: CoreResourceOperation.CREATE,
+      } as any,
+      contextResourcesFieldIdentifier: new Map(),
+      initiatorIds: {
+        applicationId: testApplicationId,
+        organizationId: testOrganizationId,
+        userId: testUserId,
+      },
+      initiatorRoles: [],
+      applicationId: testApplicationId,
+      organizationId: testOrganizationId,
+      requestUUID: 'test-request-uuid',
+      executionType: ExecutionContext_ExecutionType.USER_REQUEST,
+    };
+
+    // Reset mocks
+    mockRepository.clear();
+    vi.clearAllMocks();
+  });
+
+  // =============================================================================
+  // File Creation
+  // =============================================================================
+
+  describe('createFile', () => {
+    it('should create a file record with PENDING status', async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+        uploadedBy: testUserId,
+        uploadedByEntityType: FileUploaderEntityType.USER,
+      };
+
+      const file = await filesService.createFile(fileData, executionContext);
+
+      expect(file).toBeDefined();
+      expect(file.fileId).toBeDefined();
+      expect(file.status).toBe(FileStatus.PENDING);
+      expect(file.filename).toBe(fileData.filename);
+      expect(file.originalFilename).toBe(fileData.originalFilename);
+      expect(file.mimeType).toBe(fileData.mimeType);
+      expect(file.size).toBe(fileData.size);
+      expect(file.organizationId).toBe(testOrganizationId);
+      expect(file.uploadedBy).toBe(testUserId);
+      expect(file.uploadedByEntityType).toBe(FileUploaderEntityType.USER);
+      expect(file.storageProvider).toBe(FileStorageAccepted.WILDO_MANAGED);
+      expect(mockRepository.create).toHaveBeenCalled();
+    });
+
+    it('should derive user uploader ownership from execution context if not provided', async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+
+      const file = await filesService.createFile(fileData, executionContext);
+
+      expect(file.uploadedBy).toBe(testUserId);
+      expect(file.uploadedByEntityType).toBe(FileUploaderEntityType.USER);
+    });
+
+    it('should derive application api key uploader ownership from execution context', async () => {
+      const apiKeyExecutionContext = {
+        ...executionContext,
+        initiatorIds: {
+          applicationId: testApplicationId,
+          applicationApiKeyId: '507f1f77bcf86cd7994390aa',
+        },
+        executionType: ExecutionContext_ExecutionType.APP_API_KEY,
+      } as ExecutionContext<any>;
+
+      const file = await filesService.createFile({
+        filename: 'api-key-file.txt',
+        originalFilename: 'api-key-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      }, apiKeyExecutionContext);
+
+      expect(file.uploadedBy).toBe('507f1f77bcf86cd7994390aa');
+      expect(file.uploadedByEntityType).toBe(FileUploaderEntityType.APPLICATION_API_KEY);
+    });
+
+    it('should derive anonymous uploader ownership from execution context', async () => {
+      const anonymousExecutionContext = {
+        ...executionContext,
+        initiatorIds: {
+          applicationId: testApplicationId,
+          anonymousUserId: '507f1f77bcf86cd7994390bb',
+        },
+        executionType: ExecutionContext_ExecutionType.ANONYMOUS_SESSION,
+      } as ExecutionContext<any>;
+
+      const file = await filesService.createFile({
+        filename: 'anon-file.txt',
+        originalFilename: 'anon-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+      }, anonymousExecutionContext);
+
+      expect(file.uploadedBy).toBe('507f1f77bcf86cd7994390bb');
+      expect(file.uploadedByEntityType).toBe(FileUploaderEntityType.ANONYMOUS_USER);
+    });
+
+    it('should derive organization api key uploader ownership from execution context', async () => {
+      const orgApiKeyExecutionContext = {
+        ...executionContext,
+        initiatorIds: {
+          organizationId: testOrganizationId,
+          organizationApiKeyId: '507f1f77bcf86cd7994390cc',
+        },
+        executionType: ExecutionContext_ExecutionType.ORG_API_KEY,
+      } as ExecutionContext<any>;
+
+      const file = await filesService.createFile({
+        filename: 'org-api-key-file.txt',
+        originalFilename: 'org-api-key-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      }, orgApiKeyExecutionContext);
+
+      expect(file.uploadedBy).toBe('507f1f77bcf86cd7994390cc');
+      expect(file.uploadedByEntityType).toBe(FileUploaderEntityType.ORGANIZATION_API_KEY);
+    });
+
+    it('should reject partial uploader ownership input', async () => {
+      await expect(filesService.createFile({
+        filename: 'broken.txt',
+        originalFilename: 'broken.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        uploadedByEntityType: FileUploaderEntityType.USER,
+      }, executionContext)).rejects.toThrow('uploadedBy and uploadedByEntityType must either both be set or both be omitted');
+    });
+
+    it('should reject explicit uploader ownership that does not match the execution principal', async () => {
+      await expect(filesService.createFile({
+        filename: 'spoofed.txt',
+        originalFilename: 'spoofed.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        uploadedBy: '507f1f77bcf86cd7994390aa',
+        uploadedByEntityType: FileUploaderEntityType.APPLICATION_API_KEY,
+      }, executionContext)).rejects.toThrow('Explicit uploader ownership must match the current execution principal');
+    });
+
+    it('should honor the configured max file size instead of the default ceiling', async () => {
+      mockAppConfigService.config.storage.maxFileSize = 10;
+
+      await expect(filesService.createFile({
+        filename: 'too-large.txt',
+        originalFilename: 'too-large.txt',
+        mimeType: 'text/plain',
+        size: 11,
+      }, executionContext)).rejects.toThrow('size exceeds maximum file size of 10 bytes');
+    });
+
+    it('should extract extension from filename', async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+
+      const file = await filesService.createFile(fileData, executionContext);
+
+      expect(file.extension).toBe('txt');
+    });
+
+    it('prefers originalFilename in metadata responses to avoid leaking temp upload names', () => {
+      const metadata = filesService.toMetadataResponse({
+        fileId: 'file-1',
+        filename: 'upload_9a3f0.tmp',
+        originalFilename: 'invoice.pdf',
+        mimeType: 'application/pdf',
+        size: 2048,
+        status: FileStatus.UPLOADED,
+        uploadedAt: new Date('2026-04-01T12:00:00.000Z'),
+      } as never);
+
+      expect(metadata.filename).toBe('invoice.pdf');
+    });
+
+    it('should throw error for invalid file size', async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 200 * 1024 * 1024, // 200MB, exceeds default 100MB limit
+        organizationId: testOrganizationId,
+      };
+
+      await expect(filesService.createFile(fileData, executionContext)).rejects.toThrow();
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+
+    it('should persist application-scoped files with application storage paths', async () => {
+      const file = await filesService.createFile({
+        filename: 'brand.png',
+        originalFilename: 'brand.png',
+        mimeType: 'image/png',
+        size: 1024,
+        scope: {
+          primaryScope: ResourcePrimaryScope.APPLICATION,
+          applicationId: testApplicationId,
+        },
+      }, executionContext);
+
+      expect(file.primaryScope).toBe(ResourcePrimaryScope.APPLICATION);
+      expect(file.applicationId).toBe(testApplicationId);
+      expect(file.organizationId).toBeUndefined();
+      expect(file.storageKey).toBe(`app/${testApplicationId}/${file.fileId}`);
+    });
+  });
+
+  // =============================================================================
+  // File Linking
+  // =============================================================================
+
+  describe('linkFileToResource', () => {
+    let uploadedFile: File;
+
+    beforeEach(async () => {
+      // Create an uploaded file for linking tests
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+      uploadedFile = await filesService.createFile(fileData, executionContext);
+      // Update status to UPLOADED
+      uploadedFile.status = FileStatus.UPLOADED;
+      mockRepository.getStorage().set(uploadedFile.fileId, uploadedFile);
+    });
+
+    it('should link file to resource successfully', async () => {
+      const linkedFile = await filesService.linkFileToResource(
+        uploadedFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext
+      );
+
+      expect(linkedFile.status).toBe(FileStatus.LINKED);
+      expect(linkedFile.linkedResourceType).toBe(testResourceType);
+      expect(linkedFile.linkedResourceId).toBe(testResourceId);
+      expect(linkedFile.linkedFieldName).toBe(testFieldName);
+      expect(mockRepository.update).toHaveBeenCalled();
+    });
+
+    it('should return existing file if already linked to same resource (idempotent)', async () => {
+      // Link file first time
+      const firstLink = await filesService.linkFileToResource(
+        uploadedFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext
+      );
+
+      // Link again (should be idempotent)
+      const secondLink = await filesService.linkFileToResource(
+        uploadedFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext
+      );
+
+      expect(secondLink.fileId).toBe(firstLink.fileId);
+      expect(secondLink.status).toBe(FileStatus.LINKED);
+    });
+
+    it('should throw error if file is not in UPLOADED status', async () => {
+      // File is still PENDING
+      uploadedFile.status = FileStatus.PENDING;
+      mockRepository.getStorage().set(uploadedFile.fileId, uploadedFile);
+
+      await expect(
+        filesService.linkFileToResource(
+          uploadedFile.fileId,
+          testResourceType,
+          testResourceId,
+          testFieldName,
+          executionContext
+        )
+      ).rejects.toThrow();
+
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+
+    it('should throw error if file is already linked to different resource', async () => {
+      // Link to first resource
+      await filesService.linkFileToResource(
+        uploadedFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext
+      );
+
+      // Try to link to different resource
+      const differentResourceId = '507f1f77bcf86cd799439014';
+      await expect(
+        filesService.linkFileToResource(
+          uploadedFile.fileId,
+          testResourceType,
+          differentResourceId,
+          testFieldName,
+          executionContext
+        )
+      ).rejects.toThrow();
+
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+
+    it('should derive application scope from application-scoped parents', async () => {
+      mockResourcesRegistry.setResourceScope(testResourceType, ResourcePrimaryScope.APPLICATION);
+
+      const linkedFile = await filesService.linkFileToResource(
+        uploadedFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext,
+      );
+
+      expect(linkedFile.primaryScope).toBe(ResourcePrimaryScope.APPLICATION);
+      expect(linkedFile.applicationId).toBe(testApplicationId);
+      expect(linkedFile.organizationId).toBeUndefined();
+      expect(linkedFile.storageKey).toBe(`app/${testApplicationId}/${uploadedFile.fileId}`);
+    });
+
+    it('fails closed when the parent resource uses ANONYMOUS primary scope', async () => {
+      mockResourcesRegistry.setResourceScope(testResourceType, ResourcePrimaryScope.ANONYMOUS);
+
+      await expect(
+        filesService.linkFileToResource(
+          uploadedFile.fileId,
+          testResourceType,
+          testResourceId,
+          testFieldName,
+          executionContext,
+        )
+      ).rejects.toThrow('File scope derivation only supports APPLICATION, ORGANIZATIONS, and USER_SELF resources');
+    });
+
+  });
+
+  describe('application scope access', () => {
+    it('authorizes application-scoped files only inside the same application', async () => {
+      const file: File = {
+        fileId: new Types.ObjectId().toString(),
+        filename: 'brand.png',
+        originalFilename: 'brand.png',
+        mimeType: 'image/png',
+        size: 128,
+        storageKey: 'app/test/file',
+        status: FileStatus.UPLOADED,
+        primaryScope: ResourcePrimaryScope.APPLICATION,
+        applicationId: testApplicationId,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      await expect(filesService.authorizeFileAccess(file, executionContext)).resolves.toBe(true);
+      await expect(filesService.authorizeFileAccess(file, {
+        ...executionContext,
+        applicationId: '507f1f77bcf86cd799439088',
+        initiatorIds: {
+          ...(executionContext.initiatorIds as any),
+          applicationId: '507f1f77bcf86cd799439088',
+        },
+      } as ExecutionContext<any>)).resolves.toBe(false);
+    });
+
+    it('lists linked application-scoped files without requiring an organizationId', async () => {
+      mockResourcesRegistry.setResourceScope(testResourceType, ResourcePrimaryScope.APPLICATION);
+
+      const file: File = {
+        fileId: new Types.ObjectId().toString(),
+        filename: 'brand.png',
+        originalFilename: 'brand.png',
+        mimeType: 'image/png',
+        size: 128,
+        storageKey: 'app/test/file',
+        status: FileStatus.LINKED,
+        primaryScope: ResourcePrimaryScope.APPLICATION,
+        applicationId: testApplicationId,
+        linkedResourceType: testResourceType,
+        linkedResourceId: testResourceId,
+        linkedFieldName: testFieldName,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+      mockRepository.getStorage().set(file.fileId, file);
+
+      const appOnlyContext = {
+        ...executionContext,
+        organizationId: undefined,
+        initiatorIds: {
+          applicationId: testApplicationId,
+        },
+      } as ExecutionContext<any>;
+
+      const files = await filesService.listFilesForResource(
+        testResourceType,
+        testResourceId,
+        undefined,
+        appOnlyContext,
+      );
+
+      expect(files).toHaveLength(1);
+      expect(files[0]?.fileId).toBe(file.fileId);
+    });
+
+    it('batch fetches application-scoped files with an app-only execution context', async () => {
+      const applicationFile: File = {
+        fileId: new Types.ObjectId().toString(),
+        filename: 'brand.png',
+        originalFilename: 'brand.png',
+        mimeType: 'image/png',
+        size: 128,
+        storageKey: 'app/test/file',
+        status: FileStatus.UPLOADED,
+        primaryScope: ResourcePrimaryScope.APPLICATION,
+        applicationId: testApplicationId,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+      const foreignApplicationFile: File = {
+        ...applicationFile,
+        fileId: new Types.ObjectId().toString(),
+        applicationId: '507f1f77bcf86cd799439077',
+      };
+      const unrequestedSameScopeFile: File = {
+        ...applicationFile,
+        fileId: new Types.ObjectId().toString(),
+      };
+      mockRepository.getStorage().set(applicationFile.fileId, applicationFile);
+      mockRepository.getStorage().set(foreignApplicationFile.fileId, foreignApplicationFile);
+      mockRepository.getStorage().set(unrequestedSameScopeFile.fileId, unrequestedSameScopeFile);
+
+      const files = await filesService.batchGetFiles(
+        [applicationFile.fileId, foreignApplicationFile.fileId],
+        {
+          ...executionContext,
+          organizationId: undefined,
+          initiatorIds: {
+            applicationId: testApplicationId,
+          },
+          applicationId: testApplicationId,
+        } as ExecutionContext<any>,
+      );
+
+      expect(files.map(file => file.fileId)).toEqual([applicationFile.fileId]);
+    });
+
+    it('batch fetches UUID-backed file ids without dropping them during prefiltering', async () => {
+      const uuidFile: File = {
+        fileId: '550e8400-e29b-41d4-a716-446655440000',
+        filename: 'uuid-file.txt',
+        originalFilename: 'uuid-file.txt',
+        mimeType: 'text/plain',
+        size: 64,
+        storageKey: 'org/test/uuid-file',
+        status: FileStatus.UPLOADED,
+        primaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+        organizationId: testOrganizationId,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+      mockRepository.getStorage().set(uuidFile.fileId, uuidFile);
+
+      const files = await filesService.batchGetFiles(
+        [uuidFile.fileId],
+        executionContext,
+      );
+
+      expect(files.map(file => file.fileId)).toEqual([uuidFile.fileId]);
+    });
+
+    it('returns malformed linked rows when link metadata exists but status drifted from LINKED', async () => {
+      const malformedLinkedUploadedFile: File = {
+        fileId: new Types.ObjectId().toString(),
+        filename: 'attachment.txt',
+        originalFilename: 'attachment.txt',
+        mimeType: 'text/plain',
+        size: 64,
+        storageKey: 'org/test/attachment',
+        status: FileStatus.UPLOADED,
+        primaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+        organizationId: testOrganizationId,
+        linkedResourceType: testResourceType,
+        linkedResourceId: testResourceId,
+        linkedFieldName: testFieldName,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+      mockRepository.getStorage().set(malformedLinkedUploadedFile.fileId, malformedLinkedUploadedFile);
+
+      const files = await filesService.listFilesForResource(
+        testResourceType,
+        testResourceId,
+        undefined,
+        executionContext,
+      );
+
+      expect(files.map(file => file.fileId)).toEqual([malformedLinkedUploadedFile.fileId]);
+    });
+
+    it('fails closed for legacy scope-less files when organization ownership is missing', async () => {
+      const legacyFileWithoutOrg: File = {
+        fileId: new Types.ObjectId().toString(),
+        filename: 'legacy.txt',
+        originalFilename: 'legacy.txt',
+        mimeType: 'text/plain',
+        size: 64,
+        storageKey: 'legacy/file',
+        status: FileStatus.UPLOADED,
+        uploadedAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      await expect(
+        filesService.authorizeFileAccess(
+          legacyFileWithoutOrg,
+          {
+            ...executionContext,
+            organizationId: undefined,
+            initiatorIds: {
+              applicationId: testApplicationId,
+            },
+          } as ExecutionContext<any>,
+        ),
+      ).resolves.toBe(false);
+    });
+  });
+
+  // =============================================================================
+  // File Unlinking
+  // =============================================================================
+
+  describe('unlinkFileFromResource', () => {
+    let linkedFile: File;
+
+    beforeEach(async () => {
+      // Create and link a file
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+      const createdFile = await filesService.createFile(fileData, executionContext);
+      createdFile.status = FileStatus.UPLOADED;
+      mockRepository.getStorage().set(createdFile.fileId, createdFile);
+
+      linkedFile = await filesService.linkFileToResource(
+        createdFile.fileId,
+        testResourceType,
+        testResourceId,
+        testFieldName,
+        executionContext
+      );
+    });
+
+    it('should unlink file from resource and set status to ORPHANED', async () => {
+      const unlinkedFile = await filesService.unlinkFileFromResource(
+        linkedFile.fileId,
+        executionContext
+      );
+
+      expect(unlinkedFile.status).toBe(FileStatus.ORPHANED);
+      expect(mockRepository.update).toHaveBeenCalled();
+    });
+
+    it('does not return orphaned files when listing files for the resource', async () => {
+      await filesService.unlinkFileFromResource(
+        linkedFile.fileId,
+        executionContext
+      );
+
+      const files = await filesService.listFilesForResource(
+        testResourceType,
+        testResourceId,
+        undefined,
+        executionContext
+      );
+
+      expect(files).toHaveLength(0);
+    });
+
+    it('should throw error if file not found', async () => {
+      const nonExistentFileId = '507f1f77bcf86cd799439999';
+
+      await expect(
+        filesService.unlinkFileFromResource(nonExistentFileId, executionContext)
+      ).rejects.toThrow();
+
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+
+  });
+
+  // =============================================================================
+  // File Deletion
+  // =============================================================================
+
+  describe('deleteFile', () => {
+    let fileToDelete: File;
+
+    beforeEach(async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+      fileToDelete = await filesService.createFile(fileData, executionContext);
+    });
+
+    it('should soft delete file and set status to DELETED', async () => {
+      const deletedFile = await filesService.deleteFile(
+        fileToDelete.fileId,
+        executionContext
+      );
+
+      expect(deletedFile.status).toBe(FileStatus.DELETED);
+      expect(deletedFile.deletedAt).toBeDefined();
+      expect(mockRepository.update).toHaveBeenCalled();
+    });
+
+    it('should throw error if file not found', async () => {
+      const nonExistentFileId = '507f1f77bcf86cd799439999';
+
+      await expect(
+        filesService.deleteFile(nonExistentFileId, executionContext)
+      ).rejects.toThrow();
+
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+
+  });
+
+  describe('hardDeleteFile', () => {
+    let fileToDelete: File;
+
+    beforeEach(async () => {
+      fileToDelete = await filesService.createFile({
+        filename: 'to-purge.txt',
+        originalFilename: 'to-purge.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      }, executionContext);
+    });
+
+    it('deletes storage before removing metadata', async () => {
+      const deletedFile = await filesService.hardDeleteFile(
+        fileToDelete.fileId,
+        executionContext
+      );
+
+      expect(deletedFile.fileId).toBe(fileToDelete.fileId);
+      expect(mockStorageProvider.delete).toHaveBeenCalledWith(
+        expect.objectContaining({
+          fileId: fileToDelete.fileId,
+          storageProvider: FileStorageAccepted.WILDO_MANAGED,
+        }),
+        executionContext
+      );
+      expect(mockRepository.delete).toHaveBeenCalled();
+      expect(mockRepository.getStorage().has(fileToDelete.fileId)).toBe(false);
+    });
+
+    it('fails before metadata deletion when storage cleanup fails', async () => {
+      mockStorageProvider.delete.mockRejectedValueOnce(new Error('storage delete failed'));
+
+      await expect(
+        filesService.hardDeleteFile(fileToDelete.fileId, executionContext)
+      ).rejects.toThrow('storage delete failed');
+
+      expect(mockRepository.delete).not.toHaveBeenCalled();
+      expect(mockRepository.getStorage().has(fileToDelete.fileId)).toBe(true);
+    });
+
+    it('continues metadata deletion when the blob is already missing', async () => {
+      mockStorageProvider.delete.mockRejectedValueOnce({
+        type: ErrorType.NOT_FOUND,
+        statusCode: 404,
+        severity: ErrorSeverity.MEDIUM,
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+      });
+
+      const deletedFile = await filesService.hardDeleteFile(
+        fileToDelete.fileId,
+        executionContext
+      );
+
+      expect(deletedFile.fileId).toBe(fileToDelete.fileId);
+      expect(mockRepository.delete).toHaveBeenCalled();
+      expect(mockRepository.getStorage().has(fileToDelete.fileId)).toBe(false);
+    });
+  });
+
+  // =============================================================================
+  // Status Transitions
+  // =============================================================================
+
+  describe('updateFileStatus', () => {
+    let file: File;
+
+    beforeEach(async () => {
+      const fileData = {
+        filename: 'test-file.txt',
+        originalFilename: 'test-file.txt',
+        mimeType: 'text/plain',
+        size: 1024,
+        organizationId: testOrganizationId,
+      };
+      file = await filesService.createFile(fileData, executionContext);
+    });
+
+    it('should update file status from PENDING to UPLOADED', async () => {
+      const updatedFile = await filesService.updateFileStatus(
+        file.fileId,
+        FileStatus.UPLOADED,
+        executionContext
+      );
+
+      expect(updatedFile.status).toBe(FileStatus.UPLOADED);
+      expect(mockRepository.update).toHaveBeenCalled();
+    });
+
+    it('should update file status from UPLOADED to LINKED', async () => {
+      // First update to UPLOADED
+      file.status = FileStatus.UPLOADED;
+      mockRepository.getStorage().set(file.fileId, file);
+
+      const updatedFile = await filesService.updateFileStatus(
+        file.fileId,
+        FileStatus.LINKED,
+        executionContext
+      );
+
+      expect(updatedFile.status).toBe(FileStatus.LINKED);
+    });
+
+    it('should throw error if file not found', async () => {
+      const nonExistentFileId = '507f1f77bcf86cd799439999';
+
+      await expect(
+        filesService.updateFileStatus(nonExistentFileId, FileStatus.UPLOADED, executionContext)
+      ).rejects.toThrow();
+
+      expect(mockErrorBuilder.buildError).toHaveBeenCalled();
+    });
+  });
+});