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

package/dist/esm/base-classes/services/controllers/controller-resource.backend.service.js

@@ -2,13 +2,15 @@ import 'reflect-metadata';
 import { Router } from 'express';
 import { z } from 'zod';
 import { getZodObjectShape, isExcludedFromUpdate, isZodObject } from '@wildo-ai/zod-decorators';
-import { HttpMethod, DataMode, OPERATION_VARIANT_KEY, ResourcesConfigOperationsDtosBuilderUtils, ResourceOperationsUtils, ResourcesConfigOperationsUrlsBuilderUtils, extractCrdtFieldNames } from '@wildo-ai/saas-models';
+import { HttpMethod, DataMode, OPERATION_VARIANT_KEY, ResourcesConfigOperationsDtosBuilderUtils, ResourceOperationsUtils, ResourcesConfigOperationsUrlsBuilderUtils, extractCrdtFieldNames, COLLECTION_QUERY_PARAMETERS, BackendApiType, FileUploadGrantMintRequestSchema, MAIN_API_BASE_PATH, } from '@wildo-ai/saas-models';
 import { summarizeZodIssues } from '@wildo-ai/saas-models';
 import { buildCollectionExportFilename, COLLECTION_EXPORT_CONTENT_TYPES, COLLECTION_EXPORT_FORMAT_QUERY_PARAM, COLLECTION_EXPORT_ROW_COUNT_HEADER, COLLECTION_EXPORT_ROW_SCOPE_QUERY_PARAM, ResourceCollectionExportFormat, ResourceCollectionExportRowScope, ResourceGeneratedOperationKind, resolveCollectionExportCsvColumns, resolveRequestedCollectionExportFormat, resolveRequestedCollectionExportRowScope, toCsvHeaderRow, toCsvRow, } from '@wildo-ai/saas-models';
 import { CoreResourceOperation, ALL_COLLECTION_OPERATIONS, OPERATIONS_WITHOUT_REQUEST_BODY } from '@wildo-ai/saas-models';
 import { ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, ErrorType, ErrorCustomMessageReference, WildoHeaderKeys, getContextAddressedCompositionSingletonRelationshipCandidates, isWildoBackendError, RelationshipNature, ResourceRelationshipCardinality } from '@wildo-ai/saas-models';
 import { projectWildoBackendErrorLogFields, projectCaughtErrorLogFields, describeCaughtError } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
 import { createMulterUploadConfig } from '../../../files/utils/file-upload.utils.js';
+import { FileUploadGrantBackendService } from '../../../files/services/file-upload-grant.backend.service.js';
+import { getClientIpFromRequest } from '../../../runtime/utils/request-client-ip.utils.js';
 import { resolveConfiguredMaxFileSize } from '../../../files/utils/file-validation.utils.js';
 import { initializeValidateFieldRoutes } from './validate-field-handler.backend.service.js';
 import { serializeOperationResultForResponse } from './utils/operation-response-serializer.backend.utils.js';
