🔐 feat: Serve Stored Files Through LibreChat With Stable Links

[Vidminas]

Pull Request

Before submitting, please review the Contributing Guide.

Documentation changes belong in the LibreChat documentation repository.

👍

Summary

With fileStrategy: "s3", browsers load files from presigned URLs. Those expire after S3_URL_EXPIRY_SECONDS and are stored in messages and file records, so images break (#10269, #10145, #13762). Because browsers fetch from S3 directly, the bucket also can't be kept private to the deployment's network.

STORAGE_PROXY_FILES=true makes storage strategies link files to LibreChat instead: /api/stored-files/<source>/<key>, which never expires. The route streams each object to viewers who may read it. This PR adds the storage-agnostic route and the S3 adapter. Off by default.

Related to #16912. Depends on #16913

How it works

GET /api/stored-files/<source>/<key>
  authenticateViewer      # session cookie, as /images, incl. retired-token and 2FA checks
  sources[source]         # StoredFileSource adapter: parseKey, read, isNotFound
  owner?                  → serve
  other tenant?           → 404
  avatar?                 → serve to any signed-in user (CloudFront cookie scope)
  canAccessFile(record)   → serve (e.g. a file on a shared agent), else 404

packages/api/src/storage/
├── proxy/link.ts       # STORED_FILES_ROUTE, getStoredFileURL, parseStoredFileURL, isStoredFileProxyEnabled
├── proxy/handler.ts    # createStoredFileHandler
└── s3/source.ts        # s3FileSource adapter
api/server/routes/storedFiles.js   # wiring; mounted only when STORAGE_PROXY_FILES is on

With the proxy on, the S3 strategy:

• stores stored-file links instead of presigned URLs;
• reads them back to keys, through extractKeyFromS3Url;
• replaces presigned links where the file list and avatars already renew links;
• returns no direct download URL, so download and shared-link routes stream through their own checks.

With it off, stored links go back to presigned ones the same way.

Responses: only raster images are sent inline, and every response carries a sandboxing CSP and nosniff.

Type of change

• Bug fix
• Feature
• Refactor
• Performance improvement
• Breaking change
• Documentation
• Translation
• Tests / tooling / CI

Testing

1. Set fileStrategy: "s3" and STORAGE_PROXY_FILES=true, and start the server.
2. Upload an image in a conversation. Its link is /api/stored-files/s3/..., and the browser makes no request to S3.
3. Wait past S3_URL_EXPIRY_SECONDS (defaults to 2 minutes) and reload. The image still loads.
4. Check who can open a link:
   • Opened without a session, it returns 401.
   • Opened as another user, it returns 404.
   • Avatars load for every signed-in user.
5. Downloads and shared links still work.

Tested environments/configuration:

• OS: macOS 27.0.1 (arm64)
• Browser: Brave 1.96.61 (Chromium 154), macOS, for manual end-to-end testing of this PR on a deployment (below): images in chat, file previews, downloads and avatars.
• Storage: S3 on AWS:
  • LibreChat on ECS Fargate, with these commits applied unchanged on top of main at cd5dd94de;
  • Amazon DocumentDB 8.0;
  • sign-in through Amazon Cognito (OpenID);
  • fileStrategy: s3 with STORAGE_PROXY_FILES=true;
  • the bucket refuses object reads and writes from anywhere but the VPC's S3 gateway endpoint, and requires TLS 1.2 or later.

Automated tests:

• npm run static-checks -- --against upstream/dev --full passes.
• npm run lighthouse with Node 24.18.0, MongoDB 8.2.1 via mongodb-memory-server 11.0.1, S3 mocked with aws-sdk-client-mock, and Google Chrome 154.0.8037.97 (headless). The medians matched dev: LCP 3,432 ms against 3,455 ms, CLS 0.018 against 0.018, TBT 57 ms against 58 ms.
• Feature flags: STORAGE_PROXY_FILES on and off.

New tests:

• proxy/__tests__/handler.test.ts:
  • inline images and the response headers;
  • HEAD requests;
  • attachments;
  • 401 and 403;
  • other users;
  • avatars;
  • tenant isolation, and running the file check in the viewer's tenant context;
  • unknown sources;
  • 404 for missing objects and a bare 500 for other failures;
  • 405 for other methods.
• proxy/__tests__/link.test.ts.
• s3/__tests__/source.test.ts: the strategy in both modes, and the adapter (GetObject, HeadObject, missing objects).
• images/authorization.spec.ts: authenticateViewer.
• routes/__tests__/storedFiles.spec.js: the real @librechat/api build with mocked S3.

Screenshots / recordings

No user-facing change.

Risk / compatibility

• Off by default, with no behaviour change while off.
• Image bytes now pass through the app server. The route streams each object, aborts the S3 read when the client disconnects, and answers HEAD with HeadObject.
• API clients (OpenAI-compatible and Responses) receive relative stored-file links that need a session, as they already do with local storage and CloudFront.
• Links stored before the switch: the file list and avatars convert theirs as they load. Messages keep presigned links until the migration added in 🔁 feat: Add a Migration to Stored File Links and Back #16916 runs.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• Existing relevant tests pass
• The change does not introduce new warnings or errors
• User-facing or complex behavior is documented where necessary
• Required dependency changes have been merged/published
• Required documentation PR: 🔐 docs: Document Serving S3 Files Through LibreChat docs#817

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.