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

package/dist/esm/files/handlers/resource-file-upload-handler.backend.service.js

@@ -35,7 +35,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { injectable, inject } from 'inversify';
 import fs from 'fs';
-import { ErrorType, ErrorCustomMessageReference, FileStatus, FILE_DOWNLOADABLE_STATUSES, FILE_METADATA_WITHHELD_STATUSES, ResourcePrimaryScope, isWildoBackendError, parseFileServeVariant } from '@wildo-ai/saas-models';
+import { ErrorType, ErrorCustomMessageReference, FileStatus, FILE_DOWNLOADABLE_STATUSES, FILE_METADATA_WITHHELD_STATUSES, ResourcePrimaryScope, isWildoBackendError, parseFileServeVariant, FileRemoteReferenceLinkRead, readFileRemoteReferenceLinkRequest } from '@wildo-ai/saas-models';
 import { FileGenerationSource } 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';
@@ -125,6 +125,27 @@ let ResourceFileUploadHandlerBackendService = class ResourceFileUploadHandlerBac
             operation,
             hasFile: !!request.file,
         });
+        // One route, two bodies (#394 P5): a multipart `file` carries bytes; a JSON `remoteReference`
+        // carries a picker's reference to a file that STAYS at a vendor. Dispatched before anything is
+        // read off `request.file`, so a reference never reaches the byte path and a body that is neither
+        // fails as "no file" exactly as it did before references existed.
+        const remoteReference = readFileRemoteReferenceLinkRequest(request.body);
+        if (remoteReference.kind === FileRemoteReferenceLinkRead.INVALID) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_REMOTE_REFERENCE_INVALID,
+                context: { resourceType, fieldName, issues: remoteReference.issues },
+            });
+        }
+        if (remoteReference.kind === FileRemoteReferenceLinkRead.PRESENT) {
+            if (request.file) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.FILE_REMOTE_REFERENCE_INVALID,
+                    context: { resourceType, fieldName, message: 'A request carries EITHER a file part OR a remote reference, not both' },
+                });
+            }
+            await this.handleRemoteReferenceLink(response, resourceType, fieldName, resourceId, operation, executionContext, remoteReference.link);
+            return;
+        }
         let fileRecord;
         let uploadReachedSuccessState = false;
         let blobStoredInStorage = false;
@@ -190,23 +211,8 @@ let ResourceFileUploadHandlerBackendService = class ResourceFileUploadHandlerBac
             // written. A refusal above leaves the grant usable for a retry; a race loser is refused by the
             // atomic consume and writes nothing. This handler is NOT on the services-registry pipeline, so its
             // post-operation consumption never sees this request — this is the one consumption site.
-            const grant = response.locals?.fileUploadGrant;
-            if (grant) {
-                await this.consumableTokenService.consumeToken(executionContext.consumableTokenValue);
-                executionContext.markConsumableTokenConsumed();
-            }
-            // Step 5: Create file record (status: PENDING) with scope
-            // Under a grant the file is attributed to the MINTER — the person or machine that delegated the
-            // upload — never to the grant. A user-minted grant already yields that through the token context
-            // (`resolveFileUploaderPrincipal`, CONSUMABLE_TOKEN case); a machine-minted one yields nothing
-            // there, so the grant's own `minter` record is used. Both agree with createFile's mismatch guard.
-            const uploaderPrincipal = grant
-                ? this.fileUploadGrantService.resolveUploaderFromGrant(grant.metadata)
-                : resolveFileUploaderPrincipal(executionContext);
-            if (uploaderPrincipal) {
-                validateUploadedBy(uploaderPrincipal.uploadedBy, this.errorBuilder, executionContext, 'uploadedBy');
-                validateUploadedByEntityType(uploaderPrincipal.uploadedByEntityType, this.errorBuilder, executionContext, 'uploadedByEntityType');
-            }
+            const { grant, uploaderPrincipal } = this.resolveUploaderFromRequest(response, executionContext);
+            await this.consumeUploadGrant(grant, executionContext);
             const createdFile = await this.filesService.createFile({
                 filename: multerFile.originalname || multerFile.filename,
                 originalFilename: multerFile.originalname,
@@ -360,9 +366,20 @@ let ResourceFileUploadHandlerBackendService = class ResourceFileUploadHandlerBac
                                     storageRef: uploadResult.storageRef,
                                 }, executionContext);
                                 blobStoredInStorage = false;
