@wildo-ai/saas-backend-lib 1.0.1

package/src/files/controllers/file.controller.ts

@@ -0,0 +1,1030 @@
+/**
+ * File Controller Backend Service
+ *
+ * Handles file download, metadata retrieval, deletion, and sharing.
+ * Provides global file access endpoints independent of resource context.
+ *
+ * Routes:
+ * - GET /files/:fileId - Download file (supports ?consumable_token=... for public access)
+ * - GET /files/:fileId/metadata - Get file metadata (supports ?consumable_token=...)
+ * - DELETE /files/:fileId - Delete file (unlinked only)
+ * - POST /files/:fileId/share - Generate a shareable consumable token
+ */
+
+import { injectable, inject } from 'inversify';
+import { Request, Response, NextFunction } from 'express';
+import { Readable } from 'stream';
+import { z } from 'zod';
+import {
+  CoreConsumableTokenTypes,
+  ConsumableToken_ConsumptionMode,
+  CoreResourceOperation,
+  CoreResourceType,
+  ExecutionContext_ExecutionType,
+  ErrorType,
+  ErrorCustomMessageReference,
+  FileStatus,
+  FILE_DOWNLOADABLE_STATUSES,
+  WildoHeaderKeys,
+  isWildoBackendError,
+} from '@wildo-ai/saas-models';
+import { File } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import { FilesBackendService } from '~wildo-backend-lib/files/services/files.backend.service';
+import { FileFieldDetectionBackendService } from '~wildo-backend-lib/files/services/file-field-detection.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { ConsumableTokenBackendService } from '~wildo-backend-lib/security/consumable-tokens/services/consumable-token.backend.service';
+import { ExpiresInDurationSchema, DurationUnit, type DurationValue, type ExpiresInDuration } from '@wildo-ai/zod-decorators';
+import { resolveFileUploaderPrincipal } from '~wildo-backend-lib/files/utils/file-uploader.utils';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { validateFileId, sanitizeFilename, validateStream } from '~wildo-backend-lib/files/utils/file-validation.utils';
+import { setContentDispositionHeader } from '~wildo-backend-lib/files/utils/file-upload.utils';
+/**
+ * Zod schema for POST /files/:fileId/share request body validation.
+ * All fields are optional — defaults come from z_file({ sharableDefaults }) or hardcoded fallbacks.
+ */
+const ShareFileRequestBodySchema = z.object({
+  expiresIn: ExpiresInDurationSchema.optional(),
+  maxUses: z.number().int().min(1).optional(),
+}).strict();
+
+@injectable()
+export class FileController extends AbstractControllerBackendService {
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) logger: any,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: any,
+    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: any,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService)
+    private readonly resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)
+    private readonly executionContextCreator: ExecutionContextCreatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.FilesBackendService)
+    private readonly filesService: FilesBackendService,
+    @inject(SAAS_SERVICE_TYPES.ConsumableTokenService)
+    private readonly consumableTokenService: ConsumableTokenBackendService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)
+    private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)
+    private readonly fileFieldDetection: FileFieldDetectionBackendService,
+  ) {
+    super(logger, errorBuilder, errorHandler, 'FileController');
+  }
+
+  /**
+   * Setup file controller routes
+   */
+  protected setupRoutes(): void {
+    // Download file: GET /files/:fileId
+    this.router.get('/files/:fileId', this.asyncHandler(this.downloadFile.bind(this)));
+    this.logRouteRegistration('GET', '/files/:fileId', 'Download file');
+
+    // Get file metadata: GET /files/:fileId/metadata
+    this.router.get('/files/:fileId/metadata', this.asyncHandler(this.getFileMetadata.bind(this)));
+    this.logRouteRegistration('GET', '/files/:fileId/metadata', 'Get file metadata');
+
+    // Delete file: DELETE /files/:fileId
+    this.router.delete('/files/:fileId', this.asyncHandler(this.deleteFile.bind(this)));
+    this.logRouteRegistration('DELETE', '/files/:fileId', 'Delete file');
+
+    // Share file: POST /files/:fileId/share
+    this.router.post('/files/:fileId/share', this.asyncHandler(this.shareFile.bind(this)));
+    this.logRouteRegistration('POST', '/files/:fileId/share', 'Generate share link');
+  }
+
+  /**
+   * Get the READ operation path for FILES resource.
+   * Used to create execution contexts for file operations.
+   */
+  private getFileReadOperation() {
+    return this.resourcesRegistry.getOperationPathDefault(
+      CoreResourceType.FILES,
+      CoreResourceOperation.READ
+    );
+  }
+
+  /**
+   * Get the DELETE operation path for FILES resource.
+   */
+  private getFileDeleteOperation() {
+    return this.resourcesRegistry.getOperationPathDefault(
+      CoreResourceType.FILES,
+      CoreResourceOperation.DELETE
+    );
+  }
+
+  private buildFileNotFoundError(fileId: string, executionContext?: ExecutionContext<any>) {
+    return this.errorBuilder.buildError(
+      ErrorType.NOT_FOUND,
+      executionContext,
+      {
+        customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+        context: {
+          message: 'File not found',
+          fileId,
+        },
+      }
+    );
+  }
+
+  /**
+   * Authenticated direct file routes should not disclose whether a probed fileId
+   * exists when the caller lacks access. Collapse authorization failures into
+   * the same not-found surface used for genuinely missing files.
+   */
+  private async getReadableFileOrNotFound(
+    fileId: string,
+    executionContext: ExecutionContext<any>,
+  ): Promise<File> {
+    try {
+      const file = await this.filesService.getFile(fileId, executionContext);
+      if (!file) {
+        throw this.buildFileNotFoundError(fileId, executionContext);
+      }
+      return file;
+    } catch (error) {
+      const errorType = isWildoBackendError(error)
+        ? error.type
+        : (error instanceof Error && 'errorType' in error ? (error as Error & { errorType?: ErrorType }).errorType : undefined);
+
+      if (errorType === ErrorType.AUTHORIZATION) {
+        throw this.buildFileNotFoundError(fileId, executionContext);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Public consumable-token downloads bypass normal user authorization. Build a
+   * minimal synthetic execution context that carries only the FILES READ
+   * operation identity and a public execution type, without fabricating a user
+   * initiator.
+   */
+  private createSyntheticPublicReadExecutionContext(): ExecutionContext<any> {
+    const operationPath = this.getFileReadOperation();
+    const operation = this.resourcesRegistry.getOperationFromPath(operationPath);
+    if (!operation) {
+      throw this.errorBuilder.buildError(
+        ErrorType.INTERNAL,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.INTERNAL,
+          context: {
+            message: 'File READ operation not found for synthetic public execution context',
+          },
+        }
+      );
+    }
+
+    return new ExecutionContext(
+      operation,
+      ExecutionContext_ExecutionType.PUBLIC_EXECUTION,
+      new Map(),
+      null,
+      [],
+      [],
+    );
+  }
+
+  /**
+   * Validate a consumable token for file access (WITHOUT consuming it).
+   * Returns true if a valid token was provided, false if no token is present.
+   * Throws if token is present but invalid (expired, revoked, type mismatch, relatedId mismatch).
+   *
+   * IMPORTANT: Consumption is intentionally NOT done here. Callers must call
+   * `consumeFileTokenWithRetry()` AFTER confirming the file exists, to avoid burning
+   * SINGLE_USE tokens on 404s.
+   */
+  private async validateFileToken(
+    consumableTokenValue: string | undefined,
+    fileId: string,
+  ): Promise<boolean> {
+    if (!consumableTokenValue) {
+      return false;
+    }
+
+    // Validate the token using the dedicated service
+    // Restricts to FILE_PUBLIC_ACCESS type only
+    const tokenObject = await this.consumableTokenService.validateToken(
+      consumableTokenValue,
+      [CoreConsumableTokenTypes.FILE_PUBLIC_ACCESS],
+    );
+
+    // SECURITY: FILE_PUBLIC_ACCESS tokens MUST have a relatedId matching the requested file.
+    // Tokens without relatedId would be wildcard tokens that can access any file — reject them.
+    if (!tokenObject.relatedId || tokenObject.relatedId !== fileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.AUTHENTICATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_CONTEXT_MISMATCH,
+          context: {
+            message: tokenObject.relatedId
+              ? 'Token relatedId does not match requested fileId'
+              : 'FILE_PUBLIC_ACCESS tokens must have a relatedId bound to a specific file',
+            expectedFileId: fileId,
+          },
+        }
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Consume a file access token AFTER the file has been confirmed to exist.
+   * This prevents burning SINGLE_USE tokens on 404 responses.
+   */
+  private async consumeFileToken(consumableTokenValue: string): Promise<void> {
+    await this.consumableTokenService.consumeToken(consumableTokenValue);
+  }
+
+  /**
+   * Post-response token consumption still has to happen after a successful HTTP
+   * finish event, but we retry transient failures a few times so a short-lived
+   * Mongo hiccup does not silently leave file-access tokens reusable.
+   */
+  private async consumeFileTokenWithRetry(consumableTokenValue: string, fileId: string): Promise<void> {
+    const retryDelaysMs = [0, 100, 250, 500];
+
+    for (let attempt = 0; attempt < retryDelaysMs.length; attempt += 1) {
+      const delayMs = retryDelaysMs[attempt]!;
+
+      if (delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+
+      try {
+        await this.consumeFileToken(consumableTokenValue);
+        return;
+      } catch (error) {
+        if (attempt === retryDelaysMs.length - 1) {
+          throw error;
+        }
+
+        this.logger.warn('Retrying file token consumption after successful response', {
+          fileId,
+          attempt: attempt + 1,
+          nextRetryDelayMs: retryDelaysMs[attempt + 1],
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+
+  /**
+   * Download file endpoint.
+   * GET /files/:fileId
+   *
+   * Supports consumable token access via query parameter: ?consumable_token=...
+   */
+  private async downloadFile(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const fileId = req.params.fileId as string;
+
+    // Defense-in-depth: Check for presence before format validation
+    // Express routes should ensure params exist, but explicit check improves robustness
+    if (!fileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName: 'fileId',
+            reason: 'missing',
+            message: 'fileId parameter is required'
+          }
+        }
+      );
+    }
+
+    const consumableToken = req.query.consumable_token as string | undefined;
+
+    this.logDebug('File download requested', { fileId, hasConsumableToken: !!consumableToken });
+
+    try {
+      // Validate fileId format (CRITICAL: Prevents invalid fileId propagation and database errors)
+      // ExecutionContext will be created below, but validation can happen early with undefined context
+      validateFileId(fileId, this.errorBuilder, undefined, 'fileId');
+
+      // ── Token-based public access path ──
+      // If a consumable token is provided, validate it and serve the file directly
+      // without going through the normal execution context / authorization flow.
+      const isTokenAccess = await this.validateFileToken(consumableToken, fileId);
+
+      if (isTokenAccess) {
+        const file = await this.getFileDirectly(fileId);
+        if (!file) {
+          throw this.errorBuilder.buildError(
+            ErrorType.NOT_FOUND,
+            undefined,
+            {
+              customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+              context: { message: 'File not found', fileId },
+            }
+          );
+        }
+        if (!FILE_DOWNLOADABLE_STATUSES.has(file.status)) {
+          throw this.errorBuilder.buildError(
+            ErrorType.VALIDATION,
+            undefined,
+            {
+              customMessageReference: ErrorCustomMessageReference.VALIDATION,
+              context: { message: 'File is not available for download', fileId, status: file.status },
+            }
+          );
+        }
+        const syntheticExecutionContext = this.createSyntheticPublicReadExecutionContext();
+        this.scheduleConsumableTokenConsumptionOnSuccess(res, consumableToken!, fileId);
+        await this.streamFileFromStorage(file, res, syntheticExecutionContext, next);
+        return;
+      }
+
+      // ── Normal authenticated access path ──
+      // Create execution context for file READ operation
+      const operationPath = this.getFileReadOperation();
+      const operation = this.resourcesRegistry.getOperationFromPath(operationPath);
+      if (!operation) {
+        throw this.errorBuilder.buildError(
+          ErrorType.INTERNAL,
+          {} as ExecutionContext<any>,
+          {
+            customMessageReference: ErrorCustomMessageReference.INTERNAL,
+            context: {
+              message: 'File READ operation not found',
+            },
+          }
+        );
+      }
+
+      const executionContext = await this.executionContextCreator.createExecutionContextFromRequest(
+        req,
+        operation,
+        {
+          url: `/files/${fileId}`,
+          parameters: [],
+        }
+      );
+
+      // Authorize file access
+      const file = await this.getReadableFileOrNotFound(fileId, executionContext);
+
+      if (!FILE_DOWNLOADABLE_STATUSES.has(file.status)) {
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: {
+              message: 'File is not available for download',
+              fileId,
+              status: file.status,
+            },
+          }
+        );
+      }
+
+      // Stream file from storage
+      await this.streamFileFromStorage(file, res, executionContext, next);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  /**
+   * Stream file from storage to response.
+   * Sets appropriate headers and pipes the stream.
+   */
+  private async streamFileFromStorage(
+    file: File,
+    res: Response,
+    executionContext: ExecutionContext<any> | undefined,
+    next?: NextFunction,
+  ): Promise<void> {
+    this.logDebug('Streaming file from storage', { fileId: file.fileId });
+
+    let stream: Readable | null = null;
+
+    try {
+      const storageProvider = this.filesService.getStorageProviderForFile(file, executionContext as any);
+      const downloadResult = await storageProvider.download(file, executionContext as any);
+      stream = downloadResult.stream;
+
+      // Validate stream before use (CRITICAL: Ensures stream is readable and not destroyed)
+      validateStream(stream, this.errorBuilder, executionContext as any, 'downloadStream');
+
+      // Set response headers from storage metadata (more accurate than DB metadata)
+      // Check if headers are already sent (shouldn't happen, but safety check)
+      if (res.headersSent) {
+        this.logger.warn('Response headers already sent, cannot set file download headers', {
+          fileId: file.fileId,
+        });
+        // Still pipe the stream, but headers may be incorrect
+      } else {
+        res.setHeader(WildoHeaderKeys.CONTENT_TYPE, downloadResult.contentType || file.mimeType);
+
+        const contentLength = downloadResult.size > 0 ? downloadResult.size : (file.size || 0);
+        if (contentLength > 0) {
+          res.setHeader(WildoHeaderKeys.CONTENT_LENGTH, contentLength.toString());
+        }
+
+        // Use originalFilename from database (file object is already fetched)
+        // If originalFilename is missing, use fileId as fallback (shouldn't happen, but safe)
+        const filename = file.originalFilename || file.fileId || 'file';
+        setContentDispositionHeader(res, filename);
+
+        // Set standard HTTP caching headers if available (ETag and Last-Modified are standard HTTP headers,
+        // not platform headers, so kept as literals per standardization decisions)
+        if (downloadResult.etag) {
+          res.setHeader(WildoHeaderKeys.ETAG, downloadResult.etag);
+        }
+        if (downloadResult.lastModified) {
+          res.setHeader(WildoHeaderKeys.LAST_MODIFIED, downloadResult.lastModified.toUTCString());
+        }
+      }
+
+      // Register error handlers BEFORE piping (CRITICAL: Ensures immediate errors are caught)
+      // Handle stream errors (network errors, storage errors, etc.)
+      // Note: stream is guaranteed to be non-null here since we register the handler after assignment
+      stream.on('error', (error) => {
+        this.logger.error('Stream error while downloading file from storage', {
+          fileId: file.fileId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        // Only send error response if headers haven't been sent yet
+        if (!res.headersSent) {
+          if (next) {
+            next(error);
+            return;
+          }
+          res.status(500).end();
+        } else {
+          // If headers already sent, destroy the stream to stop sending data
+          // stream is captured in closure and guaranteed non-null (registered after assignment)
+          if (stream && !stream.destroyed) {
+            stream.destroy();
+          }
+        }
+      });
+
+      // Handle response errors (client-side errors, network issues)
+      res.on('error', (error) => {
+        this.logger.error('Response error while streaming file', {
+          fileId: file.fileId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+          // Destroy the source stream to stop reading from storage
+        if (stream && !stream.destroyed) {
+          stream.destroy();
+        }
+      });
+
+      // Handle response close (client disconnected or response finished)
+      res.on('close', () => {
+        // Clean up: destroy the source stream if it's still active
+        if (stream && !stream.destroyed) {
+          stream.destroy();
+        }
+      });
+
+      // Pipe stream to response after handlers are registered (CRITICAL: Ensures error handlers catch immediate errors)
+      stream.pipe(res);
+    } catch (error) {
+      // Clean up stream if it was created but not yet piped
+      if (stream && !stream.destroyed) {
+        try {
+          stream.destroy();
+        } catch (destroyError) {
+          this.logger.warn('Failed to destroy stream during error cleanup', {
+            fileId: file.fileId,
+            error: destroyError instanceof Error ? destroyError.message : String(destroyError),
+            originalError: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      this.logger.error('Failed to stream file from storage', {
+        fileId: file.fileId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get file metadata endpoint.
+   * GET /files/:fileId/metadata
+   *
+   * Supports consumable token access via query parameter: ?consumable_token=...
+   */
+  private async getFileMetadata(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const fileId = req.params.fileId as string;
+
+    // Defense-in-depth: Check for presence before format validation
+    // Express routes should ensure params exist, but explicit check improves robustness
+    if (!fileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName: 'fileId',
+            reason: 'missing',
+            message: 'fileId parameter is required'
+          }
+        }
+      );
+    }
+
+    const consumableToken = req.query.consumable_token as string | undefined;
+
+    this.logDebug('File metadata requested', { fileId, hasConsumableToken: !!consumableToken });
+
+    try {
+      // Validate fileId format (CRITICAL: Prevents invalid fileId propagation and database errors)
+      // ExecutionContext will be created below, but validation can happen early with undefined context
+      validateFileId(fileId, this.errorBuilder, undefined, 'fileId');
+
+      // ── Token-based public access path ──
+      const isTokenAccess = await this.validateFileToken(consumableToken, fileId);
+
+      if (isTokenAccess) {
+        const file = await this.getFileDirectly(fileId);
+        if (!file) {
+          throw this.errorBuilder.buildError(
+            ErrorType.NOT_FOUND,
+            undefined,
+            {
+              customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+              context: { message: 'File not found', fileId },
+            }
+          );
+        }
+        this.scheduleConsumableTokenConsumptionOnSuccess(res, consumableToken!, fileId);
+        const fileMetadata = this.filesService.toMetadataResponse(file);
+        this.jsonSuccess(res, fileMetadata);
+        return;
+      }
+
+      // ── Normal authenticated access path ──
+      // Create execution context for file READ operation
+      const operationPath = this.getFileReadOperation();
+      const operation = this.resourcesRegistry.getOperationFromPath(operationPath);
+      if (!operation) {
+        throw this.errorBuilder.buildError(
+          ErrorType.INTERNAL,
+          {} as ExecutionContext<any>,
+          {
+            customMessageReference: ErrorCustomMessageReference.INTERNAL,
+            context: {
+              message: 'File READ operation not found',
+            },
+          }
+        );
+      }
+
+      const executionContext = await this.executionContextCreator.createExecutionContextFromRequest(
+        req,
+        operation,
+        {
+          url: `/files/${fileId}/metadata`,
+          parameters: [],
+        }
+      );
+
+      // Authorize file access and get file
+      const file = await this.getReadableFileOrNotFound(fileId, executionContext);
+
+      // Return file metadata
+      const fileMetadata = this.filesService.toMetadataResponse(file);
+      this.jsonSuccess(res, fileMetadata);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  /**
+   * Delete file endpoint.
+   * DELETE /files/:fileId
+   *
+   * Only allows deletion of unlinked files (status: UPLOADED or ORPHANED).
+   * Rejects deletion of linked files (status: LINKED).
+   */
+  private async deleteFile(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const fileId = req.params.fileId as string;
+
+    // Defense-in-depth: Check for presence before format validation
+    // Express routes should ensure params exist, but explicit check improves robustness
+    if (!fileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName: 'fileId',
+            reason: 'missing',
+            message: 'fileId parameter is required'
+          }
+        }
+      );
+    }
+
+    this.logDebug('File deletion requested', { fileId });
+
+    try {
+      // Validate fileId format (CRITICAL: Prevents invalid fileId propagation and database errors)
+      // ExecutionContext will be created below, but validation can happen early with undefined context
+      validateFileId(fileId, this.errorBuilder, undefined, 'fileId');
+
+      // Create execution context for file DELETE operation
+      const operationPath = this.getFileDeleteOperation();
+      const operation = this.resourcesRegistry.getOperationFromPath(operationPath);
+      if (!operation) {
+        throw this.errorBuilder.buildError(
+          ErrorType.INTERNAL,
+          {} as ExecutionContext<any>,
+          {
+            customMessageReference: ErrorCustomMessageReference.INTERNAL,
+            context: {
+              message: 'File DELETE operation not found',
+            },
+          }
+        );
+      }
+
+      const executionContext = await this.executionContextCreator.createExecutionContextFromRequest(
+        req,
+        operation,
+        {
+          url: `/files/${fileId}`,
+          parameters: [],
+        }
+      );
+
+      // Read file first to verify it exists and check status. Like other
+      // authenticated direct file routes, delete should not leak whether a
+      // probed fileId exists outside the caller's accessible scope.
+      const file = await this.getReadableFileOrNotFound(fileId, executionContext);
+
+      // Check if file is already deleted
+      if (file.status === FileStatus.DELETED) {
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: {
+              message: 'File is already deleted',
+              fileId,
+              status: file.status,
+            },
+          }
+        );
+      }
+
+      if (file.status === FileStatus.SCANNING || file.status === FileStatus.EXTRACTING) {
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: {
+              message: 'Cannot delete file while processing is in progress',
+              fileId,
+              status: file.status,
+            },
+          }
+        );
+      }
+
+      // Reject deletion of linked files
+      if (file.status === FileStatus.LINKED) {
+        throw this.errorBuilder.buildError(
+          ErrorType.AUTHORIZATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+            context: {
+              message: 'Cannot delete linked file. Unlink from resource first.',
+              fileId,
+              status: file.status,
+              linkedResourceType: file.linkedResourceType,
+              linkedResourceId: file.linkedResourceId,
+            },
+          }
+        );
+      }
+
+      // Detached-file delete is owned by the recorded uploader principal.
+      // We compare only the raw id + entity type pair and leave richer display
+      // hydration to clients on demand.
+      const currentUploaderPrincipal = resolveFileUploaderPrincipal(executionContext);
+      if (
+        !currentUploaderPrincipal
+        || !file.uploadedBy
+        || !file.uploadedByEntityType
+        || file.uploadedBy !== currentUploaderPrincipal.uploadedBy
+        || file.uploadedByEntityType !== currentUploaderPrincipal.uploadedByEntityType
+      ) {
+        throw this.errorBuilder.buildError(
+          ErrorType.AUTHORIZATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+            context: {
+              message: 'Only the file uploader can delete this file',
+              fileId,
+              uploadedBy: file.uploadedBy,
+              uploadedByEntityType: file.uploadedByEntityType,
+              currentUploaderPrincipal,
+            },
+          }
+        );
+      }
+
+      // Delete file (soft delete)
+      await this.filesService.deleteFile(fileId, executionContext);
+
+      // Return success response
+      this.jsonSuccess(res, {
+        success: true,
+        message: 'File deleted successfully',
+        fileId,
+      }, 200);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  /**
+   * Share file endpoint.
+   * POST /files/:fileId/share
+   *
+   * Generates a shareable consumable token for the specified file.
+   * Requires the file's z_file field to have `sharable: true` in its schema metadata.
+   *
+   * Request body (optional):
+   * - expiresIn?: DurationValue (minutes/hours/days, value ≥ 1) — override default expiration
+   * - maxUses?: number — override default max uses (only for BOUNDED_REUSE)
+   *
+   * Returns:
+   * - { token: string, expiresAt: string, maxUses?: number }
+   */
+  private async shareFile(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const fileId = req.params.fileId as string;
+
+    if (!fileId) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.FILE_ID_VALIDATION_FAILED,
+          context: {
+            fieldName: 'fileId',
+            reason: 'missing',
+            message: 'fileId parameter is required'
+          }
+        }
+      );
+    }
+
+    this.logDebug('File share requested', { fileId });
+
+    try {
+      validateFileId(fileId, this.errorBuilder, undefined, 'fileId');
+
+      // ── Validate request body ──
+      const bodyParseResult = ShareFileRequestBodySchema.safeParse(req.body || {});
+      if (!bodyParseResult.success) {
+        throw this.errorBuilder.buildError(
+          ErrorType.VALIDATION,
+          undefined,
+          {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: {
+              message: 'Invalid share request body',
+              errors: bodyParseResult.error.issues.map(i => ({ path: i.path.join('.'), message: i.message })),
+            },
+          }
+        );
+      }
+      const requestBody = bodyParseResult.data;
+
+      // Create execution context for file READ operation (share requires at least read access)
+      const operationPath = this.getFileReadOperation();
+      const operation = this.resourcesRegistry.getOperationFromPath(operationPath);
+      if (!operation) {
+        throw this.errorBuilder.buildError(
+          ErrorType.INTERNAL,
+          {} as ExecutionContext<any>,
+          {
+            customMessageReference: ErrorCustomMessageReference.INTERNAL,
+            context: { message: 'File READ operation not found' },
+          }
+        );
+      }
+
+      const executionContext = await this.executionContextCreator.createExecutionContextFromRequest(
+        req,
+        operation,
+        {
+          url: `/files/${fileId}/share`,
+          parameters: [],
+        }
+      );
+
+      // Authorize and get the file
+      const file = await this.getReadableFileOrNotFound(fileId, executionContext);
+
+      // ── Check if the file's z_file field is declared as sharable ──
+      // The sharable flag is on the schema metadata of the z_file field that owns this file.
+      // We need to look up the resource configuration and inspect the field metadata.
+      const fileFieldMetadata = this.getFileFieldSharableMetadata(file);
+      if (!fileFieldMetadata.sharable) {
+        throw this.errorBuilder.buildError(
+          ErrorType.AUTHORIZATION,
+          executionContext,
+          {
+            customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_FILE_SHARING_DISABLED,
+            context: {
+              message: 'File sharing is not enabled for this file field',
+              fileId,
+              linkedResourceType: file.linkedResourceType,
+              linkedFieldName: file.linkedFieldName,
+            },
+          }
+        );
+      }
+
+      // ── Resolve sharing defaults from schema metadata, then override with request body ──
+      const defaults = fileFieldMetadata.sharableDefaults || {};
+
+      const expiresIn =
+        requestBody.expiresIn ?? defaults.expiresIn ?? { value: 7, unit: DurationUnit.DAYS };
+      const consumptionMode = defaults.consumptionMode === 'SINGLE_USE'
+        ? ConsumableToken_ConsumptionMode.SINGLE_USE
+        : ConsumableToken_ConsumptionMode.BOUNDED_REUSE;
+      const maxUses = consumptionMode === ConsumableToken_ConsumptionMode.BOUNDED_REUSE
+        ? (requestBody.maxUses || defaults.maxUses || 100)
+        : undefined;
+
+      // ── Generate consumable token ──
+      // NOTE: tokenType in CreateTokenParams is the token type identifier (e.g., FILE_PUBLIC_ACCESS),
+      // NOT the Wildo resource type (e.g., FILES). validateToken checks this field against expected types.
+      const result = await this.consumableTokenService.createToken({
+        tokenType: CoreConsumableTokenTypes.FILE_PUBLIC_ACCESS,
+        consumptionMode,
+        resourceIdentifier: CoreResourceType.FILES,
+        relatedId: fileId,
+        organizationId: file.organizationId,
+        expiresIn: expiresIn as DurationValue,
+        roles: [],
+        maxUses,
+        metadata: {
+          linkedResourceType: file.linkedResourceType,
+          linkedFieldName: file.linkedFieldName,
+          originalFilename: file.originalFilename,
+        },
+      });
+
+      this.jsonSuccess(res, {
+        token: result.token,
+        expiresAt: result.expiresAt.toISOString(),
+        ...(maxUses != null && { maxUses }),
+      }, 201);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  /**
+   * Consume a public access token only after the HTTP response has completed
+   * successfully. This avoids burning single-use tokens on downstream stream or
+   * response failures that happen after authorization has already succeeded.
+   */
+  private scheduleConsumableTokenConsumptionOnSuccess(
+    res: Response,
+    consumableToken: string,
+    fileId: string,
+  ): void {
+    let settled = false;
+
+    const cleanup = () => {
+      res.off('finish', onFinish);
+      res.off('close', onClose);
+      res.off('error', onError);
+    };
+
+    const onFinish = () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      cleanup();
+
+      void Promise.resolve(this.consumeFileTokenWithRetry(consumableToken, fileId)).catch((error: unknown) => {
+        this.logger.error('Failed to consume file token after successful response retries', {
+          fileId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+    };
+
+    const onClose = () => {
+      if (settled || res.writableFinished) {
+        return;
+      }
+
+      settled = true;
+      cleanup();
+    };
+
+    const onError = () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      cleanup();
+    };
+
+    res.once('finish', onFinish);
+    res.once('close', onClose);
+    res.once('error', onError);
+  }
+
+  /**
+   * Fetch a file record directly via repository, bypassing user-level authorization.
+   * Used for token-authenticated public access where the consumable token itself provides authorization.
+   *
+   * Uses an internal system execution context (INTERNALLY_INITIATED_REQUEST with APP_ADMIN_SUPER_ADMIN)
+   * to perform the read, ensuring the repository's prefix/postfix hooks have a valid context.
+   */
+  private async getFileDirectly(fileId: string): Promise<File | null> {
+    const internalContext = await this.executionContextCreator.createForInternalSystemOperation();
+    const filesRepo = this.repositoriesRegistry.getRepositoryOrThrow(
+      CoreResourceType.FILES,
+      internalContext,
+    );
+    const file = await filesRepo.read<File>(
+      internalContext,
+      { fileId },
+    );
+    return file || null;
+  }
+
+  /**
+   * Look up the z_file field metadata for a linked file to determine if sharing is enabled.
+   *
+   * Uses `getFileMetadata()` from `@wildo-ai/zod-decorators` to read the `FileSchemaMetadata`
+   * stored by `z_file({ sharable: true })`. The metadata is accessed via the resource registry
+   * → resource configuration → mainSchema → field schema.
+   *
+   * Returns `{ sharable: boolean, sharableDefaults?: ... }` based on the schema metadata
+   * of the field that owns this file. If the file is not linked or the field cannot be
+   * found, returns `{ sharable: false }`.
+   */
+  private getFileFieldSharableMetadata(file: File): {
+    sharable: boolean;
+    sharableDefaults?: { expiresIn?: ExpiresInDuration; maxUses?: number; consumptionMode?: 'SINGLE_USE' | 'BOUNDED_REUSE' };
+  } {
+    // File must be linked to a resource to have schema metadata
+    if (!file.linkedResourceType || !file.linkedFieldName) {
+      return { sharable: false };
+    }
+
+    try {
+      const detectedField = this.fileFieldDetection.getFileFieldMetadata(
+        file.linkedResourceType as any,
+        file.linkedFieldName,
+      );
+      if (!detectedField) {
+        return { sharable: false };
+      }
+
+      const fileConfig = detectedField.fileMetadata;
+      if (!fileConfig) {
+        return { sharable: false };
+      }
+
+      return {
+        sharable: !!fileConfig.sharable,
+        sharableDefaults: fileConfig.sharableDefaults,
+      };
+    } catch {
+      // If anything fails during schema lookup, sharing is not available
+      this.logDebug('Failed to look up file field sharable metadata', {
+        fileId: file.fileId,
+        linkedResourceType: file.linkedResourceType,
+        linkedFieldName: file.linkedFieldName,
+      });
+      return { sharable: false };
+    }
+  }
+}