fix(connectors): fetch-and-attach real multipart file parts (#645)

[rangarajan19]

Closes #645.

Draft — the download currently uses a plain axios call, isolated in its own fetchFileForUpload function. Per the discussion on #645, I'll swap it to the shared outbound-fetch helper once it's on main, before marking this ready for review.

What this does

• Adds a __file bodyMapping marker (bodyMapping: { image: { "__file": "$image" } }), following the existing __raw/__spread convention.
• In the form-data branch, detects that marker and fetches the URL server-side (through the existing assertSafeOutboundUrl SSRF guard, no new surface) instead of stringifying it, then attaches it as a real multipart part.
• form-urlencoded + __file is a config error — that encoding can't carry a file.
• A file param type in the custom tool builder, selectable only when target is body and encoding is multipart/form-data. Exposed to the model as { type: 'string', format: 'uri' }, since JSON Schema has no file type.

Following the maintainer's corrections from the issue thread

• Buffers the download into memory rather than streaming it straight into the multipart part — a FormData built from a live stream can't be read twice, and execute() resends the same axiosConfig on an OAuth2/LOGIN_TOKEN 401 retry. The form is now built via a small factory and rebuilt for that retry, so the file is fetched once but the body can be resent intact.
• No connector credentials (auth, headers, proxy) on the file download — it's a bare request to a third party unrelated to the connector.
• Non-2xx from the file URL fails the tool call with a clear message instead of attaching an error page as the file.
• Filename: Content-Disposition's filename wins when present, otherwise the URL's last path segment; both go through the same sanitizing ([A-Za-z0-9._-], fallback file).
• Content-Type: trusts the response header, falls back to application/octet-stream.
• Size: MAX_FILE_UPLOAD_BYTES env var, default 10MB, download aborted as soon as the cap is crossed.
• 30s timeout on the download; the URL's query string is never logged (presigned URLs carry credentials there).

Tests

Added to rest.engine.spec.ts:

• fetches the __file URL and attaches it as a real multipart part, with no connector credentials on the download
• aborts the download once it crosses the size cap, without sending the real request
• fails the tool call when the file URL answers with a non-2xx status
• rejects a __file marker when encoding is form-urlencoded
• refuses to download a __file URL that resolves to a blocked address (SSRF)
• rebuilds the multipart body with the same file on a 401 retry, fetching the file only once

82/82 tests pass (76 existing + 6 new). Full backend + frontend typecheck clean.

Docs

Short note in docs/tool-definition.md documenting the __file marker.

[keysersoft]

Thanks @rangarajan19, nice work, and the switch to fetchOutbound is exactly what I hoped for: SSRF checks on every redirect, size cap, no connector credentials on the download, and the rebuilt body on the 401 retry.

One thing I tightened before merging: a $param resolves to the caller's value as is, objects included, and __spread lets the caller choose the keys. So a model could send { "__file": "https://..." } as an ordinary field and make any form-data tool download a URL of its choosing. I pushed a commit that only honours the marker for fields the tool's own bodyMapping declares, fails the call when one arrives in the arguments, and leaves out an optional file the caller didn't pass. Two tests cover it (direct field and __spread).

Also merged main into the branch. Merging once CI is green.