-                                this.logger.warn('Rolled back stored blob after upload status commit failure', {
-                                    fileId: createdFile.fileId,
-                                });
+                                if (storageProvider.retainsBytesOnDelete) {
+                                    // A vendor storage forgets the reference and keeps the bytes (a person's own
+                                    // Drive); saying "rolled back" here would record a removal that never happened.
+                                    this.logger.warn('Forgot the stored reference after upload status commit failure; the bytes remain at the vendor with no row pointing at them', {
+                                        fileId: createdFile.fileId,
+                                        storageProvider: uploadResult.provider,
+                                        storageRef: uploadResult.storageRef,
+                                    });
+                                }
+                                else {
+                                    this.logger.warn('Rolled back stored blob after upload status commit failure', {
+                                        fileId: createdFile.fileId,
+                                    });
+                                }
                             }
                             catch (rollbackError) {
                                 if (!isWildoBackendError(rollbackError) || rollbackError.type !== ErrorType.NOT_FOUND) {
@@ -589,6 +606,168 @@ let ResourceFileUploadHandlerBackendService = class ResourceFileUploadHandlerBac
      * @param executionContext - Execution context for scope values
      * @returns FileScopeIdentifiers derived from parent resource
      */
+    /**
+     * The point of no return for a file upload GRANT (issue #312): every check a caller can act on has
+     * run and nothing has been written. A refusal before this leaves the grant usable for a retry; a
+     * race loser is refused by the atomic consume and writes nothing. This handler is NOT on the
+     * services-registry pipeline, so its post-operation consumption never sees this request — this is
+     * the one consumption site, for bytes and for references alike.
+     */
+    async consumeUploadGrant(grant, executionContext) {
+        if (!grant)
+            return;
+        await this.consumableTokenService.consumeToken(executionContext.consumableTokenValue);
+        executionContext.markConsumableTokenConsumed();
+    }
+    /**
+     * Who the file is attributed to. Under a grant that is the MINTER — the person or machine that
+     * delegated the upload — never the grant. A user-minted grant already yields that through the token
+     * context (`resolveFileUploaderPrincipal`, CONSUMABLE_TOKEN case); a machine-minted one yields
+     * nothing there, so the grant's own `minter` record is used. Both agree with createFile's mismatch
+     * guard. Consuming the grant is a separate step, because a REFERENCE is verified at the vendor AS
+     * this principal before the grant may be spent on it.
+     */
+    resolveUploaderFromRequest(response, executionContext) {
+        const grant = response.locals?.fileUploadGrant;
+        const uploaderPrincipal = grant
+            ? this.fileUploadGrantService.resolveUploaderFromGrant(grant.metadata)
+            : resolveFileUploaderPrincipal(executionContext);
+        if (uploaderPrincipal) {
+            validateUploadedBy(uploaderPrincipal.uploadedBy, this.errorBuilder, executionContext, 'uploadedBy');
+            validateUploadedByEntityType(uploaderPrincipal.uploadedByEntityType, this.errorBuilder, executionContext, 'uploadedByEntityType');
+        }
+        return { grant, uploaderPrincipal };
+    }
+    /**
+     * Link a file that stays at a vendor into this field (#394 P5): a picker's `REMOTE_REFERENCE`
+     * becomes a FILES row in the vendor's storage, with no bytes ever transiting this process.
+     *
+     * The order is the same as a byte upload's, with the vendor standing in for the multer file: the
+     * reference is resolved to a storage by the provider it names, refused unless the FIELD accepts
+     * that storage, DESCRIBED at the vendor as the linking person (which is what proves it real and
+     * readable), held to the field's constraints, and only then does a row exist — PENDING, then
+     * UPLOADED with the reference as its `storageRef`. A row that fails between the two is marked
+     * FAILED like an upload's would be.
+     */
+    async handleRemoteReferenceLink(response, resourceType, fieldName, resourceId, operation, executionContext, link) {
+        this.logDebug('Handling remote reference link', { resourceType, fieldName, resourceId, operation, providerRef: link.providerRef });
+        const fieldMeta = this.fileFieldDetection.getFileFieldMetadata(resourceType, fieldName);
+        if (fieldMeta?.fileMetadata.generation?.source === FileGenerationSource.PDF_TEMPLATE) {
+            throw this.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_GENERATED_FIELD_NOT_WRITABLE,
+                context: { resourceType, fieldName },
+            });
+        }
+        const storageProvider = this.fileStorageRouter.resolveProviderForConnectedProvider(link.providerRef);
+        if (storageProvider === undefined || storageProvider.describeRemoteReference === undefined) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_REMOTE_REFERENCE_PROVIDER_UNKNOWN,
+                context: { resourceType, fieldName, providerRef: link.providerRef },
+            });
+        }
+        const storageAccepted = fieldMeta?.fileMetadata.storageAccepted ?? [];
+        if (!storageAccepted.includes(storageProvider.providerId)) {
+            // The chooser filters on the same declaration, so a client that reaches this typed the
+            // request itself — refused rather than routed to the field's default storage, because a
+            // reference has no bytes to put there.
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_REMOTE_REFERENCE_STORAGE_NOT_ACCEPTED,
+                context: { resourceType, fieldName, providerRef: link.providerRef, storage: storageProvider.providerId, storageAccepted },
+            });
+        }
+        if (!storageProvider.isConfigured()) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: { message: `Storage '${storageProvider.providerId}' is registered but not configured for this application`, providerRef: link.providerRef },
+            });
+        }
+        const scope = this.deriveScopeFromParentResource(resourceType, executionContext);
+        const { grant, uploaderPrincipal } = this.resolveUploaderFromRequest(response, executionContext);
+        const constraint = await this.constraintResolver.resolve({ resourceType, fieldName });
+        const maxFileSize = resolveConfiguredMaxFileSize(this.appConfigService.config.storage?.maxFileSize);
+        // What the PICKER showed, checked before a vendor round trip: a client's facts cannot admit a
+        // file, but they can refuse one early — a 2 GB pick fails here, at no cost, rather than after
+        // the vendor confirmed it is 2 GB. The vendor's facts below decide; these only short-circuit.
+        if (link.sizeBytes !== undefined || link.mimeType !== undefined) {
+            const claimedViolations = collectRemoteReferenceConstraintViolations({ ...constraint, maxSize: Math.min(constraint.maxSize, maxFileSize) }, { contentType: link.mimeType, size: link.sizeBytes });
+            if (claimedViolations.length > 0) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: { message: 'File validation failed', errors: claimedViolations, filename: link.displayName, mimeType: link.mimeType, size: link.sizeBytes },
+                });
+            }
+        }
+        const description = await storageProvider.describeRemoteReference(link.externalId, uploaderPrincipal ?? {}, executionContext);
+        validateContentType(description.contentType, this.errorBuilder, executionContext, 'contentType');
+        validateSize(description.size, maxFileSize, this.errorBuilder, executionContext, 'size');
+        const violations = collectRemoteReferenceConstraintViolations(constraint, description);
+        if (violations.length > 0) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: { message: 'File validation failed', errors: violations, filename: description.name, mimeType: description.contentType, size: description.size },
+            });
+        }
+        await this.consumeUploadGrant(grant, executionContext);
+        let fileRecord;
+        // Set once the row is committed (UPLOADED, or SCANNING after a required scan): from then on a
+        // failure is the RESPONSE's, and the catch below must not roll a committed row to FAILED —
+        // the same guard the byte path holds as `uploadReachedSuccessState`.
+        let linkReachedSuccessState = false;
+        try {
+            const createdFile = await this.filesService.createFile({
+                filename: description.name,
+                originalFilename: link.displayName ?? description.name,
+                mimeType: description.contentType,
+                size: description.size,
+                checksum: description.etag,
+                storageProvider: storageProvider.providerId,
+                scope,
+                uploadedBy: uploaderPrincipal?.uploadedBy,
+                uploadedByEntityType: uploaderPrincipal?.uploadedByEntityType,
+            }, executionContext);
+            fileRecord = { fileId: createdFile.fileId };
+            let linkedFile = await this.filesService.updateFileStatus(createdFile.fileId, FileStatus.UPLOADED, executionContext, undefined, { storageRef: link.externalId, provider: storageProvider.providerId });
+            // The same scan control the byte path holds, FAIL-CLOSED for the same reason: a linked
+            // file is servable the moment it is UPLOADED, and a field whose policy is `required` — or
+            // an application with a scanner configured — must not get a servable, unscanned row through
+            // the side door a reference opens. The scanner downloads through the storage as the linker
+            // (`downloadParams` carries `uploadedBy`), so a Drive file scans like any other.
+            if (this.fileScanningService.shouldScan(fieldMeta?.fileMetadata)) {
+                await this.fileScanningService.initiateScan(linkedFile.fileId, executionContext);
+                const afterScanInitiation = await this.filesService.getFile(linkedFile.fileId, executionContext);
+                if (afterScanInitiation)
+                    linkedFile = afterScanInitiation;
+            }
+            linkReachedSuccessState = linkedFile.status === FileStatus.UPLOADED || linkedFile.status === FileStatus.SCANNING;
+            response.status(200).json({
+                success: true,
+                file: this.filesService.toMetadataResponse(linkedFile),
+            });
+            this.logDebug('Remote reference linked', { fileId: linkedFile.fileId, resourceType, fieldName, storage: storageProvider.providerId });
+            if (grant) {
+                this.fileUploadGrantService
+                    .recordRedemption(grant, { fileId: linkedFile.fileId, mimeType: linkedFile.mimeType, size: linkedFile.size }, executionContext)
+                    .catch((redemptionError) => {
+                    this.logger.error('File upload grant: redemption record failed', {
+                        grantId: grant.token._id,
+                        fileId: linkedFile.fileId,
+                        ...projectCaughtErrorLogFields(redemptionError),
+                    });
+                });
+            }
+        }
+        catch (error) {
+            if (fileRecord && !linkReachedSuccessState) {
+                try {
+                    await this.filesService.updateFileStatus(fileRecord.fileId, FileStatus.FAILED, executionContext);
+                }
+                catch (updateError) {
+                    this.logger.error('Failed to mark linked file as FAILED', { fileId: fileRecord.fileId, ...projectCaughtErrorLogFields(updateError) });
+                }
+            }
+            throw error;
+        }
+    }
     deriveScopeFromParentResource(resourceType, executionContext) {
         // Get parent resource configuration to find its primaryScope
         const resourceConfig = this.resourcesRegistry.getResourceConfiguration(resourceType);
@@ -709,4 +888,25 @@ ResourceFileUploadHandlerBackendService = __decorate([
         FileUploadGrantBackendService])
 ], ResourceFileUploadHandlerBackendService);
 export { ResourceFileUploadHandlerBackendService };
