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

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

@@ -14,6 +14,7 @@ import { AuthorizationsBackendService } from '../../../security/authorizations/s
 import { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service';
 import { ResourceFileUploadHandlerBackendService } from '../../../files/handlers/resource-file-upload-handler.backend.service';
 import { FileFieldDetectionBackendService } from '../../../files/services/file-field-detection.backend.service';
+import { FileUploadGrantBackendService } from '../../../files/services/file-upload-grant.backend.service';
 import { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service';
 import { ExecutionContextHandlerBackendService } from '../../../runtime/services/execution-context-handler.backend.service';
 import { ResourceOperationHelperBackendService } from '../../../base-classes/services/resource-operations-helper.backend.service';
@@ -90,7 +91,7 @@ export declare function extractCollectionFilters(rawData: Record<string, unknown
  * `{ 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
@@ -137,11 +138,12 @@ export declare class ControllerResourceBackendService<TCustomOperationEnum exten
     private readonly anonymousSessionService;
     private readonly appConfigService;
     private readonly rateLimitService;
+    private readonly fileUploadGrantService;
     private readonly resourceConfiguration;
     private readonly operationsMap;
     private readonly router;
     protected logDebug: (message: string, context?: Record<string, unknown>) => void;
-    constructor(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService, rateLimitService: RateLimitBackendService);
+    constructor(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService, rateLimitService: RateLimitBackendService, fileUploadGrantService: FileUploadGrantBackendService);
     getRouter(): Router;
     private resolveContextAddressedSingletonOperationAuthorizationId;
     /**
@@ -165,7 +167,7 @@ export declare class ControllerResourceBackendService<TCustomOperationEnum exten
     private resolveAssociationParentContextResourceId;
     private stringifyPersistedValue;
     private ensureFileUploadTargetMatchesRouteContext;
-    static createInstance<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodTypeAny>(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService, rateLimitService: RateLimitBackendService): ControllerResourceBackendService<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+    static createInstance<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodTypeAny>(resourceType: ResourceType, logger: LoggerService, errorBuilder: ErrorBuilderBackendService, errorHandler: ErrorHandlerService, jwtService: JwtBackendService, authorizationsService: AuthorizationsBackendService, resourcesRegistry: ResourcesRegistryBackendService, executionContextCreator: ExecutionContextCreatorBackendService, executionContextHandler: ExecutionContextHandlerBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, resourceOperationHelper: ResourceOperationHelperBackendService, servicesRegistry: ServicesRegistryHandlerBackendService, fileFieldDetection: FileFieldDetectionBackendService, fileUploadHandler: ResourceFileUploadHandlerBackendService, auditLogsService: AuditLogsBackendService, anonymousSessionService: AnonymousSessionBackendService, appConfigService: AppConfigurationService, rateLimitService: RateLimitBackendService, fileUploadGrantService: FileUploadGrantBackendService): ControllerResourceBackendService<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
     private initializeOperationsMap;
     private initializeRoutes;
     /**
@@ -231,6 +233,15 @@ export declare class ControllerResourceBackendService<TCustomOperationEnum exten
      * 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.
+     */
+    private buildFileUploadGrantMintHandler;
     private createFileUploadAuthorizationMiddleware;
     /**
      * Initialize validate-field routes for resources with unique fields.

package/dist/esm/base-classes/services/controllers/controller-resource.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller-resource.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/base-classes/services/controllers/controller-resource.backend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"controller-resource.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/base-classes/services/controllers/controller-resource.backend.service.ts"],"names":[],"mappings":"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"}

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,75 @@ 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,
+                    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 +1418,18 @@ export class ControllerResourceBackendService {
                         },
                     });
                 }
+                // A grant is bound to ONE (resource, field, operation kind, row). 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.
+                const grant = await this.fileUploadGrantService.assertGrantMatchesRoute(executionContext, {
+                    resourceType: options.resourceType,
+                    fieldName: options.fieldName,
+                    operation: options.grantOperation,
+                    resourceId,
+                });
+                if (grant) {
+                    locals.fileUploadGrant = grant;
+                }
                 await this.authorizationsService.authorizeInController(resourceId, executionContext);
                 if (resourceId) {
                     await this.ensureFileUploadTargetMatchesRouteContext(operation, resourceId, executionContext, { requireRouteContext: options.allowContextAddressedTarget });
@@ -1571,9 +1658,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
@@ -2422,19 +2510,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 +2540,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 };