@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

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

@@ -25,7 +25,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { injectable, inject, optional } from 'inversify';
 import { CoreResourceOperation, CoreResourceType, ErrorType, ErrorCustomMessageReference, ResourcePrimaryScope, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, CORE_APP_ROLES, Resources_SharedUtils, isOrganizationWideRoleInfo, isWildoBackendError, WildoHeaderKeys } from '@wildo-ai/saas-models';
-import { FileStatus, FILE_STATUS_TRANSITIONS, FILE_LINKABLE_STATUSES, FileScopeUtils, FileServeVariant, ERASED_FILE_NAME_PLACEHOLDER } from '@wildo-ai/saas-models';
+import { FileStatus, FILE_STATUS_TRANSITIONS, FILE_LINKABLE_STATUSES, FILE_DOWNLOADABLE_STATUSES, FileScopeUtils, FileServeVariant, ERASED_FILE_NAME_PLACEHOLDER } from '@wildo-ai/saas-models';
 import { resolveFileDisplayNature } from '@wildo-ai/zod-decorators';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
@@ -38,6 +38,7 @@ import { validateFileId, validateResourceId, validateResourceType, validateField
 import { setContentDispositionHeader } from '../../files/utils/file-upload.utils.js';
 import { resolveFileUploaderPrincipal } from '../../files/utils/file-uploader.utils.js';
 import { generateImageThumbnail, collectStreamToBuffer, isThumbnailableImage, THUMBNAIL_SOURCE_MAX_BYTES } from '../../files/utils/image-thumbnail.backend.utils.js';
+import { getFileFieldSchemaMetadataByPath } from '../../files/utils/file-field-schema-path.backend.utils.js';
 import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
 import { FileStorageRouterBackendService } from '../../files/storage/file-storage-router.backend.service.js';
 import { ResourcePersistenceUnitOfWorkBackendService } from '../../databases/services/resource-persistence-unit-of-work.backend.service.js';
@@ -174,10 +175,33 @@ let FilesBackendService = class FilesBackendService {
         const next = options?.next;
         const variant = options?.variant ?? FileServeVariant.ORIGINAL;
         // ── THUMBNAIL VARIANT — a preview surface asked for a downscaled rendition.
-        // Only raster images within the memory-safe size ceiling are transformed; every
-        // other case (non-image, oversized, or a resize failure inside
-        // `serveImageThumbnail`) serves the ORIGINAL bytes via the streaming path below.
-        // Gated on the RECORDED `mimeType`/`size` so the decision costs no storage round-trip.
+        //
+        // TWO refusals, and they are deliberately NOT the same shape (#478):
+        //
+        //  1. The field SUPPRESSED derived renditions (`imageConstraints.generateThumbnails: false`).
+        //     This is a declared intent — cost, or privacy on a sensitive image — so it REFUSES.
+        //     Falling through to the original bytes, which is what every other ineligible case does,
+        //     would serve the FULL-SIZE image to a caller who asked for a small one: the exact
+        //     outcome an author suppressing thumbnails is trying to prevent. A control that degrades
+        //     into serving more data than was asked for is worse than no control.
+        //
+        //  2. The file cannot be thumbnailed (non-image, zero-size, oversized, or a resize failure
+        //     inside `serveImageThumbnail`). Nothing was declared about it, so the original bytes are
+        //     the honest answer and a preview request never hard-fails.
+        //
+        // Both gates read RECORDED state — the field's declared metadata and the file's own
+        // `mimeType`/`size` — so neither costs a storage round-trip.
+        if (variant === FileServeVariant.THUMBNAIL && !this.fieldPermitsDerivedRenditions(file)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    message: 'This file field suppresses derived renditions; request the original variant instead.',
+                    fileId: file.fileId,
+                    linkedResourceType: file.linkedResourceType,
+                    linkedFieldName: file.linkedFieldName,
+                },
+            });
+        }
         const canThumbnail = variant === FileServeVariant.THUMBNAIL &&
             isThumbnailableImage(file.mimeType) &&
             (file.size ?? 0) > 0 &&
@@ -290,6 +314,56 @@ let FilesBackendService = class FilesBackendService {
             throw error;
         }
     }