@@ -324,7 +326,7 @@ export function extractCollectionFilters(rawData, filterFields) {
  *  - a scalar (`string` / `number` / `boolean` / `null` / `Date`), or
  *  - an array of scalars, or
  *  - a range object whose keys are exactly {@link RANGE_FILTER_SUBKEYS}, the framework's OWN named
- *    date-range vocabulary (`Resouces_Filter_DateRangeSchema`), with scalar bounds.
+ *    date-range vocabulary (`Resources_Filter_DateRangeSchema`), with scalar bounds.
  *
  * Anything else is refused, whatever engine's syntax it happens to be written in. Adding a genuinely
  * new structured filter shape is then a deliberate edit to this predicate and its named vocabulary,
@@ -354,9 +356,9 @@ function isPermittedFilterValue(value) {
     return entries.length > 0
         && entries.every(([key, bound]) => RANGE_FILTER_SUBKEYS.has(key) && isPermittedFilterScalar(bound));
 }
-/** Date-range filters accepted on every collection op (mirrors `Resouces_Filter_BaseSchema`). */
+/** Date-range filters accepted on every collection op (mirrors `Resources_Filter_BaseSchema`). */
 const UNIVERSAL_RANGE_FILTER_FIELDS = ['createdAt', 'updatedAt'];
-/** The two sub-keys of a `Resouces_Filter_DateRangeSchema` range object. */
+/** The two sub-keys of a `Resources_Filter_DateRangeSchema` range object. */
 const RANGE_FILTER_SUBKEYS = new Set(['startDate', 'endDate']);
 /**
  * Reconstruct date-range filters sent as BRACKETED query keys
@@ -364,7 +366,7 @@ const RANGE_FILTER_SUBKEYS = new Set(['startDate', 'endDate']);
  * `{ startDate, endDate }` object the SEARCH request DTO expects.
  *
  * WHY THIS EXISTS — a date-range filter is authored as an OBJECT
- * (`Resouces_Filter_DateRangeSchema` → `{ startDate?: Date, endDate?: Date }`), and
+ * (`Resources_Filter_DateRangeSchema` → `{ startDate?: Date, endDate?: Date }`), and
  * the frontend HTTP client / any generated SDK serialise it with bracket notation
  * (OpenAPI `style: deepObject`). Express 5 defaults its query parser to `simple`
  * (`querystring.parse`), under which `createdAt[startDate]=x` arrives as the LITERAL
@@ -465,11 +467,12 @@ export class ControllerResourceBackendService {
     anonymousSessionService;
     appConfigService;
     rateLimitService;
+    fileUploadGrantService;
     resourceConfiguration;
     operationsMap;
     router;
     logDebug;
-    constructor(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService) {
+    constructor(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService, fileUploadGrantService) {
         this.logger = logger;
         this.errorBuilder = errorBuilder;
         this.errorHandler = errorHandler;
@@ -487,6 +490,7 @@ export class ControllerResourceBackendService {
         this.anonymousSessionService = anonymousSessionService;
         this.appConfigService = appConfigService;
         this.rateLimitService = rateLimitService;
+        this.fileUploadGrantService = fileUploadGrantService;
         this.resourceConfiguration = this.resourcesRegistry.getResourceConfiguration(resourceType);
         this.router = Router();
         this.operationsMap = new Map();
@@ -951,8 +955,8 @@ export class ControllerResourceBackendService {
     // ================================
     // Initialization
     // ================================
-    static createInstance(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService) {
-        return new ControllerResourceBackendService(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService);
+    static createInstance(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService, fileUploadGrantService) {
+        return new ControllerResourceBackendService(resourceType, logger, errorBuilder, errorHandler, jwtService, authorizationsService, resourcesRegistry, executionContextCreator, executionContextHandler, repositoriesRegistry, resourceOperationHelper, servicesRegistry, fileFieldDetection, fileUploadHandler, auditLogsService, anonymousSessionService, appConfigService, rateLimitService, fileUploadGrantService);
     }
     initializeOperationsMap() {
         if (!this.resourceConfiguration.operations) {
@@ -1190,12 +1194,13 @@ export class ControllerResourceBackendService {
                     requiresTargetResourceId: false,
                     resourceType,
                     fieldName,
+                    grantOperation: CoreResourceOperation.CREATE,
                 });
                 this.router.post(createPath, authorizeCreateUpload, upload.single('file'), // Multer middleware - expects 'file' field name
                 this.asyncHandler(async (req, res, next) => {
                     try {
                         const executionContext = res.locals.fileUploadExecutionContext
-                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, createOperation, {
+                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, FileUploadGrantBackendService.withUploadGrantAcceptance(createOperation), {
                                 url: fileUploadInitiatorInfo.url,
                                 parameters: fileUploadInitiatorInfo.parameters,
                             });
@@ -1212,6 +1217,9 @@ export class ControllerResourceBackendService {
                     path: createPath,
                     parentParams: fileUploadInitiatorInfo.parameters.map(p => `${p.fieldIdentifier}:${p.resourceType}`).join(', ') || 'none',
                 });
+                // Mint door (issue #312, D3): a SIBLING of the upload route, behind the SAME authorization
+                // middleware, so mint-authority ≡ upload-authority by construction.
+                this.router.post(`${createPath}/grant`, authorizeCreateUpload, this.asyncHandler(this.buildFileUploadGrantMintHandler({ resourceType, fieldName, operation: CoreResourceOperation.CREATE })));
             }
             // UPDATE routes (one per parent combination)
             // Register more specific routes first (with parent paths) for correct Express matching
@@ -1227,6 +1235,7 @@ export class ControllerResourceBackendService {
                     allowContextAddressedTarget: options.allowContextAddressedTarget,
                     resourceType,
                     fieldName,
+                    grantOperation: CoreResourceOperation.UPDATE,
                 });
                 this.router.post(updatePath, authorizeUpdateUpload, upload.single('file'), // Multer middleware
                 this.asyncHandler(async (req, res, next) => {
@@ -1245,7 +1254,7 @@ export class ControllerResourceBackendService {
                             });
                         }
                         const executionContext = locals.fileUploadExecutionContext
-                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, updateOperation, {
+                            ?? await this.executionContextCreator.createExecutionContextFromRequest(req, FileUploadGrantBackendService.withUploadGrantAcceptance(updateOperation), {
                                 url: fileUploadInitiatorInfo.url,
                                 parameters: fileUploadInitiatorInfo.parameters,
                             });
@@ -1255,6 +1264,7 @@ export class ControllerResourceBackendService {
                         next(error);
                     }
                 }));
+                this.router.post(`${updatePath}/grant`, authorizeUpdateUpload, this.asyncHandler(this.buildFileUploadGrantMintHandler({ resourceType, fieldName, operation: CoreResourceOperation.UPDATE })));
                 this.logDebug('File upload UPDATE route registered', {
                     resourceType,
                     fieldName,
@@ -1311,10 +1321,76 @@ export class ControllerResourceBackendService {
      * first avoids unauthenticated callers forcing temp-disk writes through Multer
      * while still reusing the exact same execution context for the later upload.
      */
+    /**
+     * The handler behind `POST …/files/<field>/grant` (issue #312, D3). Runs AFTER the upload route's
+     * own authorization middleware, so by the time it executes the caller has been authorized on the
+     * target write exactly as an upload would be. It computes the two absolute URLs the grant needs from
+     * the request itself — the upload URL is this request's URL minus `/grant`, so it cannot drift from
+     * the route that was just authorized — and delegates the mint to the ONE function the MCP door also
+     * calls. Answers 201 with the grant; the token appears in it because it is the credential.
+     */
+    buildFileUploadGrantMintHandler(target) {
+        return async (req, res, next) => {
+            try {
+                const locals = res.locals;
+                const executionContext = locals.fileUploadExecutionContext;
+                if (!executionContext) {
+                    throw this.errorBuilder.buildError(ErrorType.INTERNAL, {}, {
+                        customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                        context: { message: 'Upload grant mint reached without an authorized context' },
+                    });
+                }
+                const resourceId = target.operation === CoreResourceOperation.UPDATE
+                    ? (locals.fileUploadResolvedResourceId ?? req.params[this.resourceConfiguration.resourceFieldIdentifier])
+                    : undefined;
+                const parsedBody = FileUploadGrantMintRequestSchema.safeParse(req.body ?? {});
+                if (!parsedBody.success) {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: { errors: parsedBody.error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message })) },
+                    });
+                }
+                // The API's own public origin comes from configuration, never from request headers — a
+                // Host header is client-controlled and a grant URL built from it would point wherever the
+                // caller said.
+                const apiPublicUrl = this.appConfigService.config.runtime?.endPoints?.[BackendApiType.MAIN_BACKEND_API]?.publicUrl;
+                if (!apiPublicUrl) {
+                    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                        context: { message: `runtime.endPoints.${BackendApiType.MAIN_BACKEND_API}.publicUrl is required to mint a file upload grant` },
+                    });
+                }
+                const origin = apiPublicUrl.replace(/\/+$/, '');
+                const requestPath = (req.originalUrl.split('?')[0] ?? '').replace(/\/grant\/?$/, '');
+                const uploadUrl = `${origin}${requestPath}`;
+                const apiBaseUrl = `${origin}${req.baseUrl || MAIN_API_BASE_PATH}`;
+                const grant = await this.fileUploadGrantService.mint({
+                    executionContext,
+                    target: { ...target, resourceId },
+                    expiresInMinutes: parsedBody.data.expiresInMinutes,
+                    declared: { name: parsedBody.data.name, mimeType: parsedBody.data.mimeType, size: parsedBody.data.size },
+                    uploadUrl,
+                    apiBaseUrl,
+                    requestProvenance: {
+                        ipAddress: getClientIpFromRequest(req),
+                        userAgent: typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined,
+                    },
+                });
+                res.status(201).json(grant);
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
     createFileUploadAuthorizationMiddleware(operation, fileUploadInitiatorInfo, options) {
+        // The upload routes — and ONLY the upload routes — accept a file upload GRANT as an ALTERNATIVE
+        // credential (issue #312, D4). The authored operation is left untouched, so the JSON CREATE/UPDATE
+        // routes refuse the same token (GATE 1, `CONSUMABLE_TOKEN_NOT_ACCEPTED_FOR_OPERATION`).
+        const acceptingOperation = FileUploadGrantBackendService.withUploadGrantAcceptance(operation);
         return this.asyncHandler(async (req, res, next) => {
             try {
-                let executionContext = await this.executionContextCreator.createExecutionContextFromRequest(req, operation, {
+                let executionContext = await this.executionContextCreator.createExecutionContextFromRequest(req, acceptingOperation, {
                     url: fileUploadInitiatorInfo.url,
                     parameters: fileUploadInitiatorInfo.parameters,
                 });
@@ -1343,6 +1419,26 @@ export class ControllerResourceBackendService {
                         },
                     });
                 }
+                // A grant is bound to ONE (resource, field, operation kind, row) AND to ONE concrete route.
+                // Checked BEFORE the authorizer so a grant minted for another field never even reaches a role
+                // check on this one; a non-grant context passes through untouched. Mirrors `validateFileToken`
+                // on the download twin.
+                //
+                // `req.originalUrl` is the raw request target as received — the SAME thing the mint recorded
+                // (`origin + req.originalUrl` minus the query and the `/grant` suffix), so the two sides of the
+                // comparison are produced by one recipe and cannot drift. It is passed raw, query included:
+                // the service owns the normalisation, so there is nowhere else for a caller to get it wrong.
+                // This middleware also fronts the `/grant` mint route, whose path carries that extra segment —
+                // a grant presented there therefore mismatches, which is the intended answer.
+                const grant = await this.fileUploadGrantService.assertGrantMatchesRoute(executionContext, {
+                    resourceType: options.resourceType,
+                    fieldName: options.fieldName,
+                    operation: options.grantOperation,
+                    resourceId,
+                }, req.originalUrl);
+                if (grant) {
+                    locals.fileUploadGrant = grant;
+                }
                 await this.authorizationsService.authorizeInController(resourceId, executionContext);
                 if (resourceId) {
                     await this.ensureFileUploadTargetMatchesRouteContext(operation, resourceId, executionContext, { requireRouteContext: options.allowContextAddressedTarget });
@@ -1571,9 +1667,10 @@ export class ControllerResourceBackendService {
                      * encodes a remote entity's key and an `INTROSPECTION`-backed resource's id is whatever
                      * its projection calls the row — neither can be an ObjectId or a UUID, and
                      * `ResourceIdBackendService.getFormatForResource` exists precisely to say so. Measured on
-                     * the introspection lane: `GET …/workbench-application-modules` answered 200 with 8 rows
-                     * while `…/workbench-application-modules/engine` answered 400 `invalid_format`, because
-                     * the branch that would have admitted `engine` was never entered.
+                     * the introspection lane, against the workbench's module projection (a resource since
+                     * superseded by `workbench-domain-resources`): the LIST answered 200 with 8 rows while the
+                     * addressed READ of the row keyed `engine` answered 400 `invalid_format`, because the
+                     * branch that would have admitted `engine` was never entered.
                      *
                      * Passing the resource type does not loosen anything for platform-backed rows: the helper
                      * resolves their format to the application's declared ObjectId or UUID and validates
@@ -2085,7 +2182,18 @@ export class ControllerResourceBackendService {
         return normalizeCollectionQueryRequestData(rawRequestData, operation, effectiveOperation, this.resourceConfiguration.operations);
     }
     buildCollectionQueryRequestDtoInput(req, operation, effectiveOperation) {
-        const requestData = { ...req.params, ...req.query, ...req.body };
+        // ROUTING IS NOT PAYLOAD. `req.params` carries the route's scope ids (`organizationId`,
+        // `applicationId`) and the instance id — none of which the caller "sent". Merging them into the
+        // request-DTO input conflates where a request was ROUTED with what it CONTAINS, and a `.strict()`
+        // DTO then rejects every request including `{}` (measured on `auditLogs | exportAuditLogs`, #319).
+        //
+        // The defect was latent everywhere and surfaced only where an author was rigorous: every
+        // non-strict DTO silently accepted the injected keys and ignored them, so being strict was the
+        // thing that broke. Nothing is lost by excluding them — the instance id is read separately from
+        // `req.params[resourceFieldIdentifier]` at its own call sites, and the scope is authoritative on
+        // the execution context (`initiatorIds`), which is where every tenant-isolating consumer already
+        // reads it and the only source a request cannot author for itself.
+        const requestData = { ...req.query, ...req.body };
         const normalizedRequest = this.normalizeCollectionQueryRequestData(requestData, operation, effectiveOperation);
         const filters = { ...normalizedRequest.filter };
         if (effectiveOperation === CoreResourceOperation.SEARCH && normalizedRequest.searchQuery) {
@@ -2106,7 +2214,8 @@ export class ControllerResourceBackendService {
         };
     }
     validateRequestData(req, operation, executionContext) {
-        const _extractedRequestData = (req) => ({ ...req.params, ...req.query, ...req.body });
+        // Routing is not payload — see `buildCollectionQueryRequestDtoInput` for the full reasoning (#319).
+        const _extractedRequestData = (req) => ({ ...req.query, ...req.body });
         // Use effectiveOperation to account for resourceOperationLike
         const effectiveOperation = operation.resourceOperationLike || operation.operationIdentifier;
         const hasExplicitRequestDto = hasMeaningfulExplicitRequestDto(operation.requestDto);
@@ -2422,19 +2531,24 @@ export function normalizeCollectionQueryRequestData(rawRequestData, operation, e
         ...extractCollectionFilters(reconstructedRawRequestData, effectiveFilterFields),
         ...extractCollectionFilters(nestedFilters, effectiveFilterFields),
     };
-    const page = parseOptionalPositiveInt(rawRequestData.page)
+    // The flat wire names are the published collection vocabulary
+    // (`COLLECTION_QUERY_PARAMETERS`); the nested `pagination` / `sorting` forms
+    // are the structured-body aliases the frontend client sends.
+    const page = parseOptionalPositiveInt(rawRequestData[COLLECTION_QUERY_PARAMETERS.page])
         ?? parseOptionalPositiveInt(rawRequestData.pagination?.page);
-    const limit = parseOptionalPositiveInt(rawRequestData.limit)
+    const limit = parseOptionalPositiveInt(rawRequestData[COLLECTION_QUERY_PARAMETERS.limit])
         ?? parseOptionalPositiveInt(rawRequestData.pagination?.limit);
     if (effectiveOperation === CoreResourceOperation.SEARCH) {
-        const searchQuery = (typeof rawRequestData.q === 'string' && rawRequestData.q.trim() !== ''
-            ? rawRequestData.q
-            : typeof rawRequestData.searchQuery === 'string' && rawRequestData.searchQuery.trim() !== ''
-                ? rawRequestData.searchQuery
+        const rawSearch = rawRequestData[COLLECTION_QUERY_PARAMETERS.search];
+        const rawSearchAlias = rawRequestData[COLLECTION_QUERY_PARAMETERS.searchAlias];
+        const searchQuery = (typeof rawSearch === 'string' && rawSearch.trim() !== ''
+            ? rawSearch
+            : typeof rawSearchAlias === 'string' && rawSearchAlias.trim() !== ''
+                ? rawSearchAlias
                 : typeof nestedFilters.searchRequest === 'string' && nestedFilters.searchRequest.trim() !== ''
                     ? nestedFilters.searchRequest
                     : undefined);
-        const sort = parseCollectionQuerySort(rawRequestData.sort)
+        const sort = parseCollectionQuerySort(rawRequestData[COLLECTION_QUERY_PARAMETERS.sort])
             ?? normalizeCollectionSorting(rawRequestData.sorting);
         return { filter, page, limit, searchQuery, sort };
     }
@@ -2447,7 +2561,7 @@ export function normalizeCollectionQueryRequestData(rawRequestData, operation, e
         // absent `sort` falls back to the operation's sortFields default, or
         // createdAt-desc when none are configured — i.e. no behaviour change for
         // callers that don't pass `sort`.
-        const sort = parseCollectionQuerySort(rawRequestData.sort);
+        const sort = parseCollectionQuerySort(rawRequestData[COLLECTION_QUERY_PARAMETERS.sort]);
         return { filter, page, limit, sort };
     }
     return { filter };