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

package/dist/esm/mcp/services/mcp-server.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.backend.service.js","sourceRoot":"","sources":["../../../../../src/mcp/services/mcp-server.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, inject } from 'inversify';\nimport {\n  ResourceType,\n  ResourceConfiguration_OperationPath,\n  ResourcesConfig_OperationPathUtils,\n  CoreResourceOperation,\n  ErrorType,\n  ErrorCustomMessageReference,\n} from '@wildo-ai/saas-models';\nimport { z } from 'zod';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';\nimport { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';\nimport { toResponseSafeToolOutput } from '~wildo-backend-lib/base-classes/services/controllers/utils/operation-response-serializer.backend.utils';\nimport { normalizeCollectionQueryRequestData } from '~wildo-backend-lib/base-classes/services/controllers/controller-resource.backend.service';\nimport { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport {\n  McpToolAdapterBackendService,\n  mcpReachableScopesForPrincipal,\n  mcpPrincipalForAuthenticatedCaller,\n  resolveEffectiveMcpOperation,\n  isCollectionQueryMcpOperation,\n} from '~wildo-backend-lib/mcp/services/mcp-tool-adapter.backend.service';\nimport {\n  McpToolDescriptor,\n  McpToolAdapterBuildOptions,\n  MCP_TOOL_NAME_SEPARATOR,\n} from '~wildo-backend-lib/mcp/models/mcp-tool.backend.schemas';\n\n/**\n * Per-call options for {@link McpServerBackendService.callTool}.\n */\nexport interface McpCallToolOptions {\n  /**\n   * Target resource id for resource-specific operations (READ / UPDATE / DELETE\n   * and instance-scoped custom operations). Omit for collection operations\n   * (CREATE / LIST / SEARCH / COUNT), which authorize on roles + parent scope only.\n   */\n  resourceId?: string;\n  /**\n   * The NAMED MCP server instance this call arrived on (R-2), or omitted for the default `/mcp`\n   * server. MUST mirror the transport's route: the exposability gate below re-resolves the tool\n   * against this instance, so a tool curated onto another server is NOT callable here even by name.\n   */\n  instanceRef?: string;\n}\n\n/**\n * Result of a successful `tools/call`. `result` is the operation output projected\n * through the operation's response DTO (backend-only/secret fields stripped, dates\n * JSON-normalized — see `callTool`), returned WITHOUT MCP `content` framing: the\n * `{ content: [...], isError }` envelope is applied by the transport\n * ({@link MCPControllerBackendService.handleToolsCall}). Keeping this service\n * transport-agnostic lets the same `callTool` back another transport unchanged.\n */\nexport interface McpCallToolResult {\n  toolName: string;\n  result: unknown;\n}\n\n/**\n * The MCP server core: lists resource-operation tools and executes them against\n * the SERVICE layer with per-call authorization. Transport-agnostic — the\n * JSON-RPC / Streamable-HTTP wire layer + OAuth 2.1 resource-server auth\n * (RFC 9728 metadata, RFC 8707 audience validation) live in\n * {@link MCPControllerBackendService}; this core carries no wire concern so the\n * same `listTools`/`callTool` can back another transport unchanged.\n *\n * # Boundaries\n *\n * - `listTools()` delegates to {@link McpToolAdapterBackendService}.\n * - `callTool()` resolves the target operation, RE-RUNS `authorizeInController`\n *   against the caller's execution context (fail-closed), then invokes the\n *   service pipeline DIRECTLY via {@link ServicesRegistryHandlerBackendService}\n *   (never re-HTTP). The service pipeline enforces `requiredFeatures` /\n *   `enabledCondition` downstream.\n * - KNOWN GAP (tracked — `.claude/plans/mcp-server-followups.md` Item 5): the\n *   per-route HTTP rate-limit middleware is bypassed on this direct dispatch path,\n *   so an operation's `rateLimit` policy is not yet enforced here. The planned fix\n *   is a per-principal quota shared with the A2A dispatch surface.\n * - Server-initiated streaming (SSE / notifications / progress) is intentionally\n *   absent: every exposed operation is synchronous request/response, for which a\n *   single JSON response is Streamable-HTTP-compliant (Item 1, deferred).\n */\n/**\n * Operations whose RESULT is the paginated `{ data, pagination }` envelope, for OUTPUT.\n *\n * Deliberately NOT the same set as {@link isCollectionQueryOperation}: `COUNT` takes the collection\n * argument envelope but RETURNS A SCALAR, so asking the repository to wrap it would hand back a\n * shape its response DTO does not declare — trading one contract mismatch for another.\n *\n * Mirrors `needsPagination` in `ControllerResourceBackendService`, which is where this decision has\n * always been made for the HTTP surface. The two must agree: they select the shape the SAME response\n * DTO is asked to validate.\n */\nfunction isPaginationWrappedOperation(effectiveOperation: string): boolean {\n  return effectiveOperation === CoreResourceOperation.LIST\n    || effectiveOperation === CoreResourceOperation.SEARCH;\n}\n\n@injectable()\nexport class McpServerBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) protected readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) protected readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.McpToolAdapter) protected readonly toolAdapter: McpToolAdapterBackendService,\n    @inject(SAAS_SERVICE_TYPES.AuthorizationsService) protected readonly authorizer: AuthorizationsBackendService,\n    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) protected readonly servicesHandler: ServicesRegistryHandlerBackendService,\n    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) protected readonly resourcesRegistry: ResourcesRegistryBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('McpServerBackendService');\n    this.logger.setDebugTypeLogging('McpServerBackendService', false);\n  }\n\n  /**\n   * Return the exposed tool descriptors for the caller's reachable scopes (`options.reachableScopes`).\n   * PROGRESSIVE principal-awareness (C): a caller presenting a valid Bearer bound to this endpoint\n   * passes its principal's scopes, so a user-delegated caller additionally sees its USER_SELF tools.\n   * Omitting the scopes yields the MACHINE catalog; an ANONYMOUS caller passes an EMPTY set and the\n   * transport challenges it rather than serving the empty page. Authorization is still enforced\n   * fail-closed at `callTool` time — the catalog is a discovery aid, never an authorization grant.\n   */\n  public listTools(options: McpToolAdapterBuildOptions = {}): McpToolDescriptor[] {\n    return this.toolAdapter.buildToolDescriptors(options);\n  }\n\n  /**\n   * Execute one tool: resolve → authorize (fail-closed) → dispatch to the service layer.\n   *\n   * @param toolName - `<resourceIdentifier>__<operationIdentifier>`.\n   * @param args - the tool arguments (the operation request body).\n   * @param executionContext - the caller's context (a machine principal for api-key\n   *        / client-credentials callers; a user-delegated context once OIDC lands).\n   * @param options - per-call options ({@link McpCallToolOptions}).\n   * @throws AUTHORIZATION when the principal is not permitted to run the operation.\n   * @throws NOT_FOUND when the tool name does not map to an exposable operation.\n   */\n  public async callTool(\n    toolName: string,\n    args: unknown,\n    executionContext: ExecutionContext<any>,\n    options: McpCallToolOptions = {},\n  ): Promise<McpCallToolResult> {\n    const { resourceType, operationIdentifier } = this.parseToolName(toolName);\n\n    // Single source of exposability truth: the adapter decides whether this resource+operation is a\n    // valid, default URL-bearing tool REACHABLE BY THIS CALLER. Progressive principal-awareness — a\n    // user-delegated principal (USER_REQUEST, carries a `userId`) reaches USER_SELF operations; a\n    // machine principal reaches ORG/APP only. Rejecting here (before authorization) prevents a crafted\n    // name from reaching a scope the caller cannot use (e.g. a machine hitting USER_SELF → always 403).\n    // Derived from the SAME source `tools/list` filters on, so advertise ≡ callable per principal.\n    // R-2: also gated on the server INSTANCE the call arrived on, so `(principal, instance)` together\n    // decide callability — the same pair `tools/list` filters on.\n    // Post-authentication by construction: `callTool` is only reached with a validated token.\n    const reachableScopes = mcpReachableScopesForPrincipal(mcpPrincipalForAuthenticatedCaller(executionContext.isUserExecution()));\n    const operation = this.toolAdapter.resolveExposableOperation(resourceType, operationIdentifier, reachableScopes, options.instanceRef);\n    if (!operation) {\n      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n        customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND,\n        context: { message: `MCP tool \"${toolName}\" does not map to an exposable resource operation`, toolName },\n      });\n    }\n\n    // Bind the resolved operation onto the caller's context (preserves principal\n    // identity + roles) so the authorizer and the service pipeline both see the\n    // operation actually being executed.\n    const boundExecutionContext = executionContext.withOperation(operation);\n\n    const idOrIds = options.resourceId;\n\n    // Fail-closed per-operation authorization: reads `operation.roles` +\n    // `executionContext.initiatorRoles` / scope. Throws AUTHORIZATION on denial.\n    await this.authorizer.authorizeInController(idOrIds, boundExecutionContext);\n\n    // Dispatch to the service layer directly (NOT re-HTTP). The service pipeline\n    // enforces enabledCondition / requiredFeatures downstream.\n    //\n    // Dispatch the EXACT operation we resolved + authorized + advertised (the URL-bearing default\n    // from `resolveExposableOperation`), via `extractOperationPath`. We deliberately do NOT\n    // re-resolve through `getServiceOperationPathDefault`: for a resource that declares BOTH a\n    // URL-bearing default AND an INTERNAL_CALL default for the same operation identifier, that\n    // helper PREFERS the INTERNAL_CALL variant — which would execute a different variant (different\n    // `requestDto` validating `args`, different side effects / custom-impl) than the one\n    // `authorizeInController` just checked and than the `inputSchema` advertised to the agent.\n    // Using the resolved operation's own path mirrors how the HTTP controllers dispatch the URL\n    // operation and keeps authorize ≡ advertise ≡ execute on one variant.\n    const operationPath: ResourceConfiguration_OperationPath<any, any> = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);\n\n    const dispatchArgs = this.toDispatchArguments(operation, args, boundExecutionContext);\n\n    this.logDebug('Executing MCP tool call', { toolName, resourceType, operationIdentifier, hasResourceId: idOrIds !== undefined });\n\n    /**\n     * Request the pagination WRAPPER for collection operations, exactly as the HTTP controller does.\n     *\n     * The repository's `list` returns a BARE ARRAY unless the caller asks for the envelope\n     * (`options.paginated`), and the decision to ask is made in `ControllerResourceBackendService`:\n     * `needsPagination = LIST || SEARCH` → `{ paginated: true }`. That is a CONTROLLER-tier\n     * decision, and this path does not go through the controller — so `tools/call` dispatched a\n     * paginated LIST without ever requesting pagination, the repository returned a bare array, and\n     * the operation's RESPONSE DTO (which for a paginated list declares `{ data, pagination }`)\n     * rejected it. Every paginated `*__list` tool answered `-32603` with\n     * `expected array, received undefined` at `data`.\n     *\n     * Two things hid it. `*__search` was unaffected — the search path builds its own envelope — and\n     * the one LIST that worked (`todosRelationships__list`) is UNPAGINATED, so a bare array is\n     * exactly what its response DTO declares. So the failure looked resource-specific when it was\n     * operation-wide.\n     *\n     * This is the OUTPUT half of the defect family the input normalisation already fixed on\n     * 2026-08-01: \"the advertised contract is not the enforced contract\". `tools/list` advertises a\n     * paginated collection envelope because the response DTO says so; the dispatch has to request\n     * the shape that DTO describes, or the two tiers disagree about what the operation returns.\n     */\n    const needsPaginationWrapper = isPaginationWrappedOperation(this.resolveEffectiveOperation(operation));\n\n    const result = await this.servicesHandler.doByOperationPath(\n      operationPath,\n      boundExecutionContext,\n      idOrIds,\n      dispatchArgs,\n      needsPaginationWrapper ? { paginated: true } : undefined,\n    );\n\n    // Project the raw service result through the operation's RESPONSE DTO — the SAME\n    // output-serialization boundary the HTTP controller (`sendResponse`) and the A2A tool\n    // path use — BEFORE it crosses to the external MCP agent. `doByOperationPath` returns the\n    // internal DTO, which still carries `.isBackendOnly()` / write-only-secret fields and raw\n    // `Date`/`ObjectId` instances; returning it verbatim would leak backend-only/secret material\n    // into the agent's model context. `toResponseSafeToolOutput` strips + JSON-normalizes so the\n    // MCP tool result is byte-identical to what a REST client would receive.\n    const safeResult = await toResponseSafeToolOutput(operation, result);\n\n    return { toolName, result: safeResult };\n  }\n\n  /**\n   * Split `<resourceIdentifier>__<operationIdentifier>` on the FIRST double\n   * underscore. Resource identifiers use single underscores only, so the first\n   * `__` unambiguously delimits the resource from the operation.\n   */\n  /**\n   * Bring the agent's raw `arguments` onto the SAME input contract the HTTP controller produces\n   * before dispatch. Added 2026-08-01; until then `tools/call` passed `args` through untouched.\n   *\n   * Two distinct defects that fixed, both of the \"advertised contract is not the enforced\n   * contract\" family:\n   *\n   *  1. **Collection tools silently ignored the agent's filter.** `tools/list` advertises an\n   *     `inputSchema` derived from the operation's `requestDto`, which for LIST / SEARCH is keyed\n   *     `{ filters, pagination, sorting }`. The service reads `{ filter, page, limit, sort,\n   *     searchQuery }`. The HTTP controller bridges the two; MCP did not, so an agent that\n   *     followed the schema it was given received the UNFILTERED collection while believing it was\n   *     filtered — the worst shape for an LLM caller, which then reasons over the wrong rows.\n   *     {@link normalizeCollectionQueryRequestData} is now the single authority both surfaces use,\n   *     and it accepts either vocabulary. It also carries the filter ALLOW-LIST, which matters\n   *     here: the repository's `sanitizeRequestFilter` returns the filter UNCHANGED when an\n   *     operation declares no `filterFields`, so for a surface with no strict DTO parse in front\n   *     of it this is the layer that stops an arbitrary key reaching the database.\n   *  2. **The published request contract was not enforced.** Every other operation now gets the\n   *     controller's strict `requestDto.parse`, so a key the tool never advertised is dropped at\n   *     the boundary that advertised it, rather than three layers away. Writes were already safe —\n   *     the repository re-parses against the same DTO\n   *     (`repositories-registry-handler.backend.service.ts`) — but relying on a distant guard for\n   *     an external protocol surface is defence by coincidence: nothing tells a future refactor of\n   *     that method that MCP depends on it.\n   *\n   * Parse failures are deliberately NOT swallowed. An agent that sends a malformed argument should\n   * be told, so the model can correct itself; silently dropping it teaches the model nothing and\n   * leaves it reasoning about an operation it did not actually perform.\n   */\n  private toDispatchArguments(\n    operation: {\n      requestDto?: z.ZodTypeAny;\n      resourceOperationLike?: unknown;\n      operationIdentifier: unknown;\n      resourceIdentifier: unknown;\n    },\n    args: unknown,\n    executionContext: ExecutionContext<any>,\n  ): unknown {\n    const effectiveOperation = this.resolveEffectiveOperation(operation);\n    const isCollectionOperation = isCollectionQueryMcpOperation(effectiveOperation);\n\n    if (isCollectionOperation) {\n      const rawArguments = (args && typeof args === 'object' && !Array.isArray(args))\n        ? args as Record<string, unknown>\n        : {};\n      const resourceOperations = this.resourcesRegistry\n        .getResourceConfiguration(operation.resourceIdentifier as ResourceType)\n        .operations;\n      return normalizeCollectionQueryRequestData(\n        rawArguments,\n        operation as never,\n        effectiveOperation,\n        resourceOperations as never,\n      );\n    }\n\n    if (!operation.requestDto) return args;\n\n    try {\n      return operation.requestDto.parse(args);\n    } catch (error) {\n      if (error instanceof z.ZodError) {\n        throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n          customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,\n          stack: error.stack,\n          context: {\n            message: 'MCP tool arguments do not satisfy the operation request contract advertised by tools/list',\n            operationIdentifier: operation.operationIdentifier,\n            zodIssues: error.issues,\n          },\n        });\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * The operation this tool really performs — a custom operation declares what it behaves LIKE via\n   * `resourceOperationLike`, and both the input normalisation and the output envelope must key on\n   * the same answer. Derived once here because they previously derived it separately, and a\n   * custom LIST-like operation that only one of them recognised would be normalised as a collection\n   * on the way in and dispatched without pagination on the way out.\n   */\n  private resolveEffectiveOperation(operation: { resourceOperationLike?: unknown; operationIdentifier: unknown }): string {\n    return resolveEffectiveMcpOperation(operation);\n  }\n\n  private parseToolName(toolName: string): { resourceType: ResourceType; operationIdentifier: string } {\n    const separatorIndex = toolName.indexOf(MCP_TOOL_NAME_SEPARATOR);\n    if (separatorIndex <= 0 || separatorIndex + MCP_TOOL_NAME_SEPARATOR.length >= toolName.length) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND,\n        context: { message: `Malformed MCP tool name \"${toolName}\" — expected \"<resource>${MCP_TOOL_NAME_SEPARATOR}<operation>\"`, toolName },\n      });\n    }\n    return {\n      resourceType: toolName.slice(0, separatorIndex) as ResourceType,\n      operationIdentifier: toolName.slice(separatorIndex + MCP_TOOL_NAME_SEPARATOR.length),\n    };\n  }\n}\n"]}
+{"version":3,"file":"mcp-server.backend.service.js","sourceRoot":"","sources":["../../../../../src/mcp/services/mcp-server.backend.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAEL,4BAA4B,EAE5B,kCAAkC,EAClC,qBAAqB,EACrB,SAAS,EACT,2BAA2B,EAC3B,cAAc,EACd,kBAAkB,EAClB,gCAAgC,EAChC,yCAAyC,GAI1C,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,EAAE,6BAA6B,EAAE,MAAM,qEAAqE,CAAC;AACpH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AAC/G,OAAO,EAAE,4BAA4B,EAAE,MAAM,wDAAwD,CAAC;AAEtG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAE9G,OAAO,EAAE,4BAA4B,EAAE,MAAM,oFAAoF,CAAC;AAClI,OAAO,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACpJ,OAAO,EAAE,wBAAwB,EAAE,MAAM,wGAAwG,CAAC;AAClJ,OAAO,EAAE,mCAAmC,EAAE,MAAM,0FAA0F,CAAC;AAC/I,OAAO,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAC3H,OAAO,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAC;AACxG,OAAO,EAAE,+BAA+B,EAAE,MAAM,mGAAmG,CAAC;AACpJ,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,kCAAkC,EAClC,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,kEAAkE,CAAC;AAC1E,OAAO,EAGL,uBAAuB,GACxB,MAAM,wDAAwD,CAAC;AAiChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CAAC,kBAA0B;IAC9D,OAAO,kBAAkB,KAAK,qBAAqB,CAAC,IAAI;WACnD,kBAAkB,KAAK,qBAAqB,CAAC,MAAM,CAAC;AAC3D,CAAC;AAGM,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAIsB;IACa;IACL;IACO;IACS;IACP;IACD;IACN;IACO;IAX/D,QAAQ,CAA+D;IAEjF,YACwD,MAAqB,EACR,YAAwC,EAC7C,WAAyC,EAClC,UAAwC,EAC/B,eAAsD,EAC7D,iBAAkD,EACnD,sBAAqD,EAC3D,gBAAyC,EAClC,gBAAyC;QAR1D,WAAM,GAAN,MAAM,CAAe;QACR,iBAAY,GAAZ,YAAY,CAA4B;QAC7C,gBAAW,GAAX,WAAW,CAA8B;QAClC,eAAU,GAAV,UAAU,CAA8B;QAC/B,oBAAe,GAAf,eAAe,CAAuC;QAC7D,sBAAiB,GAAjB,iBAAiB,CAAiC;QACnD,2BAAsB,GAAtB,sBAAsB,CAA+B;QAC3D,qBAAgB,GAAhB,gBAAgB,CAAyB;QAClC,qBAAgB,GAAhB,gBAAgB,CAAyB;QAEhH,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACI,SAAS,CAAC,UAAsC,EAAE;QACvD,OAAO,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;OAUG;IACI,KAAK,CAAC,QAAQ,CACnB,QAAgB,EAChB,IAAa,EACb,gBAAuC,EACvC,UAA8B,EAAE;QAEhC,MAAM,EAAE,YAAY,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAE3E,gGAAgG;QAChG,gGAAgG;QAChG,8FAA8F;QAC9F,mGAAmG;QACnG,oGAAoG;QACpG,+FAA+F;QAC/F,kGAAkG;QAClG,8DAA8D;QAC9D,0FAA0F;QAC1F,MAAM,eAAe,GAAG,8BAA8B,CAAC,kCAAkC,CAAC,gBAAgB,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;QAE/H,kGAAkG;QAClG,iGAAiG;QACjG,mGAAmG;QACnG,IAAI,mBAAmB,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE,CAAC;YAC/D,OAAO,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;QACjI,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,yBAAyB,CAAC,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QACtI,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE;gBACxE,sBAAsB,EAAE,2BAA2B,CAAC,iBAAiB;gBACrE,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,QAAQ,mDAAmD,EAAE,QAAQ,EAAE;aACzG,CAAC,CAAC;QACL,CAAC;QAED,6EAA6E;QAC7E,4EAA4E;QAC5E,qCAAqC;QACrC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAExE,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;QAEnC,qEAAqE;QACrE,6EAA6E;QAC7E,MAAM,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;QAE5E,gGAAgG;QAChG,iGAAiG;QACjG,iGAAiG;QACjG,kGAAkG;QAClG,0FAA0F;QAC1F,iGAAiG;QACjG,iDAAiD;QACjD,MAAM,IAAI,CAAC,8BAA8B,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;QAE5E,6EAA6E;QAC7E,2DAA2D;QAC3D,EAAE;QACF,8FAA8F;QAC9F,wFAAwF;QACxF,2FAA2F;QAC3F,2FAA2F;QAC3F,gGAAgG;QAChG,qFAAqF;QACrF,2FAA2F;QAC3F,4FAA4F;QAC5F,sEAAsE;QACtE,MAAM,aAAa,GAAkD,kCAAkC,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAExI,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC;QAEtF,IAAI,CAAC,QAAQ,CAAC,yBAAyB,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC;QAEhI;;;;;;;;;;;;;;;;;;;;;WAqBG;QACH,MAAM,sBAAsB,GAAG,4BAA4B,CAAC,IAAI,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC,CAAC;QAEvG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,iBAAiB,CACzD,aAAa,EACb,qBAAqB,EACrB,OAAO,EACP,YAAY,EACZ,sBAAsB,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CACzD,CAAC;QAEF,iFAAiF;QACjF,sFAAsF;QACtF,0FAA0F;QAC1F,0FAA0F;QAC1F,6FAA6F;QAC7F,6FAA6F;QAC7F,yEAAyE;QACzE,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAErE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACK,KAAK,CAAC,8BAA8B,CAC1C,SAAyD,EACzD,qBAA4C;QAE5C,IACE,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ;eAC5D,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,sBAAsB,EAChF,CAAC;YACD,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,+BAA+B,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAAC;QACvF,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8FAA8F,EAAE;gBAC/G,kBAAkB,EAAE,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC;gBACxD,mBAAmB,EAAE,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC;aAC3D,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,gBAAgB,CAAC,qBAAqB,CAC/C,MAAM,EACN,gBAAgB,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,EAAE,EAC/F,UAAU,EACV,qBAAqB,CAAC,cAAc,CACrC,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACK,KAAK,CAAC,mBAAmB,CAC/B,QAAgB,EAChB,YAA0B,EAC1B,aAAqB,EACrB,IAAa,EACb,gBAAuC,EACvC,OAA2B,EAC3B,eAAkD;QAElD,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAC3H,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE;gBACxE,sBAAsB,EAAE,2BAA2B,CAAC,iBAAiB;gBACrE,OAAO,EAAE,EAAE,OAAO,EAAE,aAAa,QAAQ,kDAAkD,EAAE,QAAQ,EAAE;aACxG,CAAC,CAAC;QACL,CAAC;QACD,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;QAC9D,MAAM,qBAAqB,GAAG,gBAAgB,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QAC9E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACtC,IAAI,aAAa,KAAK,qBAAqB,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YAClE,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,qBAAqB,EAAE;gBAC9E,sBAAsB,EAAE,2BAA2B,CAAC,UAAU;gBAC9D,OAAO,EAAE,EAAE,OAAO,EAAE,sDAAsD,EAAE,QAAQ,EAAE;aACvF,CAAC,CAAC;QACL,CAAC;QAED,iEAAiE;QACjE,MAAM,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;QAE/E,MAAM,UAAU,GAAG,gCAAgC,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;QAC1G,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,qBAAqB,EAAE;gBAC9E,sBAAsB,EAAE,2BAA2B,CAAC,UAAU;gBAC9D,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE;aAChI,CAAC,CAAC;QACL,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;QACnH,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,qBAAqB,EAAE;gBACjF,sBAAsB,EAAE,2BAA2B,CAAC,aAAa;gBACjE,OAAO,EAAE,EAAE,OAAO,EAAE,qBAAqB,cAAc,CAAC,gBAAgB,oDAAoD,EAAE;aAC/H,CAAC,CAAC;QACL,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,8GAA8G;QAC9G,MAAM,UAAU,GAAG,IAAI,CAAC,sBAAsB,CAAC,eAAe,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;QACtI,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;YACnD,gBAAgB,EAAE,qBAAqB;YACvC,MAAM,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE;YACzE,gBAAgB,EAAE,UAAU,CAAC,IAAI,CAAC,gBAAgB;YAClD,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE;YACxG,SAAS,EAAE,GAAG,MAAM,GAAG,UAAU,EAAE;YACnC,UAAU,EAAE,GAAG,MAAM,GAAG,kBAAkB,EAAE;SAC7C,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,sCAAsC,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,KAAK,SAAS,EAAE,CAAC,CAAC;QACrJ,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,uHAAuH;IAC/G,iBAAiB,CAAC,IAAa,EAAE,YAA0B;QACjE,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,IAAI,EAAE,CAAC;QACzD,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,8BAA8B,EAAE,CAAC,YAAY,CAAC,CAAC;QACxF,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,IAAK,IAAgC,CAAC;YAAE,OAAO,IAAI,CAAC;QACjF,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAA+B,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACK,sBAAsB,CAC5B,eAA+D,EAC/D,YAA0B,EAC1B,SAAiB,EACjB,aAAuC,EACvC,UAA8B,EAC9B,gBAAuC;QAEvC,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,8BAA8B,EAAE,CAAC,YAAY,CAAC,CAAC;QACxF,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,CAAC,gBAAgB,IAAI,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;aACnH,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAuC;YACnD,GAAG,CAAC,gBAAgB,CAAC,YAA8D,IAAI,EAAE,CAAC;YAC1F,GAAG,CAAC,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,yCAAyC,CAAC,gCAAgC,CAAC;gBACvF,iBAAiB,EAAE,IAAI,CAAC,GAAG;gBAC3B,mBAAmB,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;gBAC1C,kBAAkB,EAAE,YAAY;gBAChC,6BAA6B,EAAE,SAAS,IAAI,IAAI;gBAChD,SAAS;gBACT,wBAAwB,EAAE,aAAa,KAAK,qBAAqB,CAAC,MAAM;gBACxE,UAAU,EAAE,KAAK;aAClB,CAAC,CAAC;YACH,IAAI,UAAU,GAAG,KAAK,CAAC;YACvB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,KAAa,EAAE,EAAE;gBACnE,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAAC,UAAU,GAAG,IAAI,CAAC;oBAAC,OAAO,IAAI,KAAK,GAAG,CAAC;gBAAC,CAAC;gBAChG,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,UAAU;gBAAE,OAAO,IAAI,CAAC;QAC/B,CAAC;QACD,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;YAC5E,sBAAsB,EAAE,2BAA2B,CAAC,aAAa;YACjE,OAAO,EAAE,EAAE,OAAO,EAAE,sEAAsE,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE;SACjL,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACK,mBAAmB,CACzB,SAKC,EACD,IAAa,EACb,gBAAuC;QAEvC,MAAM,kBAAkB,GAAG,IAAI,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC;QACrE,MAAM,qBAAqB,GAAG,6BAA6B,CAAC,kBAAkB,CAAC,CAAC;QAEhF,IAAI,qBAAqB,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC7E,CAAC,CAAC,IAA+B;gBACjC,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,kBAAkB,GAAG,IAAI,CAAC,iBAAiB;iBAC9C,wBAAwB,CAAC,SAAS,CAAC,kBAAkC,CAAC;iBACtE,UAAU,CAAC;YACd,OAAO,mCAAmC,CACxC,YAAY,EACZ,SAAkB,EAClB,kBAAkB,EAClB,kBAA2B,CAC5B,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAEvC,IAAI,CAAC;YACH,OAAO,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAChC,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE;oBACzE,sBAAsB,EAAE,2BAA2B,CAAC,qCAAqC;oBACzF,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,OAAO,EAAE;wBACP,OAAO,EAAE,2FAA2F;wBACpG,mBAAmB,EAAE,SAAS,CAAC,mBAAmB;wBAClD,SAAS,EAAE,KAAK,CAAC,MAAM;qBACxB;iBACF,CAAC,CAAC;YACL,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,yBAAyB,CAAC,SAA4E;QAC5G,OAAO,4BAA4B,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;IAEO,aAAa,CAAC,QAAgB;QACpC,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;QACjE,IAAI,cAAc,IAAI,CAAC,IAAI,cAAc,GAAG,uBAAuB,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC9F,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE;gBAClE,sBAAsB,EAAE,2BAA2B,CAAC,iBAAiB;gBACrE,OAAO,EAAE,EAAE,OAAO,EAAE,4BAA4B,QAAQ,2BAA2B,uBAAuB,cAAc,EAAE,QAAQ,EAAE;aACrI,CAAC,CAAC;QACL,CAAC;QACD,OAAO;YACL,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAiB;YAC/D,mBAAmB,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc,GAAG,uBAAuB,CAAC,MAAM,CAAC;SACrF,CAAC;IACJ,CAAC;CACF,CAAA;AA3dY,uBAAuB;IADnC,UAAU,EAAE;IAKR,WAAA,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;IACjC,WAAA,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,CAAA;IAC9C,WAAA,MAAM,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;IACzC,WAAA,MAAM,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAA;IAChD,WAAA,MAAM,CAAC,kBAAkB,CAAC,8BAA8B,CAAC,CAAA;IACzD,WAAA,MAAM,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAA;IAClD,WAAA,MAAM,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAA;IACjD,WAAA,MAAM,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;IAC3C,WAAA,MAAM,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAA;+CAP8B,0BAA0B;QAChC,4BAA4B;QACtB,4BAA4B;QACd,qCAAqC;QAC1C,+BAA+B;QAC3B,6BAA6B;QACzC,uBAAuB;QAChB,uBAAuB;GAZvG,uBAAuB,CA2dnC","sourcesContent":["import { injectable, inject } from 'inversify';\nimport {\n  ResourceType,\n  ResourceOperationVariantType,\n  ResourceConfiguration_OperationPath,\n  ResourcesConfig_OperationPathUtils,\n  CoreResourceOperation,\n  ErrorType,\n  ErrorCustomMessageReference,\n  BackendApiType,\n  MAIN_API_BASE_PATH,\n  FileUploadGrantMintRequestSchema,\n  ResourcesConfigOperationsUrlsBuilderUtils,\n  type ResourcePrimaryScope,\n  type ResourceConfiguration_Operation,\n  type FileUploadGrantOperation,\n} from '@wildo-ai/saas-models';\nimport { z } from 'zod';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { FileUploadGrantBackendService } from '~wildo-backend-lib/files/services/file-upload-grant.backend.service';\nimport { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport { MCP_UPLOAD_GRANT_TOOL_MARKER } from '~wildo-backend-lib/mcp/models/mcp-tool.backend.schemas';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';\nimport { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';\nimport { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';\nimport { toResponseSafeToolOutput } from '~wildo-backend-lib/base-classes/services/controllers/utils/operation-response-serializer.backend.utils';\nimport { normalizeCollectionQueryRequestData } from '~wildo-backend-lib/base-classes/services/controllers/controller-resource.backend.service';\nimport { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport { RateLimitBackendService } from '~wildo-backend-lib/errors/services/rate-limit.backend.service';\nimport { resolveDeclaredPolicySubjectKey } from '~wildo-backend-lib/security/authentications/services/utils/external-turn-rate-limit.backend.utils';\nimport {\n  McpToolAdapterBackendService,\n  mcpReachableScopesForPrincipal,\n  mcpPrincipalForAuthenticatedCaller,\n  resolveEffectiveMcpOperation,\n  isCollectionQueryMcpOperation,\n} from '~wildo-backend-lib/mcp/services/mcp-tool-adapter.backend.service';\nimport {\n  McpToolDescriptor,\n  McpToolAdapterBuildOptions,\n  MCP_TOOL_NAME_SEPARATOR,\n} from '~wildo-backend-lib/mcp/models/mcp-tool.backend.schemas';\n\n/**\n * Per-call options for {@link McpServerBackendService.callTool}.\n */\nexport interface McpCallToolOptions {\n  /**\n   * Target resource id for resource-specific operations (READ / UPDATE / DELETE\n   * and instance-scoped custom operations). Omit for collection operations\n   * (CREATE / LIST / SEARCH / COUNT), which authorize on roles + parent scope only.\n   */\n  resourceId?: string;\n  /**\n   * The NAMED MCP server instance this call arrived on (R-2), or omitted for the default `/mcp`\n   * server. MUST mirror the transport's route: the exposability gate below re-resolves the tool\n   * against this instance, so a tool curated onto another server is NOT callable here even by name.\n   */\n  instanceRef?: string;\n}\n\n/**\n * Result of a successful `tools/call`. `result` is the operation output projected\n * through the operation's response DTO (backend-only/secret fields stripped, dates\n * JSON-normalized — see `callTool`), returned WITHOUT MCP `content` framing: the\n * `{ content: [...], isError }` envelope is applied by the transport\n * ({@link MCPControllerBackendService.handleToolsCall}). Keeping this service\n * transport-agnostic lets the same `callTool` back another transport unchanged.\n */\nexport interface McpCallToolResult {\n  toolName: string;\n  result: unknown;\n}\n\n/**\n * The MCP server core: lists resource-operation tools and executes them against\n * the SERVICE layer with per-call authorization. Transport-agnostic — the\n * JSON-RPC / Streamable-HTTP wire layer + OAuth 2.1 resource-server auth\n * (RFC 9728 metadata, RFC 8707 audience validation) live in\n * {@link MCPControllerBackendService}; this core carries no wire concern so the\n * same `listTools`/`callTool` can back another transport unchanged.\n *\n * # Boundaries\n *\n * - `listTools()` delegates to {@link McpToolAdapterBackendService}.\n * - `callTool()` resolves the target operation, RE-RUNS `authorizeInController`\n *   against the caller's execution context (fail-closed), enforces the operation's\n *   own declared `rateLimit` policy (see `assertOperationRateLimitPolicy`), then\n *   invokes the service pipeline DIRECTLY via\n *   {@link ServicesRegistryHandlerBackendService} (never re-HTTP). The service\n *   pipeline enforces `requiredFeatures` / `enabledCondition` downstream.\n * - RATE LIMITING on this plane is now TWO guards, and they answer different questions:\n *   the transport applies the framework's blanket per-principal `tools/call` cap\n *   (`MCP_EXTERNAL_CALL_RATE_MAX`, an abuse throttle nobody declared, fails OPEN), and\n *   THIS service applies the operation's own AUTHORED `rateLimit` (a statement the\n *   application made about that endpoint, enforced identically to the HTTP seam). The\n *   second one lives here rather than in the transport for the same reason\n *   `authorizeInController` does: it is a property of the OPERATION, so a second\n *   transport backed by this core must inherit it rather than re-implement it.\n *   (Historical note: the block that stood here recorded the per-operation policy as a\n *   KNOWN GAP whose \"planned fix is a per-principal quota shared with the A2A dispatch\n *   surface\". That per-principal quota SHIPPED — `assertExternalTurnWithinRate`, used by\n *   both `MCPControllerBackendService` and `A2ABackendService` — and the comment was\n *   never updated, so it read as wholly open when only its per-operation half was.)\n * - Server-initiated streaming (SSE / notifications / progress) is intentionally\n *   absent: every exposed operation is synchronous request/response, for which a\n *   single JSON response is Streamable-HTTP-compliant (Item 1, deferred).\n */\n/**\n * Operations whose RESULT is the paginated `{ data, pagination }` envelope, for OUTPUT.\n *\n * Deliberately NOT the same set as {@link isCollectionQueryOperation}: `COUNT` takes the collection\n * argument envelope but RETURNS A SCALAR, so asking the repository to wrap it would hand back a\n * shape its response DTO does not declare — trading one contract mismatch for another.\n *\n * Mirrors `needsPagination` in `ControllerResourceBackendService`, which is where this decision has\n * always been made for the HTTP surface. The two must agree: they select the shape the SAME response\n * DTO is asked to validate.\n */\nfunction isPaginationWrappedOperation(effectiveOperation: string): boolean {\n  return effectiveOperation === CoreResourceOperation.LIST\n    || effectiveOperation === CoreResourceOperation.SEARCH;\n}\n\n@injectable()\nexport class McpServerBackendService {\n  protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) protected readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) protected readonly errorBuilder: ErrorBuilderBackendService,\n    @inject(SAAS_SERVICE_TYPES.McpToolAdapter) protected readonly toolAdapter: McpToolAdapterBackendService,\n    @inject(SAAS_SERVICE_TYPES.AuthorizationsService) protected readonly authorizer: AuthorizationsBackendService,\n    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) protected readonly servicesHandler: ServicesRegistryHandlerBackendService,\n    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) protected readonly resourcesRegistry: ResourcesRegistryBackendService,\n    @inject(SAAS_SERVICE_TYPES.FileUploadGrantService) protected readonly fileUploadGrantService: FileUploadGrantBackendService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService) protected readonly appConfigService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.RateLimitBackendService) protected readonly rateLimitService: RateLimitBackendService,\n  ) {\n    this.logDebug = this.logger.debugByType('McpServerBackendService');\n    this.logger.setDebugTypeLogging('McpServerBackendService', false);\n  }\n\n  /**\n   * Return the exposed tool descriptors for the caller's reachable scopes (`options.reachableScopes`).\n   * PROGRESSIVE principal-awareness (C): a caller presenting a valid Bearer bound to this endpoint\n   * passes its principal's scopes, so a user-delegated caller additionally sees its USER_SELF tools.\n   * Omitting the scopes yields the MACHINE catalog; an ANONYMOUS caller passes an EMPTY set and the\n   * transport challenges it rather than serving the empty page. Authorization is still enforced\n   * fail-closed at `callTool` time — the catalog is a discovery aid, never an authorization grant.\n   */\n  public listTools(options: McpToolAdapterBuildOptions = {}): McpToolDescriptor[] {\n    return this.toolAdapter.buildToolDescriptors(options);\n  }\n\n  /**\n   * Execute one tool: resolve → authorize (fail-closed) → dispatch to the service layer.\n   *\n   * @param toolName - `<resourceIdentifier>__<operationIdentifier>`.\n   * @param args - the tool arguments (the operation request body).\n   * @param executionContext - the caller's context (a machine principal for api-key\n   *        / client-credentials callers; a user-delegated context once OIDC lands).\n   * @param options - per-call options ({@link McpCallToolOptions}).\n   * @throws AUTHORIZATION when the principal is not permitted to run the operation.\n   * @throws NOT_FOUND when the tool name does not map to an exposable operation.\n   */\n  public async callTool(\n    toolName: string,\n    args: unknown,\n    executionContext: ExecutionContext<any>,\n    options: McpCallToolOptions = {},\n  ): Promise<McpCallToolResult> {\n    const { resourceType, operationIdentifier } = this.parseToolName(toolName);\n\n    // Single source of exposability truth: the adapter decides whether this resource+operation is a\n    // valid, default URL-bearing tool REACHABLE BY THIS CALLER. Progressive principal-awareness — a\n    // user-delegated principal (USER_REQUEST, carries a `userId`) reaches USER_SELF operations; a\n    // machine principal reaches ORG/APP only. Rejecting here (before authorization) prevents a crafted\n    // name from reaching a scope the caller cannot use (e.g. a machine hitting USER_SELF → always 403).\n    // Derived from the SAME source `tools/list` filters on, so advertise ≡ callable per principal.\n    // R-2: also gated on the server INSTANCE the call arrived on, so `(principal, instance)` together\n    // decide callability — the same pair `tools/list` filters on.\n    // Post-authentication by construction: `callTool` is only reached with a validated token.\n    const reachableScopes = mcpReachableScopesForPrincipal(mcpPrincipalForAuthenticatedCaller(executionContext.isUserExecution()));\n\n    // Issue #312, D11: a DERIVED upload-grant tool mints a grant instead of dispatching an operation.\n    // It resolves its PARENT through the same adapter gate (exposure, instance, scope inherited), is\n    // authorized exactly as the parent would be, then calls the ONE mint function the REST door calls.\n    if (operationIdentifier.includes(MCP_UPLOAD_GRANT_TOOL_MARKER)) {\n      return this.callUploadGrantTool(toolName, resourceType, operationIdentifier, args, executionContext, options, reachableScopes);\n    }\n\n    const operation = this.toolAdapter.resolveExposableOperation(resourceType, operationIdentifier, reachableScopes, options.instanceRef);\n    if (!operation) {\n      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n        customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND,\n        context: { message: `MCP tool \"${toolName}\" does not map to an exposable resource operation`, toolName },\n      });\n    }\n\n    // Bind the resolved operation onto the caller's context (preserves principal\n    // identity + roles) so the authorizer and the service pipeline both see the\n    // operation actually being executed.\n    const boundExecutionContext = executionContext.withOperation(operation);\n\n    const idOrIds = options.resourceId;\n\n    // Fail-closed per-operation authorization: reads `operation.roles` +\n    // `executionContext.initiatorRoles` / scope. Throws AUTHORIZATION on denial.\n    await this.authorizer.authorizeInController(idOrIds, boundExecutionContext);\n\n    // The operation's OWN declared request budget. AFTER authorization on purpose: a caller who may\n    // not run the operation at all must be refused with AUTHORIZATION rather than told how much of a\n    // budget they have — and must not consume a slot of a budget that is not theirs, which would let\n    // an unauthorized caller exhaust an authorized one's quota. (The HTTP seam orders these the other\n    // way round because it has no choice: `checkPolicyForVariant` runs pre-flight, before the\n    // execution context that authorization needs even exists. Here the identity is already resolved,\n    // so the safer order is available and is taken.)\n    await this.assertOperationRateLimitPolicy(operation, boundExecutionContext);\n\n    // Dispatch to the service layer directly (NOT re-HTTP). The service pipeline\n    // enforces enabledCondition / requiredFeatures downstream.\n    //\n    // Dispatch the EXACT operation we resolved + authorized + advertised (the URL-bearing default\n    // from `resolveExposableOperation`), via `extractOperationPath`. We deliberately do NOT\n    // re-resolve through `getServiceOperationPathDefault`: for a resource that declares BOTH a\n    // URL-bearing default AND an INTERNAL_CALL default for the same operation identifier, that\n    // helper PREFERS the INTERNAL_CALL variant — which would execute a different variant (different\n    // `requestDto` validating `args`, different side effects / custom-impl) than the one\n    // `authorizeInController` just checked and than the `inputSchema` advertised to the agent.\n    // Using the resolved operation's own path mirrors how the HTTP controllers dispatch the URL\n    // operation and keeps authorize ≡ advertise ≡ execute on one variant.\n    const operationPath: ResourceConfiguration_OperationPath<any, any> = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);\n\n    const dispatchArgs = this.toDispatchArguments(operation, args, boundExecutionContext);\n\n    this.logDebug('Executing MCP tool call', { toolName, resourceType, operationIdentifier, hasResourceId: idOrIds !== undefined });\n\n    /**\n     * Request the pagination WRAPPER for collection operations, exactly as the HTTP controller does.\n     *\n     * The repository's `list` returns a BARE ARRAY unless the caller asks for the envelope\n     * (`options.paginated`), and the decision to ask is made in `ControllerResourceBackendService`:\n     * `needsPagination = LIST || SEARCH` → `{ paginated: true }`. That is a CONTROLLER-tier\n     * decision, and this path does not go through the controller — so `tools/call` dispatched a\n     * paginated LIST without ever requesting pagination, the repository returned a bare array, and\n     * the operation's RESPONSE DTO (which for a paginated list declares `{ data, pagination }`)\n     * rejected it. Every paginated `*__list` tool answered `-32603` with\n     * `expected array, received undefined` at `data`.\n     *\n     * Two things hid it. `*__search` was unaffected — the search path builds its own envelope — and\n     * the one LIST that worked (`todosRelationships__list`) is UNPAGINATED, so a bare array is\n     * exactly what its response DTO declares. So the failure looked resource-specific when it was\n     * operation-wide.\n     *\n     * This is the OUTPUT half of the defect family the input normalisation already fixed on\n     * 2026-08-01: \"the advertised contract is not the enforced contract\". `tools/list` advertises a\n     * paginated collection envelope because the response DTO says so; the dispatch has to request\n     * the shape that DTO describes, or the two tiers disagree about what the operation returns.\n     */\n    const needsPaginationWrapper = isPaginationWrappedOperation(this.resolveEffectiveOperation(operation));\n\n    const result = await this.servicesHandler.doByOperationPath(\n      operationPath,\n      boundExecutionContext,\n      idOrIds,\n      dispatchArgs,\n      needsPaginationWrapper ? { paginated: true } : undefined,\n    );\n\n    // Project the raw service result through the operation's RESPONSE DTO — the SAME\n    // output-serialization boundary the HTTP controller (`sendResponse`) and the A2A tool\n    // path use — BEFORE it crosses to the external MCP agent. `doByOperationPath` returns the\n    // internal DTO, which still carries `.isBackendOnly()` / write-only-secret fields and raw\n    // `Date`/`ObjectId` instances; returning it verbatim would leak backend-only/secret material\n    // into the agent's model context. `toResponseSafeToolOutput` strips + JSON-normalizes so the\n    // MCP tool result is byte-identical to what a REST client would receive.\n    const safeResult = await toResponseSafeToolOutput(operation, result);\n\n    return { toolName, result: safeResult };\n  }\n\n  /**\n   * Enforce the resolved operation's OWN `rateLimit?` policy on the tool plane.\n   *\n   * ## What was broken\n   *\n   * `rateLimit?` is authored on an `API_CALL` / `API_CALL_WITH_CALLBACK` variant and was enforced\n   * by exactly one consumer — `RateLimitBackendService.checkPolicyForVariant`, called from the\n   * resource controller's HTTP pre-flight. `callTool` dispatches the SAME operation through the\n   * SAME service pipeline while bypassing Express entirely, so the identical operation was\n   * throttled over REST and unthrottled as a tool. An application that declared a budget on an\n   * endpoint got one; an agent asked for the same endpoint by its tool name and got none.\n   *\n   * ## Subject: the CREDENTIAL, not the IP and not the tenant\n   *\n   * See {@link resolveDeclaredPolicySubjectKey} for the full argument. In short: the HTTP seam\n   * keys on the source IP because at its pre-flight moment no identity exists yet, so `5/min` has\n   * always meant \"5/min per CLIENT\". On this plane the client is the credential the agent\n   * presented — a server-verified field of the execution context, never anything the model\n   * supplied. Keying on the tenant instead would make the same authored number several times\n   * stricter here than over REST for any tenant running more than one agent.\n   *\n   * ## Scope: a SEPARATE bucket from the REST route, deliberately\n   *\n   * The key is namespaced `mcp:resource:<resource>:<operation>` rather than sharing the HTTP\n   * seam's `resource:<resource>:<operation>`. Sharing would be incoherent — the two seams count\n   * different SUBJECTS (an IP and a credential), so one bucket would mix two identity spaces and\n   * let a browser's traffic spend an agent's budget. Per-plane-per-client is the faithful\n   * extension of a policy that was already per-client rather than a global cap.\n   *\n   * ## Not applied to the derived upload-grant tool\n   *\n   * `callUploadGrantTool` MINTS a grant; it does not dispatch the parent operation. Charging the\n   * parent's budget there would spend two slots for one upload (mint + the upload itself, which\n   * traverses the real HTTP route and meets `checkPolicyForVariant`) while a REST client spends\n   * one — the declared number would mean something different depending on how the caller got the\n   * URL. It is left uncharged for that reason, not by omission.\n   *\n   * ## Postures\n   *\n   * - **No declared policy, or a non-HTTP variant** → no-op, zero Redis traffic. Mirrors\n   *   `checkPolicyForVariant`'s two early returns exactly; the variant guard is defensive, since\n   *   `resolveExposableOperation` only ever yields a URL-bearing default.\n   * - **Unkeyable subject** → not enforced, logged. Structurally unreachable: `callTool` is only\n   *   reached post-authentication, and `ExecutionContext`'s own constructor rejects an\n   *   authenticated principal carrying no identity field. It is not \"unbounded\" either — the\n   *   transport's blanket per-principal cap is the backstop, and it declines on exactly the same\n   *   input. Refusing a well-formed call here instead would invent an outage out of a branch that\n   *   cannot happen.\n   * - **Limiter outage** → propagates, as it does over HTTP for the same declared policy. An\n   *   authored budget must not quietly become \"unlimited\" on one plane while it is a 500 on the\n   *   other.\n   */\n  private async assertOperationRateLimitPolicy(\n    operation: ResourceConfiguration_Operation<any, any, any>,\n    boundExecutionContext: ExecutionContext<any>,\n  ): Promise<void> {\n    if (\n      operation.variantType !== ResourceOperationVariantType.API_CALL\n      && operation.variantType !== ResourceOperationVariantType.API_CALL_WITH_CALLBACK\n    ) {\n      return;\n    }\n    const policy = operation.rateLimit;\n    if (!policy) {\n      return;\n    }\n\n    const subjectKey = resolveDeclaredPolicySubjectKey(boundExecutionContext.initiatorIds);\n    if (!subjectKey) {\n      this.logger.warn('[mcp] declared rateLimit not enforced — the authenticated caller carries no keyable identity', {\n        resourceIdentifier: String(operation.resourceIdentifier),\n        operationIdentifier: String(operation.operationIdentifier),\n      });\n      return;\n    }\n\n    await this.rateLimitService.checkPolicyForSubject(\n      policy,\n      `mcp:resource:${String(operation.resourceIdentifier)}:${String(operation.operationIdentifier)}`,\n      subjectKey,\n      boundExecutionContext.organizationId,\n    );\n  }\n\n  /**\n   * Execute a derived upload-grant tool (issue #312, D11).\n   *\n   * Authorization is the PARENT's: the caller's context is bound to the parent operation and\n   * `authorizeInController` runs on it with the same `resourceId` the parent would take — so minting\n   * requires exactly the authority uploading would, which is the invariant the REST door gets from\n   * sharing the upload middleware. The upload URL is built from the parent's own route pattern with\n   * the parameters the context and the call supply, and the API origin comes from CONFIGURATION,\n   * never from a request header.\n   */\n  private async callUploadGrantTool(\n    toolName: string,\n    resourceType: ResourceType,\n    operationPart: string,\n    args: unknown,\n    executionContext: ExecutionContext<any>,\n    options: McpCallToolOptions,\n    reachableScopes: ReadonlySet<ResourcePrimaryScope>,\n  ): Promise<McpCallToolResult> {\n    const derived = this.toolAdapter.resolveUploadGrantTool(resourceType, operationPart, reachableScopes, options.instanceRef);\n    if (!derived) {\n      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n        customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND,\n        context: { message: `MCP tool \"${toolName}\" does not map to an exposable upload-grant tool`, toolName },\n      });\n    }\n    const { parentOperation, fieldName, operationKind } = derived;\n    const boundExecutionContext = executionContext.withOperation(parentOperation);\n    const resourceId = options.resourceId;\n    if (operationKind === CoreResourceOperation.UPDATE && !resourceId) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, boundExecutionContext, {\n        customMessageReference: ErrorCustomMessageReference.VALIDATION,\n        context: { message: 'An upload grant for an UPDATE requires the record id', toolName },\n      });\n    }\n\n    // Same gate, same order, same arguments as the parent operation.\n    await this.authorizer.authorizeInController(resourceId, boundExecutionContext);\n\n    const parsedArgs = FileUploadGrantMintRequestSchema.safeParse(this.withoutInstanceId(args, resourceType));\n    if (!parsedArgs.success) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, boundExecutionContext, {\n        customMessageReference: ErrorCustomMessageReference.VALIDATION,\n        context: { toolName, errors: parsedArgs.error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message })) },\n      });\n    }\n\n    const apiPublicUrl = this.appConfigService.config.runtime?.endPoints?.[BackendApiType.MAIN_BACKEND_API]?.publicUrl;\n    if (!apiPublicUrl) {\n      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, boundExecutionContext, {\n        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n        context: { message: `runtime.endPoints.${BackendApiType.MAIN_BACKEND_API}.publicUrl is required to mint a file upload grant` },\n      });\n    }\n    const origin = apiPublicUrl.replace(/\\/+$/, '');\n    // Scope ids come from the CALLER's context: binding an operation onto a context never changes who is calling.\n    const uploadPath = this.resolveUploadRoutePath(parentOperation, resourceType, fieldName, operationKind, resourceId, executionContext);\n    const grant = await this.fileUploadGrantService.mint({\n      executionContext: boundExecutionContext,\n      target: { resourceType, fieldName, operation: operationKind, resourceId },\n      expiresInMinutes: parsedArgs.data.expiresInMinutes,\n      declared: { name: parsedArgs.data.name, mimeType: parsedArgs.data.mimeType, size: parsedArgs.data.size },\n      uploadUrl: `${origin}${uploadPath}`,\n      apiBaseUrl: `${origin}${MAIN_API_BASE_PATH}`,\n    });\n    this.logDebug('Executing MCP upload-grant tool call', { toolName, resourceType, fieldName, operationKind, hasResourceId: resourceId !== undefined });\n    return { toolName, result: grant };\n  }\n\n  /** The tool arguments minus the resource's own id, which the transport already split out into `options.resourceId`. */\n  private withoutInstanceId(args: unknown, resourceType: ResourceType): unknown {\n    if (!args || typeof args !== 'object') return args ?? {};\n    const selfField = this.resourcesRegistry.getAllResourceFieldIdentifiers()[resourceType];\n    if (!selfField || !(selfField in (args as Record<string, unknown>))) return args;\n    const { [selfField]: _dropped, ...rest } = args as Record<string, unknown>;\n    return rest;\n  }\n\n  /**\n   * The concrete upload-route PATH (mount prefix included) for one file field of the parent\n   * operation, from the parent's own route patterns — the same builder the resource controller used\n   * to REGISTER the route, so the grant's `uploadUrl` is a route that exists.\n   *\n   * A parent can carry several patterns (one per parent-resource combination); the one chosen is the\n   * first whose every `{param}` the call can supply: the resource's own id from `resourceId`, and scope\n   * / parent ids from the context's `initiatorIds`. Patterns are tried shortest first, so the\n   * primary-scope form wins over a nested FK form the MCP call cannot address anyway.\n   */\n  private resolveUploadRoutePath(\n    parentOperation: ResourceConfiguration_Operation<any, any, any>,\n    resourceType: ResourceType,\n    fieldName: string,\n    operationKind: FileUploadGrantOperation,\n    resourceId: string | undefined,\n    executionContext: ExecutionContext<any>,\n  ): string {\n    const selfField = this.resourcesRegistry.getAllResourceFieldIdentifiers()[resourceType];\n    const initiatorInfos = [...(('initiatorInfos' in parentOperation ? parentOperation.initiatorInfos : undefined) ?? [])]\n      .sort((a, b) => (a.parameters?.length ?? 0) - (b.parameters?.length ?? 0));\n    const supplied: Record<string, string | undefined> = {\n      ...(executionContext.initiatorIds as Record<string, string | undefined> | undefined ?? {}),\n      ...(selfField && resourceId ? { [selfField]: resourceId } : {}),\n    };\n    for (const info of initiatorInfos) {\n      const route = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({\n        operationRouteUrl: info.url,\n        operationParameters: info.parameters ?? [],\n        targetResourceType: resourceType,\n        targetResourceFieldIdentifier: selfField ?? 'id',\n        fieldName,\n        requiresTargetResourceId: operationKind === CoreResourceOperation.UPDATE,\n        isFrontend: false,\n      });\n      let unresolved = false;\n      const path = route.url.replace(/\\{([^}]+)\\}/g, (_m, param: string) => {\n        const value = supplied[param];\n        if (typeof value !== 'string' || value.length === 0) { unresolved = true; return `{${param}}`; }\n        return encodeURIComponent(value);\n      });\n      if (!unresolved) return path;\n    }\n    throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n      customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n      context: { message: 'No upload route of this operation can be addressed from the MCP call', resourceType, fieldName, operationKind, patterns: initiatorInfos.map((i) => i.url) },\n    });\n  }\n\n  /**\n   * Split `<resourceIdentifier>__<operationIdentifier>` on the FIRST double\n   * underscore. Resource identifiers use single underscores only, so the first\n   * `__` unambiguously delimits the resource from the operation.\n   */\n  /**\n   * Bring the agent's raw `arguments` onto the SAME input contract the HTTP controller produces\n   * before dispatch. Added 2026-08-01; until then `tools/call` passed `args` through untouched.\n   *\n   * Two distinct defects that fixed, both of the \"advertised contract is not the enforced\n   * contract\" family:\n   *\n   *  1. **Collection tools silently ignored the agent's filter.** `tools/list` advertises an\n   *     `inputSchema` derived from the operation's `requestDto`, which for LIST / SEARCH is keyed\n   *     `{ filters, pagination, sorting }`. The service reads `{ filter, page, limit, sort,\n   *     searchQuery }`. The HTTP controller bridges the two; MCP did not, so an agent that\n   *     followed the schema it was given received the UNFILTERED collection while believing it was\n   *     filtered — the worst shape for an LLM caller, which then reasons over the wrong rows.\n   *     {@link normalizeCollectionQueryRequestData} is now the single authority both surfaces use,\n   *     and it accepts either vocabulary. It also carries the filter ALLOW-LIST, which matters\n   *     here: the repository's `sanitizeRequestFilter` returns the filter UNCHANGED when an\n   *     operation declares no `filterFields`, so for a surface with no strict DTO parse in front\n   *     of it this is the layer that stops an arbitrary key reaching the database.\n   *  2. **The published request contract was not enforced.** Every other operation now gets the\n   *     controller's strict `requestDto.parse`, so a key the tool never advertised is dropped at\n   *     the boundary that advertised it, rather than three layers away. Writes were already safe —\n   *     the repository re-parses against the same DTO\n   *     (`repositories-registry-handler.backend.service.ts`) — but relying on a distant guard for\n   *     an external protocol surface is defence by coincidence: nothing tells a future refactor of\n   *     that method that MCP depends on it.\n   *\n   * Parse failures are deliberately NOT swallowed. An agent that sends a malformed argument should\n   * be told, so the model can correct itself; silently dropping it teaches the model nothing and\n   * leaves it reasoning about an operation it did not actually perform.\n   */\n  private toDispatchArguments(\n    operation: {\n      requestDto?: z.ZodTypeAny;\n      resourceOperationLike?: unknown;\n      operationIdentifier: unknown;\n      resourceIdentifier: unknown;\n    },\n    args: unknown,\n    executionContext: ExecutionContext<any>,\n  ): unknown {\n    const effectiveOperation = this.resolveEffectiveOperation(operation);\n    const isCollectionOperation = isCollectionQueryMcpOperation(effectiveOperation);\n\n    if (isCollectionOperation) {\n      const rawArguments = (args && typeof args === 'object' && !Array.isArray(args))\n        ? args as Record<string, unknown>\n        : {};\n      const resourceOperations = this.resourcesRegistry\n        .getResourceConfiguration(operation.resourceIdentifier as ResourceType)\n        .operations;\n      return normalizeCollectionQueryRequestData(\n        rawArguments,\n        operation as never,\n        effectiveOperation,\n        resourceOperations as never,\n      );\n    }\n\n    if (!operation.requestDto) return args;\n\n    try {\n      return operation.requestDto.parse(args);\n    } catch (error) {\n      if (error instanceof z.ZodError) {\n        throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n          customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,\n          stack: error.stack,\n          context: {\n            message: 'MCP tool arguments do not satisfy the operation request contract advertised by tools/list',\n            operationIdentifier: operation.operationIdentifier,\n            zodIssues: error.issues,\n          },\n        });\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * The operation this tool really performs — a custom operation declares what it behaves LIKE via\n   * `resourceOperationLike`, and both the input normalisation and the output envelope must key on\n   * the same answer. Derived once here because they previously derived it separately, and a\n   * custom LIST-like operation that only one of them recognised would be normalised as a collection\n   * on the way in and dispatched without pagination on the way out.\n   */\n  private resolveEffectiveOperation(operation: { resourceOperationLike?: unknown; operationIdentifier: unknown }): string {\n    return resolveEffectiveMcpOperation(operation);\n  }\n\n  private parseToolName(toolName: string): { resourceType: ResourceType; operationIdentifier: string } {\n    const separatorIndex = toolName.indexOf(MCP_TOOL_NAME_SEPARATOR);\n    if (separatorIndex <= 0 || separatorIndex + MCP_TOOL_NAME_SEPARATOR.length >= toolName.length) {\n      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {\n        customMessageReference: ErrorCustomMessageReference.SERVICE_NOT_FOUND,\n        context: { message: `Malformed MCP tool name \"${toolName}\" — expected \"<resource>${MCP_TOOL_NAME_SEPARATOR}<operation>\"`, toolName },\n      });\n    }\n    return {\n      resourceType: toolName.slice(0, separatorIndex) as ResourceType,\n      operationIdentifier: toolName.slice(separatorIndex + MCP_TOOL_NAME_SEPARATOR.length),\n    };\n  }\n}\n"]}

package/dist/esm/mcp/services/mcp-tool-adapter.backend.service.d.ts

@@ -1,4 +1,5 @@
-import { ResourceType, ResourceConfiguration_Operation, ResourcePrimaryScope } from '@wildo-ai/saas-models';
+import { ResourceType, ResourceConfiguration_Operation, ResourcePrimaryScope, type FileUploadGrantOperation } from '@wildo-ai/saas-models';
+import type { FileFieldDetectionBackendService } from '../../files/services/file-field-detection.backend.service';
 import type { LoggerService } from '../../monitoring/logger/services/logger.service';
 import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service';
 import { McpToolDescriptor, McpToolAdapterBuildOptions } from '../../mcp/models/mcp-tool.backend.schemas';
@@ -60,6 +61,12 @@ export declare function resolveEffectiveMcpOperation(operation: {
  * would ask the repository to wrap a scalar in a pagination envelope its response DTO never declares.
  */
 export declare function isCollectionQueryMcpOperation(effectiveOperation: string): boolean;
+/**
+ * The kebab-case segment a file field gets in its upload ROUTE (`…/files/<segment>`) — the same
+ * transform `ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation` applies, so
+ * a derived tool name and the route it mints for agree by construction.
+ */
+export declare function fileFieldRouteSegment(fieldName: string): string;
 /**
  * Adapts registered resource operations into MCP tool descriptors.
  *
@@ -100,8 +107,24 @@ export declare function isCollectionQueryMcpOperation(effectiveOperation: string
 export declare class McpToolAdapterBackendService {
     protected readonly logger: LoggerService;
     protected readonly resourcesRegistry: ResourcesRegistryBackendService;
+    /**
+     * Detects the user-uploadable file fields a resource carries — the same detector the resource
+     * controller uses to REGISTER upload routes, so a derived upload-grant tool is advertised for
+     * exactly the fields that have a route. Optional only so harnesses that never look at file
+     * fields can construct the adapter; the container always binds it, and without it no derived
+     * tool is advertised or callable (fail-closed, logged once).
+     */
+    protected readonly fileFieldDetection?: FileFieldDetectionBackendService;
     protected logDebug: (message: string, context?: Record<string, unknown>) => void;
-    constructor(logger: LoggerService, resourcesRegistry: ResourcesRegistryBackendService);
+    constructor(logger: LoggerService, resourcesRegistry: ResourcesRegistryBackendService, 
+    /**
+     * Detects the user-uploadable file fields a resource carries — the same detector the resource
+     * controller uses to REGISTER upload routes, so a derived upload-grant tool is advertised for
+     * exactly the fields that have a route. Optional only so harnesses that never look at file
+     * fields can construct the adapter; the container always binds it, and without it no derived
+     * tool is advertised or callable (fail-closed, logged once).
+     */
+    fileFieldDetection?: FileFieldDetectionBackendService);
     /**
      * Build the MCP tool descriptor set for the requested resources, filtered to the caller's reachable
      * scopes (`options.reachableScopes`, default = machine-reachable ORG/APP). A user-delegated caller
@@ -195,6 +218,45 @@ export declare class McpToolAdapterBackendService {
      * build their tool descriptors, sorted by operation identifier.
      */
     private buildResourceToolDescriptors;
+    /**
+     * The user-uploadable file fields a CREATE / UPDATE operation carries; `[]` for every other operation
+     * (a READ or DELETE never receives a file) and whenever no detector is bound.
+     */
+    private uploadableFileFieldsFor;
+    private warnedNoFileFieldDetection;
+    /**
+     * Debug, not warn: the container always binds the detector, so in production this never fires; where
+     * it does fire — a harness that constructs the adapter bare — a warning would be noise about a
+     * dependency the harness deliberately left out.
+     */
+    private warnOnceNoFileFieldDetection;
+    /**
+     * Append, to the PARENT tool's description, where each file field's `fileId` comes from. Engine-
+     * appended for the same reason as the envelope note: how a file reaches a resource is a framework
+     * fact, not app prose, and an agent reading `attachments.fileId: string` would otherwise have no way
+     * to learn that the value cannot be invented.
+     */
+    private withUploadGrantNote;
+    /**
+     * The derived upload-grant descriptor. Its arguments are the parent's instance id (UPDATE only —
+     * the same id the parent advertises, split out by the transport exactly the same way) and an
+     * optional lifetime bounded by the engine ceiling. Nothing about the file itself: bytes never
+     * travel through a tool call, which is the whole reason this tool exists.
+     */
+    private buildUploadGrantDescriptor;
+    /**
+     * Resolve a DERIVED upload-grant tool back to its parent operation and file field — the callable
+     * half of `buildToolDescriptors`' derived emission, kept symmetric with it: the parent is resolved
+     * through `resolveExposableOperation` (so exposure, instance and principal-scope gating are
+     * inherited verbatim), the field must be one of the resource's uploadable file fields, and the
+     * composed name must satisfy the naming guidance. `undefined` for anything that is not a well-formed,
+     * advertised derived tool.
+     */
+    resolveUploadGrantTool(resourceType: ResourceType, operationPart: string, reachableScopes: ReadonlySet<ResourcePrimaryScope>, instanceRef?: string): {
+        parentOperation: ResourceConfiguration_Operation<any, any, any>;
+        fieldName: string;
+        operationKind: FileUploadGrantOperation;
+    } | undefined;
     /** `<resourceIdentifier>__<operationIdentifier>`. */
     private buildToolName;
     /**

package/dist/esm/mcp/services/mcp-tool-adapter.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-tool-adapter.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/mcp/services/mcp-tool-adapter.backend.service.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,YAAY,EAEZ,+BAA+B,EAC/B,oBAAoB,EAMrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAE3H,OAAO,EACL,iBAAiB,EAEjB,0BAA0B,EAK3B,MAAM,wDAAwD,CAAC;AAuDhE;;;;GAIG;AACH,oBAAY,kBAAkB;IAC5B,gCAAgC;IAChC,SAAS,cAAc;IACvB,0EAA0E;IAC1E,OAAO,YAAY;IACnB,sFAAsF;IACtF,cAAc,mBAAmB;CAClC;AAED;;;;;;GAMG;AACH;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAAC,eAAe,EAAE,OAAO,GAAG,kBAAkB,CAE/F;AAED,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,kBAAkB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAS/G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAEjI;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAIjF;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,4BAA4B;IAIF,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa;IAE3E,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,+BAA+B;IALvE,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAGzB,MAAM,EAAE,aAAa,EAExD,iBAAiB,EAAE,+BAA+B;IAMvE;;;;;OAKG;IACI,oBAAoB,CAAC,OAAO,GAAE,0BAA+B,GAAG,iBAAiB,EAAE;IAgC1F;;;;;;;;;;;;;;;;;;OAkBG;IACI,yBAAyB,CAC9B,YAAY,EAAE,YAAY,EAC1B,mBAAmB,EAAE,MAAM,EAC3B,eAAe,GAAE,WAAW,CAAC,oBAAoB,CAA4B,EAC7E,WAAW,CAAC,EAAE,MAAM,GACnB,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS;IAoB7D;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,sBAAsB;IAsB9B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,2BAA2B;IAInC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACH,OAAO,CAAC,4BAA4B;IAgGpC,qDAAqD;IACrD,OAAO,CAAC,aAAa;IAIrB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,4BAA4B;IAsBpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,gBAAgB;CAWzB"}
+{"version":3,"file":"mcp-tool-adapter.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/mcp/services/mcp-tool-adapter.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/mcp/services/mcp-tool-adapter.backend.service.js

@@ -10,12 +10,12 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { injectable, inject } from 'inversify';
-import { ResourcePrimaryScope, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, ResourceOperationRiskLevel, CoreResourceOperation, isDefaultUrlBearingOperation, createResourceSearchQueryRequestSchema, } from '@wildo-ai/saas-models';
+import { injectable, inject, optional } from 'inversify';
+import { ResourcePrimaryScope, PRIMARY_SCOPE_TO_FIELD_IDENTIFIER, ResourceOperationRiskLevel, CoreResourceOperation, isDefaultUrlBearingOperation, createResourceSearchQueryRequestSchema, FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES, FILE_UPLOAD_GRANT_DEFAULT_MINUTES, ResourcesConfigNamingUtils, } from '@wildo-ai/saas-models';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
 import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
 import { convertZodSchemaToMcpInputSchema, isMcpValueWrappedRequestDto } from '../../mcp/utils/zod-to-mcp-json-schema.backend.utils.js';
-import { MCP_TOOL_NAME_SEPARATOR, MCP_TOOL_NAME_MAX_LENGTH, isSpecConformantMcpToolName, } from '../../mcp/models/mcp-tool.backend.schemas.js';
+import { MCP_TOOL_NAME_SEPARATOR, MCP_TOOL_NAME_MAX_LENGTH, isSpecConformantMcpToolName, buildUploadGrantToolOperationPart, parseUploadGrantToolOperationPart, } from '../../mcp/models/mcp-tool.backend.schemas.js';
 /**
  * Resource primary scopes a **machine principal** can reach — ORG / APP only. Verified against the
  * authorizer (`authorizations.backend.service.ts`): `authorizeUserSelf` requires
@@ -139,6 +139,14 @@ export function isCollectionQueryMcpOperation(effectiveOperation) {
         || effectiveOperation === CoreResourceOperation.SEARCH
         || effectiveOperation === CoreResourceOperation.COUNT;
 }
+/**
+ * The kebab-case segment a file field gets in its upload ROUTE (`…/files/<segment>`) — the same
+ * transform `ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation` applies, so
+ * a derived tool name and the route it mints for agree by construction.
+ */
+export function fileFieldRouteSegment(fieldName) {
+    return ResourcesConfigNamingUtils.toKebabCase(fieldName.replace(/\./g, '-'));
+}
 /** Core operations that only read — surfaced as `annotations.readOnlyHint`. */
 const READ_ONLY_CORE_OPERATIONS = new Set([
     CoreResourceOperation.READ,
@@ -203,10 +211,12 @@ const DESTRUCTIVE_RISK_LEVELS = new Set([
 let McpToolAdapterBackendService = class McpToolAdapterBackendService {
     logger;
     resourcesRegistry;
+    fileFieldDetection;
     logDebug;
-    constructor(logger, resourcesRegistry) {
+    constructor(logger, resourcesRegistry, fileFieldDetection) {
         this.logger = logger;
         this.resourcesRegistry = resourcesRegistry;
+        this.fileFieldDetection = fileFieldDetection;
         this.logDebug = this.logger.debugByType('McpToolAdapterBackendService');
         this.logger.setDebugTypeLogging('McpToolAdapterBackendService', false);
     }
@@ -451,17 +461,151 @@ let McpToolAdapterBackendService = class McpToolAdapterBackendService {
                 : baseInputSchema;
             // …then withdraw the SCOPE field, wherever the DTO happens to place it.
             const inputSchema = this.withoutScopeParameters(advertisedSchema, config.resourcePrimaryScope);
+            const uploadableFileFields = this.uploadableFileFieldsFor(config.resourceIdentifier, operationIdentifier);
             descriptors.push({
                 name,
-                description: this.resolveDescription(config.resourceIdentifier, operationIdentifier, operation, descriptionProvider),
+                description: this.withUploadGrantNote(config.resourceIdentifier, operationIdentifier, uploadableFileFields, this.resolveDescription(config.resourceIdentifier, operationIdentifier, operation, descriptionProvider)),
                 inputSchema,
                 annotations: this.buildAnnotations(operationIdentifier, operation.riskLevel),
                 resourceType: config.resourceIdentifier,
                 operationIdentifier,
             });
+            /*
+             * ## Coverage: unit tests only, accepted deliberately — 2026-09-08 (#467)
+             *
+             * NO application reaches this derivation. Neither dogfood exposes an MCP operation carrying a
+             * user-uploadable file field: the two file fields declared belong to `todo-lists` and
+             * `knowledge-documents`, neither MCP-exposed, and the only file field on an MCP-exposed
+             * resource is `todos.generatedSummaryPdf` — PDF-template generated, and therefore excluded
+             * from uploadable fields BY DESIGN. So the derivation below, `resolveUploadGrantTool` and the
+             * mint path are covered by unit tests only.
+             *
+             * Nothing is wrong; the shape that reaches this code simply does not exist in any application.
+             * Buying the proof would mean authoring an uploadable file field for the purpose of testing
+             * it, which proves the harness more than the product — weighed and accepted.
+             *
+             * **What would change the answer:** an MCP-exposed resource gaining a user-uploadable file
+             * field. That author is the first party to execute this path.
+             */
+            // Issue #312, D11: one DERIVED upload-grant tool per user-uploadable file field of an exposed
+            // CREATE / UPDATE. It inherits every gate the parent just passed (exposure, instance, scope) by
+            // construction — it is emitted inside the parent's own iteration — and is resolved back through
+            // the parent by `resolveUploadGrantTool`, so advertised ≡ callable holds for it too.
+            for (const fileField of uploadableFileFields) {
+                const derivedName = this.buildToolName(config.resourceIdentifier, buildUploadGrantToolOperationPart(operationIdentifier, fileFieldRouteSegment(fileField.fieldName)));
+                if (!isSpecConformantMcpToolName(derivedName)) {
+                    // Same withdrawal as the parent's guard above: a name the client could not parse is not
+                    // advertised, and `resolveUploadGrantTool` mirrors the check so it is not callable either.
+                    this.logger.warn('Skipping MCP upload-grant tool whose derived name does not satisfy the MCP naming guidance', {
+                        toolName: derivedName, resourceIdentifier: config.resourceIdentifier, operationIdentifier, fieldName: fileField.fieldName, maxLength: MCP_TOOL_NAME_MAX_LENGTH,
+                    });
+                    continue;
+                }
+                if (seen.has(derivedName))
+                    continue;
+                seen.add(derivedName);
+                descriptors.push(this.buildUploadGrantDescriptor(config.resourceIdentifier, operationIdentifier, fileField, derivedName, bindsInstanceId ? selfFieldIdentifier : undefined, name));
+            }
         }
         return descriptors.sort((a, b) => a.operationIdentifier.localeCompare(b.operationIdentifier));
     }
+    /**
+     * The user-uploadable file fields a CREATE / UPDATE operation carries; `[]` for every other operation
+     * (a READ or DELETE never receives a file) and whenever no detector is bound.
+     */
+    uploadableFileFieldsFor(resourceType, operationIdentifier) {
+        if (operationIdentifier !== String(CoreResourceOperation.CREATE) && operationIdentifier !== String(CoreResourceOperation.UPDATE))
+            return [];
+        if (!this.fileFieldDetection) {
+            this.warnOnceNoFileFieldDetection();
+            return [];
+        }
+        return this.fileFieldDetection.getUploadableFileFields(resourceType);
+    }
+    warnedNoFileFieldDetection = false;
+    /**
+     * Debug, not warn: the container always binds the detector, so in production this never fires; where
+     * it does fire — a harness that constructs the adapter bare — a warning would be noise about a
+     * dependency the harness deliberately left out.
+     */
+    warnOnceNoFileFieldDetection() {
+        if (this.warnedNoFileFieldDetection)
+            return;
+        this.warnedNoFileFieldDetection = true;
+        this.logDebug('No FileFieldDetectionService bound — no upload-grant tool is advertised or callable');
+    }
+    /**
+     * Append, to the PARENT tool's description, where each file field's `fileId` comes from. Engine-
+     * appended for the same reason as the envelope note: how a file reaches a resource is a framework
+     * fact, not app prose, and an agent reading `attachments.fileId: string` would otherwise have no way
+     * to learn that the value cannot be invented.
+     */
+    withUploadGrantNote(resourceType, operationIdentifier, fileFields, description) {
+        if (fileFields.length === 0)
+            return description;
+        const lines = fileFields.map((f) => `"${f.fieldName}.${f.fileMetadata.multiple ? 'fileIds' : 'fileId'}" is obtained by calling ${this.buildToolName(resourceType, buildUploadGrantToolOperationPart(operationIdentifier, fileFieldRouteSegment(f.fieldName)))} and uploading the file with the link it returns; a fileId cannot be invented.`);
+        return `${description}
+
+File fields: ${lines.join(' ')}`;
+    }
+    /**
+     * The derived upload-grant descriptor. Its arguments are the parent's instance id (UPDATE only —
+     * the same id the parent advertises, split out by the transport exactly the same way) and an
+     * optional lifetime bounded by the engine ceiling. Nothing about the file itself: bytes never
+     * travel through a tool call, which is the whole reason this tool exists.
+     */
+    buildUploadGrantDescriptor(resourceType, parentOperationIdentifier, fileField, name, instanceIdField, parentToolName) {
+        const properties = {
+            ...(instanceIdField ? { [instanceIdField]: { type: 'string', description: `The ${String(resourceType)} record the file is for — the same id ${parentToolName} takes.` } } : {}),
+            expiresInMinutes: {
+                type: 'integer', minimum: 1, maximum: FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES,
+                description: `How long the link stays usable (default ${FILE_UPLOAD_GRANT_DEFAULT_MINUTES}, at most ${FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES}).`,
+            },
+            // Declaring the file up front lets the server refuse an impossible one BEFORE a link exists — the
+            // same facts the MCP File Objects proposal has a client declare when it asks to upload.
+            name: { type: 'string', maxLength: 255, description: 'The file name you intend to upload (used in the returned command).' },
+            mimeType: { type: 'string', maxLength: 255, description: `Declared MIME type; refused now if the field does not accept it (accepted: ${fileField.fileMetadata.allowedMimeTypes?.join(', ') || 'any'}).` },
+            size: { type: 'integer', minimum: 1, description: 'Declared size in bytes; refused now if above the field maximum.' },
+        };
+        const target = `the "${fileField.fieldName}" file of a ${String(resourceType)} record (${parentOperationIdentifier})`;
+        return {
+            name,
+            description: `Mint a single-use upload link for ${target}. NOTHING is uploaded by this call and no bytes ever travel through a tool call. `
+                + 'It returns uploadCommand — run it if you can execute commands and the file is on your filesystem — and uploadPageUrl — show it to the user otherwise, so they can drop the file in their browser. '
+                + 'The link is not the caller\'s credential: it unlocks exactly ONE upload of ONE file into this field and then dies. '
+                + `Afterwards read the produced fileId (from the upload response, or from statusUrl if a human uploaded) and pass it as "${fileField.fieldName}.${fileField.fileMetadata.multiple ? 'fileIds' : 'fileId'}" in ${parentToolName}. `
+                + 'If the link expires or the upload is refused, call this again.',
+            inputSchema: { type: 'object', properties, ...(instanceIdField ? { required: [instanceIdField] } : {}), additionalProperties: false },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            resourceType,
+            operationIdentifier: buildUploadGrantToolOperationPart(parentOperationIdentifier, fileFieldRouteSegment(fileField.fieldName)),
+        };
+    }
+    /**
+     * Resolve a DERIVED upload-grant tool back to its parent operation and file field — the callable
+     * half of `buildToolDescriptors`' derived emission, kept symmetric with it: the parent is resolved
+     * through `resolveExposableOperation` (so exposure, instance and principal-scope gating are
+     * inherited verbatim), the field must be one of the resource's uploadable file fields, and the
+     * composed name must satisfy the naming guidance. `undefined` for anything that is not a well-formed,
+     * advertised derived tool.
+     */
+    resolveUploadGrantTool(resourceType, operationPart, reachableScopes, instanceRef) {
+        const parsed = parseUploadGrantToolOperationPart(operationPart);
+        if (!parsed)
+            return undefined;
+        const kind = parsed.parentOperationIdentifier;
+        if (kind !== String(CoreResourceOperation.CREATE) && kind !== String(CoreResourceOperation.UPDATE))
+            return undefined;
+        if (!isSpecConformantMcpToolName(this.buildToolName(resourceType, operationPart)))
+            return undefined;
+        const parentOperation = this.resolveExposableOperation(resourceType, kind, reachableScopes, instanceRef);
+        if (!parentOperation)
+            return undefined;
+        const field = this.uploadableFileFieldsFor(resourceType, kind).find((f) => fileFieldRouteSegment(f.fieldName) === parsed.fieldRouteSegment);
+        if (!field)
+            return undefined;
+        return { parentOperation, fieldName: field.fieldName, operationKind: kind };
+    }
     /** `<resourceIdentifier>__<operationIdentifier>`. */
     buildToolName(resourceIdentifier, operationIdentifier) {
         return `${String(resourceIdentifier)}${MCP_TOOL_NAME_SEPARATOR}${operationIdentifier}`;
@@ -681,7 +825,9 @@ McpToolAdapterBackendService = __decorate([
     injectable(),
     __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
     __param(1, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
-    __metadata("design:paramtypes", [Function, ResourcesRegistryBackendService])
+    __param(2, inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)),
+    __param(2, optional()),
+    __metadata("design:paramtypes", [Function, ResourcesRegistryBackendService, Function])
 ], McpToolAdapterBackendService);
 export { McpToolAdapterBackendService };
 //# sourceMappingURL=mcp-tool-adapter.backend.service.js.map