@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/files/controllers/file.controller.js

@@ -0,0 +1,806 @@
+/**
+ * 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
+ */
+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 { 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 { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { AbstractControllerBackendService } from '../../base-classes/services/controllers/abstract-controller.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 { FilesBackendService } from '../../files/services/files.backend.service.js';
+import { FileFieldDetectionBackendService } from '../../files/services/file-field-detection.backend.service.js';
+import { ExecutionContext } from '../../runtime/models/execution-context.backend.schemas.js';
+import { ConsumableTokenBackendService } from '../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { ExpiresInDurationSchema, DurationUnit } from '@wildo-ai/zod-decorators';
+import { resolveFileUploaderPrincipal } from '../../files/utils/file-uploader.utils.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { validateFileId, validateStream } from '../../files/utils/file-validation.utils.js';
+import { setContentDispositionHeader } from '../../files/utils/file-upload.utils.js';
+/**
+ * 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();
+let FileController = class FileController extends AbstractControllerBackendService {
+    resourcesRegistry;
+    executionContextCreator;
+    filesService;
+    consumableTokenService;
+    repositoriesRegistry;
+    fileFieldDetection;
+    constructor(logger, errorBuilder, errorHandler, resourcesRegistry, executionContextCreator, filesService, consumableTokenService, repositoriesRegistry, fileFieldDetection) {
+        super(logger, errorBuilder, errorHandler, 'FileController');
+        this.resourcesRegistry = resourcesRegistry;
+        this.executionContextCreator = executionContextCreator;
+        this.filesService = filesService;
+        this.consumableTokenService = consumableTokenService;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.fileFieldDetection = fileFieldDetection;
+    }
+    /**
+     * Setup file controller routes
+     */
+    setupRoutes() {
+        // 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.
+     */
+    getFileReadOperation() {
+        return this.resourcesRegistry.getOperationPathDefault(CoreResourceType.FILES, CoreResourceOperation.READ);
+    }
+    /**
+     * Get the DELETE operation path for FILES resource.
+     */
+    getFileDeleteOperation() {
+        return this.resourcesRegistry.getOperationPathDefault(CoreResourceType.FILES, CoreResourceOperation.DELETE);
+    }
+    buildFileNotFoundError(fileId, executionContext) {
+        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.
+     */
+    async getReadableFileOrNotFound(fileId, executionContext) {
+        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.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.
+     */
+    createSyntheticPublicReadExecutionContext() {
+        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.
+     */
+    async validateFileToken(consumableTokenValue, fileId) {
+        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.
+     */
+    async consumeFileToken(consumableTokenValue) {
+        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.
+     */
+    async consumeFileTokenWithRetry(consumableTokenValue, fileId) {
+        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=...
+     */
+    async downloadFile(req, res, next) {
+        const fileId = req.params.fileId;
+        // 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;
+        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, {}, {
+                    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.
+     */
+    async streamFileFromStorage(file, res, executionContext, next) {
+        this.logDebug('Streaming file from storage', { fileId: file.fileId });
+        let stream = null;
+        try {
+            const storageProvider = this.filesService.getStorageProviderForFile(file, executionContext);
+            const downloadResult = await storageProvider.download(file, executionContext);
+            stream = downloadResult.stream;
+            // Validate stream before use (CRITICAL: Ensures stream is readable and not destroyed)
+            validateStream(stream, this.errorBuilder, executionContext, '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=...
+     */
+    async getFileMetadata(req, res, next) {
+        const fileId = req.params.fileId;
+        // 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;
+        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, {}, {
+                    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).
+     */
+    async deleteFile(req, res, next) {
+        const fileId = req.params.fileId;
+        // 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, {}, {
+                    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 }
+     */
+    async shareFile(req, res, next) {
+        const fileId = req.params.fileId;
+        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, {}, {
+                    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,
+                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.
+     */
+    scheduleConsumableTokenConsumptionOnSuccess(res, consumableToken, fileId) {
+        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) => {
+                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.
+     */
+    async getFileDirectly(fileId) {
+        const internalContext = await this.executionContextCreator.createForInternalSystemOperation();
+        const filesRepo = this.repositoriesRegistry.getRepositoryOrThrow(CoreResourceType.FILES, internalContext);
+        const file = await filesRepo.read(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 }`.
+     */
+    getFileFieldSharableMetadata(file) {
+        // 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, 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 };
+        }
+    }
+};
+FileController = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorHandlerService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.FilesBackendService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)),
+    __metadata("design:paramtypes", [Object, Object, Object, ResourcesRegistryBackendService,
+        ExecutionContextCreatorBackendService,
+        FilesBackendService,
+        ConsumableTokenBackendService,
+        RepositoriesRegistryHandlerBackendService,
+        FileFieldDetectionBackendService])
+], FileController);
+export { FileController };
+//# sourceMappingURL=file.controller.js.map