+    /**
+     * Does the DECLARING field permit derived renditions of this file?
+     *
+     * Reads `imageConstraints.generateThumbnails` off the file field's own schema metadata,
+     * resolved from the file's recorded `linkedResourceType` + `linkedFieldName`. Until #478 the
+     * flag was declared, set on the framework's own user-avatar field, and read by nothing — every
+     * eligible raster image got a rendition whether or not its author had asked for one, and an
+     * author who set it `false` for cost or privacy got thumbnails and no error. It degraded in the
+     * PERMISSIVE direction, which is why it was worth wiring rather than deleting.
+     *
+     * ## Absence means PERMIT, at three different levels, and each is deliberate
+     *
+     * A file with no `linkedResourceType`/`linkedFieldName` (a standalone upload), a field the
+     * registry cannot resolve, a field with no `imageConstraints`, or `imageConstraints` with no
+     * `generateThumbnails` — all permit. Only an EXPLICIT `false` suppresses. The flag is opt-OUT:
+     * nobody has declared it today except to say `true`, and a resolution failure must not become a
+     * silent refusal on a preview surface that works now.
+     *
+     * The `{ sizes: [...] }` form counts as permission. Its sizes are not honoured — the derivation
+     * has one fixed longest-edge — so it is truthy-permits here and nothing more; an author reading
+     * this should not expect their sizes to reach the renderer.
+     */
+    fieldPermitsDerivedRenditions(file) {
+        const resourceType = file.linkedResourceType;
+        const fieldName = file.linkedFieldName;
+        if (!resourceType || !fieldName) {
+            return true;
+        }
+        const resourceConfig = this.resourcesRegistry.getResourceConfiguration(resourceType);
+        if (!resourceConfig?.mainSchema) {
+            return true;
+        }
+        let resolved;
+        try {
+            resolved = getFileFieldSchemaMetadataByPath(resourceConfig.mainSchema, fieldName);
+        }
+        catch (error) {
+            // The walker throws on schema shapes it refuses to descend (plain unions, dynamic
+            // containers). That is a question about the SCHEMA, not about this file's permission —
+            // serving a preview is the safe answer, and the walker's own consumers report the shape.
+            this.logDebug('Could not resolve file field metadata for the rendition gate; permitting', {
+                fileId: file.fileId,
+                resourceType,
+                fieldName,
+                ...projectCaughtErrorLogFields(error),
+            });
+            return true;
+        }
+        return resolved?.fileMetadata.imageConstraints?.generateThumbnails !== false;
+    }
     /**
      * Serve a downscaled `webp` thumbnail of a raster image — the `?variant=thumbnail`
      * path of {@link streamFileToResponse}.
@@ -703,6 +777,102 @@ let FilesBackendService = class FilesBackendService {
         this.logDebug('Batch get completed', { requested: fileIds.length, found: files.length, authorized: authorizedFiles.length });
         return authorizedFiles;
     }
+    /**
+     * Read a file's BYTES for a system-initiated outbound send — today, an email attachment (#429).
+     *
+     * ## Why this lives here and not in the caller
+     *
+     * Everything it has to get right is file knowledge: which statuses may be served, how a file is
+     * authorized against a scope, and which storage provider holds the bytes. A caller that assembled
+     * those itself would be a second, drifting copy of three decisions this service owns — and the
+     * one most dangerous to copy is the status gate, because getting it wrong means attaching an
+     * INFECTED file to an outbound email.
+     *
+     * ## It REFUSES rather than skipping, and that is the whole point
+     *
+     * The defect this closes is a SILENT drop: `attachmentFileIds` was declared and read by nothing,
+     * so a caller supplying an attachment got a successful send and an attachment-less email. A
+     * resolution that quietly omitted a file it could not serve would be the same defect wearing
+     * error handling, so every rejection throws and names the file.
+     *
+     * ## Authorization: the `authoritativeScopeOverride` this reuses was built for exactly this shape
+     *
+     * A system send carries no user principal, and an identity-less execution context derives no
+     * owner — `authorizeFileAccess` records that trap in its own JSDoc, where an empty context would
+     * have denied the subject's own file during erasure teardown. So the caller's scope is passed
+     * explicitly, the same way the teardown path passes the owner it already resolved. The scope is
+     * NOT optional: without it there is no tenancy confinement, and an attachment path that reads any
+     * file by id is a read-anything primitive wearing an email envelope.
+     *
+     * @param fileIds - The file ids to resolve, in the order the caller supplied them.
+     * @param scope - The AUTHORITATIVE owner every file is authorized against. An organization-scoped
+     *   send passes its `organizationId`; an application-scoped one passes `applicationId` only, and
+     *   then only application-scoped files resolve.
+     * @returns One entry per requested id, in the requested order, carrying the bytes.
+     * @throws When a file is unknown, is in a status that is not servable, is outside the scope, or
+     *   cannot be read from its storage provider.
+     */
+    async readFilesForOutboundAttachment(fileIds, scope) {
+        if (fileIds.length === 0) {
+            return [];
+        }
+        const applicationId = scope.applicationId ?? this.appConfigService.applicationId ?? undefined;
+        const executionContext = await this.executionContextCreator.createForInternalRepositoryOperation({
+            resourceType: CoreResourceType.FILES,
+            operationIdentifier: CoreResourceOperation.READ,
+            initiatorIds: {
+                ...(applicationId ? { applicationId } : {}),
+                ...(scope.organizationId ? { organizationId: scope.organizationId } : {}),
+                ...(scope.userId ? { userId: scope.userId } : {}),
+            },
+            initiatorRoles: [
+                {
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
+                },
+            ],
+        });
+        const files = await this.filesRepository.list(executionContext, { _id: { $in: [...fileIds] } });
+        const filesById = new Map(files.map((file) => [file.fileId, file]));
+        const resolved = [];
+        for (const fileId of fileIds) {
+            const file = filesById.get(fileId);
+            if (!file) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: { message: 'Attachment file not found', fileId },
+                });
+            }
+            // The SAME authority the download route uses. INFECTED, SCANNING, PENDING, FAILED and
+            // DELETED are all outside it, so none of them can leave the system as an attachment.
+            if (!FILE_DOWNLOADABLE_STATUSES.has(file.status)) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: { message: 'Attachment file is not in a servable status', fileId, status: file.status },
+                });
+            }
+            const authorized = await this.authorizeFileAccess(file, executionContext, scope);
+            if (!authorized) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+                    context: { message: 'Attachment file is outside the sending scope', fileId },
+                });
+            }
+            const provider = this.getStorageProviderForFile(file, executionContext);
+            const download = await provider.download({ fileId: file.fileId, storageRef: file.storageRef, storageProvider: file.storageProvider }, executionContext);
+            const chunks = [];
+            for await (const chunk of download.stream) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            resolved.push({
+                fileId: file.fileId,
+                filename: file.filename,
+                mimeType: file.mimeType,
+                bytes: Buffer.concat(chunks),
+            });
+        }
+        return resolved;
+    }
     /**
      * Update file status (e.g., PENDING -> UPLOADED, UPLOADED -> LINKED).
      *