+/**
+ * The field's constraints applied to what the VENDOR says about a file — the same three checks the
+ * multer-file validator runs on bytes, on metadata instead. Extension-vs-MIME is not among them: a
+ * reference carries the vendor's MIME type as fact, and there is no local file to sniff.
+ */
+export function collectRemoteReferenceConstraintViolations(constraint, description) {
+    // Each axis is checked only when the description CARRIES it: a client that claimed a MIME type
+    // and no size has not claimed a size of zero, and a `minSize` field must not refuse it before
+    // the vendor answers. The vendor's description carries both and is checked on both.
+    const violations = [];
+    if (description.contentType !== undefined && constraint.allowedMimeTypes !== undefined && constraint.allowedMimeTypes.length > 0 && !constraint.allowedMimeTypes.includes(description.contentType)) {
+        violations.push(`File type '${description.contentType}' is not allowed. Allowed types: ${constraint.allowedMimeTypes.join(', ')}`);
+    }
+    if (description.size !== undefined && constraint.maxSize !== undefined && description.size > constraint.maxSize) {
+        violations.push(`File size ${description.size} exceeds the maximum of ${constraint.maxSize} bytes`);
+    }
+    if (description.size !== undefined && constraint.minSize !== undefined && description.size < constraint.minSize) {
+        violations.push(`File size ${description.size} is below the minimum of ${constraint.minSize} bytes`);
+    }
+    return violations;
+}
 //# sourceMappingURL=resource-file-upload-handler.backend.service.js.map