Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🌩️ feat: CloudFront CDN File Strategy (#12193)
Atef Bellaaj187ab787da38
diff --git a/api/package.json b/api/package.jsonindex c5b588610e..c7bdd1145a 100644--- a/api/package.json+++ b/api/package.json@@ -36,7 +36,9 @@"dependencies": {"@anthropic-ai/vertex-sdk": "^0.14.3","@aws-sdk/client-bedrock-runtime": "^3.1013.0",+ "@aws-sdk/client-cloudfront": "^3.1042.0","@aws-sdk/client-s3": "^3.980.0",+ "@aws-sdk/cloudfront-signer": "^3.1036.0","@aws-sdk/s3-request-presigner": "^3.758.0","@azure/identity": "^4.13.1","@azure/search-documents": "^12.0.0",diff --git a/api/server/controllers/auth/LogoutController.js b/api/server/controllers/auth/LogoutController.jsindex 381bfc58b2..ae1c94a7c9 100644--- a/api/server/controllers/auth/LogoutController.js+++ b/api/server/controllers/auth/LogoutController.js@@ -1,5 +1,5 @@const cookies = require('cookie');-const { isEnabled } = require('@librechat/api');+const { isEnabled, clearCloudFrontCookies } = require('@librechat/api');const { logger } = require('@librechat/data-schemas');const { logoutUser } = require('~/server/services/AuthService');const { getOpenIdConfig } = require('~/strategies');@@ -44,6 +44,7 @@ const logoutController = async (req, res) => {res.clearCookie('openid_id_token');res.clearCookie('openid_user_id');res.clearCookie('token_provider');+ clearCloudFrontCookies(res);const response = { message };if (isOpenIdUser &&diff --git a/api/server/controllers/auth/LogoutController.spec.js b/api/server/controllers/auth/LogoutController.spec.jsindex c9294fdcec..ff02f5237e 100644--- a/api/server/controllers/auth/LogoutController.spec.js+++ b/api/server/controllers/auth/LogoutController.spec.js@@ -4,9 +4,13 @@ const mockLogoutUser = jest.fn();const mockLogger = { warn: jest.fn(), error: jest.fn(), debug: jest.fn() };const mockIsEnabled = jest.fn();const mockGetOpenIdConfig = jest.fn();+const mockClearCloudFrontCookies = jest.fn();jest.mock('cookie');-jest.mock('@librechat/api', () => ({ isEnabled: (...args) => mockIsEnabled(...args) }));+jest.mock('@librechat/api', () => ({+ isEnabled: (...args) => mockIsEnabled(...args),+ clearCloudFrontCookies: (...args) => mockClearCloudFrontCookies(...args),+}));jest.mock('@librechat/data-schemas', () => ({ logger: mockLogger }));jest.mock('~/server/services/AuthService', () => ({logoutUser: (...args) => mockLogoutUser(...args),@@ -255,6 +259,15 @@ describe('LogoutController', () => {expect(res.clearCookie).toHaveBeenCalledWith('openid_user_id');expect(res.clearCookie).toHaveBeenCalledWith('token_provider');});++ it('calls clearCloudFrontCookies on successful logout', async () => {+ const req = buildReq();+ const res = buildRes();++ await logoutController(req, res);++ expect(mockClearCloudFrontCookies).toHaveBeenCalledWith(res);+ });});describe('URL length limit and logout_hint fallback', () => {diff --git a/api/server/services/AuthService.js b/api/server/services/AuthService.jsindex 816a0eac5b..40b3c1a725 100644--- a/api/server/services/AuthService.js+++ b/api/server/services/AuthService.js@@ -11,6 +11,7 @@ const {math,isEnabled,checkEmailConfig,+ setCloudFrontCookies,isEmailDomainAllowed,shouldUseSecureCookie,resolveAppConfigForUser,@@ -440,6 +441,9 @@ const setAuthTokens = async (userId, res, _session = null) => {secure: shouldUseSecureCookie(),sameSite: 'strict',});++ setCloudFrontCookies(res);+return token;} catch (error) {logger.error('[setAuthTokens] Error in setting authentication tokens:', error);@@ -557,6 +561,9 @@ const setOpenIDAuthTokens = (tokenset, req, res, userId, existingRefreshToken) =sameSite: 'strict',});}++ setCloudFrontCookies(res);+return appAuthToken;} catch (error) {logger.error('[setOpenIDAuthTokens] Error in setting authentication tokens:', error);diff --git a/api/server/services/AuthService.spec.js b/api/server/services/AuthService.spec.jsindex c8abafdbe5..df89f3f2c9 100644--- a/api/server/services/AuthService.spec.js+++ b/api/server/services/AuthService.spec.js@@ -15,6 +15,7 @@ jest.mock('@librechat/api', () => ({math: jest.fn((val, fallback) => (val ? Number(val) : fallback)),shouldUseSecureCookie: jest.fn(() => false),resolveAppConfigForUser: jest.fn(async (_getAppConfig, _user) => ({})),+ setCloudFrontCookies: jest.fn(() => true),}));jest.mock('~/models', () => ({findUser: jest.fn(),@@ -40,10 +41,17 @@ const {shouldUseSecureCookie,isEmailDomainAllowed,resolveAppConfigForUser,+ setCloudFrontCookies,} = require('@librechat/api');-const { findUser } = require('~/models');+const {+ findUser,+ getUserById,+ generateToken,+ generateRefreshToken,+ createSession,+} = require('~/models');const { getAppConfig } = require('~/server/services/Config');-const { setOpenIDAuthTokens, requestPasswordReset } = require('./AuthService');+const { setOpenIDAuthTokens, requestPasswordReset, setAuthTokens } = require('./AuthService');/** Helper to build a mock Express response */function mockResponse() {@@ -339,3 +347,67 @@ describe('requestPasswordReset', () => {expect(result.message).toContain('If an account with that email exists');});});++describe('CloudFront cookie integration', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ describe('setOpenIDAuthTokens', () => {+ const validTokenset = {+ id_token: 'the-id-token',+ access_token: 'the-access-token',+ refresh_token: 'the-refresh-token',+ };++ it('calls setCloudFrontCookies with response object', () => {+ const req = mockRequest();+ const res = mockResponse();++ setOpenIDAuthTokens(validTokenset, req, res, 'user-123');++ expect(setCloudFrontCookies).toHaveBeenCalledWith(res);+ });++ it('succeeds even when setCloudFrontCookies returns false', () => {+ setCloudFrontCookies.mockReturnValue(false);++ const req = mockRequest();+ const res = mockResponse();++ const result = setOpenIDAuthTokens(validTokenset, req, res, 'user-123');++ expect(result).toBe('the-id-token');+ });+ });++ describe('setAuthTokens', () => {+ beforeEach(() => {+ getUserById.mockResolvedValue({ _id: 'user-123' });+ generateToken.mockResolvedValue('mock-access-token');+ generateRefreshToken.mockReturnValue('mock-refresh-token');+ createSession.mockResolvedValue({+ session: { expiration: new Date(Date.now() + 604800000) },+ refreshToken: 'mock-refresh-token',+ });+ });++ it('calls setCloudFrontCookies with response object', async () => {+ const res = mockResponse();++ await setAuthTokens('user-123', res);++ expect(setCloudFrontCookies).toHaveBeenCalledWith(res);+ });++ it('succeeds even when setCloudFrontCookies returns false', async () => {+ setCloudFrontCookies.mockReturnValue(false);++ const res = mockResponse();++ const result = await setAuthTokens('user-123', res);++ expect(result).toBe('mock-access-token');+ });+ });+});diff --git a/api/server/services/Files/images/encode.js b/api/server/services/Files/images/encode.jsindex 93d0aebd4b..2f075229aa 100644--- a/api/server/services/Files/images/encode.js+++ b/api/server/services/Files/images/encode.js@@ -80,7 +80,12 @@ const base64Only = new Set([EModelEndpoint.bedrock,]);-const blobStorageSources = new Set([FileSources.azure_blob, FileSources.s3, FileSources.firebase]);+const blobStorageSources = new Set([+ FileSources.azure_blob,+ FileSources.s3,+ FileSources.firebase,+ FileSources.cloudfront,+]);/*** Encodes and formats the given files.diff --git a/api/server/services/Files/strategies.js b/api/server/services/Files/strategies.jsindex 47b39cb87b..8a88e9d2e1 100644--- a/api/server/services/Files/strategies.js+++ b/api/server/services/Files/strategies.js@@ -2,14 +2,20 @@ const { FileSources } = require('librechat-data-provider');const {getS3URL,saveURLToS3,+ ImageService,parseDocument,uploadFileToS3,- S3ImageService,saveBufferToS3,getS3FileStream,deleteFileFromS3,+ getCloudFrontURL,uploadMistralOCR,+ saveURLToCloudFront,uploadAzureMistralOCR,+ uploadFileToCloudFront,+ saveBufferToCloudFront,+ getCloudFrontFileStream,+ deleteFileFromCloudFront,uploadGoogleVertexMistralOCR,} = require('@librechat/api');const {@@ -37,15 +43,21 @@ const {const { resizeImageBuffer } = require('./images/resize');const { updateUser, updateFile } = require('~/models');-const s3ImageService = new S3ImageService({+const imageServiceDeps = {resizeImageBuffer,updateUser,updateFile,-});+};-const uploadImageToS3 = (params) => s3ImageService.uploadImageToS3(params);+const s3ImageService = new ImageService(saveBufferToS3, imageServiceDeps);+const uploadImageToS3 = (params) => s3ImageService.uploadImage(params);const prepareImageURLS3 = (_req, file) => s3ImageService.prepareImageURL(file);const processS3Avatar = (params) => s3ImageService.processAvatar(params);++const cloudFrontImageService = new ImageService(saveBufferToCloudFront, imageServiceDeps);+const uploadImageToCloudFront = (params) => cloudFrontImageService.uploadImage(params);+const prepareCloudFrontImageURL = (_req, file) => cloudFrontImageService.prepareImageURL(file);+const processCloudFrontAvatar = (params) => cloudFrontImageService.processAvatar(params);const {saveBufferToAzure,saveURLToAzure,@@ -109,6 +121,22 @@ const s3Strategy = () => ({getDownloadStream: getS3FileStream,});+/**+ * CloudFront CDN Strategy Functions+ * Uses S3 for storage, CloudFront for URL delivery+ */+const cloudfrontStrategy = () => ({+ handleFileUpload: uploadFileToCloudFront,+ saveURL: saveURLToCloudFront,+ getFileURL: getCloudFrontURL,+ deleteFile: deleteFileFromCloudFront,+ saveBuffer: saveBufferToCloudFront,+ prepareImagePayload: prepareCloudFrontImageURL,+ processAvatar: processCloudFrontAvatar,+ handleImageUpload: uploadImageToCloudFront,+ getDownloadStream: getCloudFrontFileStream,+});+/*** Azure Blob Storage Strategy Functions*@@ -291,6 +319,8 @@ const getStrategyFunctions = (fileSource) => {return vectorStrategy();} else if (fileSource === FileSources.s3) {return s3Strategy();+ } else if (fileSource === FileSources.cloudfront) {+ return cloudfrontStrategy();} else if (fileSource === FileSources.execute_code) {return codeOutputStrategy();} else if (fileSource === FileSources.mistral_ocr) {diff --git a/librechat.example.yaml b/librechat.example.yamlindex 1b8fa43ee8..dd275718a2 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -18,12 +18,28 @@ cache: true# image: "firebase" # Storage for uploaded images in chats# document: "local" # Storage for document uploads (PDFs, text files, etc.)-# Available strategies: "local", "s3", "firebase"+# Available strategies: "local", "s3", "firebase", "azure_blob", "cloudfront"# If not specified, defaults to "local" for all file types# You can mix and match strategies based on your needs:# - Use S3 for avatars for fast global access# - Use Firebase for images with automatic optimization# - Use local storage for documents for privacy/compliance+# - Use CloudFront for CDN-accelerated delivery (requires S3 + cloudfront config below)++# CloudFront CDN Configuration (optional)+# Use when fileStrategy: "cloudfront" or fileStrategies includes cloudfront+# Requires: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME+# For signed cookies/URLs: CLOUDFRONT_KEY_PAIR_ID, CLOUDFRONT_PRIVATE_KEY+# cloudfront:+# domain: "https://cdn.example.com" # CloudFront domain (CNAME recommended for cookies)+# distributionId: "E1234ABCD" # Required if invalidateOnDelete is true+# invalidateOnDelete: false # Create cache invalidation on file delete+# imageSigning: "none" # "none" (public) | "cookies" (signed cookies)+# # When imageSigning: "cookies", API + CloudFront must share a parent domain:+# # API: api.example.com, CloudFront CNAME: cdn.example.com, cookieDomain: ".example.com"+# cookieDomain: ".example.com" # Required for "cookies" - shared parent domain+# cookieExpiry: 1800 # Cookie lifetime in seconds (max: 604800 / 7 days, default: 1800 / 30 min)+# urlExpiry: 3600 # Reserved for future signed-URL mode (not yet implemented)# Custom interface configurationinterface:@@ -116,7 +132,7 @@ interface:# - create: Allow users to create and manage new MCP servers# - share: Allow users to share MCP servers with other users# - public: Allow users to share MCP servers publicly (with everyone)-+# Creation / edit MCP server config Dialog config example# trustCheckbox:# label:diff --git a/package-lock.json b/package-lock.jsonindex 183eff0c19..d578383bce 100644--- a/package-lock.json+++ b/package-lock.json@@ -51,7 +51,9 @@"dependencies": {"@anthropic-ai/vertex-sdk": "^0.14.3","@aws-sdk/client-bedrock-runtime": "^3.1013.0",+ "@aws-sdk/client-cloudfront": "^3.1042.0","@aws-sdk/client-s3": "^3.980.0",+ "@aws-sdk/cloudfront-signer": "^3.1036.0","@aws-sdk/s3-request-presigner": "^3.758.0","@azure/identity": "^4.13.1","@azure/search-documents": "^12.0.0",@@ -3275,6 +3277,112 @@"node": ">=18.0.0"}},+ "node_modules/@aws-sdk/client-cloudfront": {+ "version": "3.1042.0",+ "resolved": "https://registry.npmjs.org/@aws-sdk/client-cloudfront/-/client-cloudfront-3.1042.0.tgz",+ "integrity": "sha512-LE79zvUbdvXGExuJBbJAvvNWtnxwVXYYuyQMU3pzVv4gPUknsR3WTsaEhrdR8CkRM2wXq3ZKOPSyph3C2ZYa7g==",+ "license": "Apache-2.0",+ "dependencies": {+ "@aws-crypto/sha256-browser": "5.2.0",+ "@aws-crypto/sha256-js": "5.2.0",+ "@aws-sdk/core": "^3.974.8",+ "@aws-sdk/credential-provider-node": "^3.972.39",+ "@aws-sdk/middleware-host-header": "^3.972.10",+ "@aws-sdk/middleware-logger": "^3.972.10",+ "@aws-sdk/middleware-recursion-detection": "^3.972.11",+ "@aws-sdk/middleware-user-agent": "^3.972.38",+ "@aws-sdk/region-config-resolver": "^3.972.13",+ "@aws-sdk/types": "^3.973.8",+ "@aws-sdk/util-endpoints": "^3.996.8",+ "@aws-sdk/util-user-agent-browser": "^3.972.10",+ "@aws-sdk/util-user-agent-node": "^3.973.24",+ "@smithy/config-resolver": "^4.4.17",+ "@smithy/core": "^3.23.17",+ "@smithy/fetch-http-handler": "^5.3.17",+ "@smithy/hash-node": "^4.2.14",+ "@smithy/invalid-dependency": "^4.2.14",+ "@smithy/middleware-content-length": "^4.2.14",+ "@smithy/middleware-endpoint": "^4.4.32",+ "@smithy/middleware-retry": "^4.5.7",+ "@smithy/middleware-serde": "^4.2.20",+ "@smithy/middleware-stack": "^4.2.14",+ "@smithy/node-config-provider": "^4.3.14",+ "@smithy/node-http-handler": "^4.6.1",+ "@smithy/protocol-http": "^5.3.14",+ "@smithy/smithy-client": "^4.12.13",+ "@smithy/types": "^4.14.1",+ "@smithy/url-parser": "^4.2.14",+ "@smithy/util-base64": "^4.3.2",+ "@smithy/util-body-length-browser": "^4.2.2",+ "@smithy/util-body-length-node": "^4.2.3",+ "@smithy/util-defaults-mode-browser": "^4.3.49",+ "@smithy/util-defaults-mode-node": "^4.2.54",+ "@smithy/util-endpoints": "^3.4.2",+ "@smithy/util-middleware": "^4.2.14",+ "@smithy/util-retry": "^4.3.6",+ "@smithy/util-stream": "^4.5.25",+ "@smithy/util-utf8": "^4.2.2",+ "@smithy/util-waiter": "^4.3.0",+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=20.0.0"+ }+ },+ "node_modules/@aws-sdk/client-cloudfront/node_modules/@aws-sdk/util-endpoints": {+ "version": "3.996.8",+ "resolved": "https://registry.npmjs.org/@aws-sdk/util-endpoints/-/util-endpoints-3.996.8.tgz",+ "integrity": "sha512-oOZHcRDihk5iEe5V25NVWg45b3qEA8OpHWVdU/XQh8Zj4heVPAJqWvMphQnU7LkufmUo10EpvFPZuQMiFLJK3g==",+ "license": "Apache-2.0",+ "dependencies": {+ "@aws-sdk/types": "^3.973.8",+ "@smithy/types": "^4.14.1",+ "@smithy/url-parser": "^4.2.14",+ "@smithy/util-endpoints": "^3.4.2",+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=20.0.0"+ }+ },+ "node_modules/@aws-sdk/client-cloudfront/node_modules/@smithy/is-array-buffer": {+ "version": "4.2.2",+ "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-4.2.2.tgz",+ "integrity": "sha512-n6rQ4N8Jj4YTQO3YFrlgZuwKodf4zUFs7EJIWH86pSCWBaAtAGBFfCM7Wx6D2bBJ2xqFNxGBSrUWswT3M0VJow==",+ "license": "Apache-2.0",+ "dependencies": {+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=18.0.0"+ }+ },+ "node_modules/@aws-sdk/client-cloudfront/node_modules/@smithy/util-buffer-from": {+ "version": "4.2.2",+ "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-4.2.2.tgz",+ "integrity": "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q==",+ "license": "Apache-2.0",+ "dependencies": {+ "@smithy/is-array-buffer": "^4.2.2",+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=18.0.0"+ }+ },+ "node_modules/@aws-sdk/client-cloudfront/node_modules/@smithy/util-utf8": {+ "version": "4.2.2",+ "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-4.2.2.tgz",+ "integrity": "sha512-75MeYpjdWRe8M5E3AW0O4Cx3UadweS+cwdXjwYGBW5h/gxxnbeZ877sLPX/ZJA9GVTlL/qG0dXP29JWFCD1Ayw==",+ "license": "Apache-2.0",+ "dependencies": {+ "@smithy/util-buffer-from": "^4.2.2",+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=18.0.0"+ }+ },"node_modules/@aws-sdk/client-kendra": {"version": "3.1041.0","resolved": "https://registry.npmjs.org/@aws-sdk/client-kendra/-/client-kendra-3.1041.0.tgz",@@ -3537,6 +3645,20 @@"node": ">=18.0.0"}},+ "node_modules/@aws-sdk/cloudfront-signer": {+ "version": "3.1036.0",+ "resolved": "https://registry.npmjs.org/@aws-sdk/cloudfront-signer/-/cloudfront-signer-3.1036.0.tgz",+ "integrity": "sha512-AXEl7lGvlbWbN0Xi0dd0XVfzVnA39dUyMILPcTk6Q5DkwmPgp6M/K6A6Ejbjajhoe8C1AUF4O1+hDc7DPxnBxg==",+ "license": "Apache-2.0",+ "dependencies": {+ "@smithy/core": "^3.23.17",+ "@smithy/url-parser": "^4.2.14",+ "tslib": "^2.6.2"+ },+ "engines": {+ "node": ">=20.0.0"+ }+ },"node_modules/@aws-sdk/core": {"version": "3.974.8","resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.974.8.tgz",@@ -19204,19 +19326,6 @@"dev": true,"license": "(Unlicense OR Apache-2.0)"},- "node_modules/@smithy/abort-controller": {- "version": "4.2.12",- "resolved": "https://registry.npmjs.org/@smithy/abort-controller/-/abort-controller-4.2.12.tgz",- "integrity": "sha512-xolrFw6b+2iYGl6EcOL7IJY71vvyZ0DJ3mcKtpykqPe2uscwtzDZJa1uVQXyP7w9Dd+kGwYnPbMsJrGISKiY/Q==",- "license": "Apache-2.0",- "dependencies": {- "@smithy/types": "^4.13.1",- "tslib": "^2.6.2"- },- "engines": {- "node": ">=18.0.0"- }- },"node_modules/@smithy/chunked-blob-reader": {"version": "5.2.0","resolved": "https://registry.npmjs.org/@smithy/chunked-blob-reader/-/chunked-blob-reader-5.2.0.tgz",@@ -20175,13 +20284,12 @@}},"node_modules/@smithy/util-waiter": {- "version": "4.2.8",- "resolved": "https://registry.npmjs.org/@smithy/util-waiter/-/util-waiter-4.2.8.tgz",- "integrity": "sha512-n+lahlMWk+aejGuax7DPWtqav8HYnWxQwR+LCG2BgCUmaGcTe9qZCFsmw8TMg9iG75HOwhrJCX9TCJRLH+Yzqg==",+ "version": "4.3.0",+ "resolved": "https://registry.npmjs.org/@smithy/util-waiter/-/util-waiter-4.3.0.tgz",+ "integrity": "sha512-JyjYmLAfS+pdxF92o4yLgEoy0zhayKTw73FU1aofLWwLcJw7iSqIY2exGmMTrl/lmZugP5p/zxdFSippJDfKWA==","license": "Apache-2.0","dependencies": {- "@smithy/abort-controller": "^4.2.8",- "@smithy/types": "^4.12.0",+ "@smithy/types": "^4.14.1","tslib": "^2.6.2"},"engines": {@@ -44305,7 +44413,9 @@"peerDependencies": {"@anthropic-ai/vertex-sdk": "^0.14.3","@aws-sdk/client-bedrock-runtime": "^3.1013.0",+ "@aws-sdk/client-cloudfront": "^3.1042.0","@aws-sdk/client-s3": "^3.980.0",+ "@aws-sdk/cloudfront-signer": "^3.1036.0","@azure/identity": "^4.13.1","@azure/search-documents": "^12.0.0","@azure/storage-blob": "^12.30.0",@@ -44328,6 +44438,7 @@"ioredis": "^5.3.2","js-yaml": "^4.1.1","jsonwebtoken": "^9.0.0",+ "jwks-rsa": "^3.2.0","keyv": "^5.3.2","keyv-file": "^5.1.2","librechat-data-provider": "*",diff --git a/packages/api/package.json b/packages/api/package.jsonindex ca3f4fd868..6a8a408a97 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -25,7 +25,7 @@"test:cache-integration:mcp": "jest --testPathPatterns=\"src/mcp/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false","test:cache-integration:stream": "jest --testPathPatterns=\"src/stream/.*\\.stream_integration\\.spec\\.ts$\" --coverage=false --runInBand --forceExit","test:cache-integration": "npm run test:cache-integration:core && npm run test:cache-integration:cluster && npm run test:cache-integration:mcp && npm run test:cache-integration:stream",- "test:s3-integration": "jest --testPathPatterns=\"src/storage/s3/.*\\.s3_integration\\.spec\\.ts$\" --coverage=false --runInBand",+ "test:s3-integration": "jest --testPathPatterns=\"src/storage/s3/.*\\.integration\\.spec\\.ts$\" --coverage=false --runInBand","verify": "npm run test:ci","b:clean": "bun run rimraf dist","b:build": "bun run b:clean && bun run rollup -c --silent --bundleConfigAsCjs",@@ -90,7 +90,9 @@"peerDependencies": {"@anthropic-ai/vertex-sdk": "^0.14.3","@aws-sdk/client-bedrock-runtime": "^3.1013.0",+ "@aws-sdk/client-cloudfront": "^3.1042.0","@aws-sdk/client-s3": "^3.980.0",+ "@aws-sdk/cloudfront-signer": "^3.1036.0","@azure/identity": "^4.13.1","@azure/search-documents": "^12.0.0","@azure/storage-blob": "^12.30.0",diff --git a/packages/api/src/app/__tests__/cdn.test.ts b/packages/api/src/app/__tests__/cdn.test.tsnew file mode 100644index 0000000000..cc85fb594c--- /dev/null+++ b/packages/api/src/app/__tests__/cdn.test.ts@@ -0,0 +1,133 @@+import { FileSources } from 'librechat-data-provider';++jest.mock('@librechat/data-schemas', () => ({+ logger: { error: jest.fn(), warn: jest.fn(), info: jest.fn() },+}));++jest.mock('~/cdn/firebase', () => ({+ initializeFirebase: jest.fn(),+}));++jest.mock('~/cdn/azure', () => ({+ initializeAzureBlobService: jest.fn().mockResolvedValue(undefined),+}));++jest.mock('~/cdn/s3', () => ({+ initializeS3: jest.fn(),+}));++jest.mock('~/cdn/cloudfront', () => ({+ initializeCloudFront: jest.fn(),+}));++import type { AppConfig } from '@librechat/data-schemas';+import { initializeFileStorage } from '../cdn';+import { initializeFirebase } from '~/cdn/firebase';+import { initializeAzureBlobService } from '~/cdn/azure';+import { initializeS3 } from '~/cdn/s3';+import { initializeCloudFront } from '~/cdn/cloudfront';++const baseAppConfig: AppConfig = {+ config: {},+ fileStrategy: FileSources.local,+ imageOutputType: 'png',+};++describe('initializeFileStorage', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ it('initializes S3 when fileStrategy is s3', () => {+ const appConfig = { ...baseAppConfig, fileStrategy: FileSources.s3 } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeS3).toHaveBeenCalledTimes(1);+ expect(initializeFirebase).not.toHaveBeenCalled();+ expect(initializeCloudFront).not.toHaveBeenCalled();+ });++ it('initializes Firebase when fileStrategy is firebase', () => {+ const appConfig = { ...baseAppConfig, fileStrategy: FileSources.firebase } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeFirebase).toHaveBeenCalledTimes(1);+ expect(initializeS3).not.toHaveBeenCalled();+ expect(initializeCloudFront).not.toHaveBeenCalled();+ });++ it('initializes strategy from fileStrategies when fileStrategy is local', () => {+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.local,+ fileStrategies: { avatar: FileSources.s3 },+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeS3).toHaveBeenCalledTimes(1);+ expect(initializeFirebase).not.toHaveBeenCalled();+ expect(initializeCloudFront).not.toHaveBeenCalled();+ });++ it('does not initialize S3 twice when fileStrategy and fileStrategies both use s3', () => {+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.s3,+ fileStrategies: { image: FileSources.s3 },+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeS3).toHaveBeenCalledTimes(1);+ });++ it('initializes multiple different strategies from fileStrategies', () => {+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.s3,+ fileStrategies: { avatar: FileSources.firebase },+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeS3).toHaveBeenCalledTimes(1);+ expect(initializeFirebase).toHaveBeenCalledTimes(1);+ });++ it('initializes CloudFront with config when fileStrategy is cloudfront', () => {+ const cloudfrontConfig = { domain: 'https://d123.cloudfront.net' };+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.cloudfront,+ cloudfront: cloudfrontConfig,+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeCloudFront).toHaveBeenCalledTimes(1);+ expect(initializeCloudFront).toHaveBeenCalledWith(cloudfrontConfig);+ });++ it('logs an error and does not initialize CloudFront when cloudfront config is absent', () => {+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.cloudfront,+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeCloudFront).not.toHaveBeenCalled();+ });++ it('initializes CloudFront from fileStrategies when fileStrategy is local, but avatar is configured for CloudFront', () => {+ const cloudfrontConfig = { domain: 'https://d123.cloudfront.net' };+ const appConfig = {+ ...baseAppConfig,+ fileStrategy: FileSources.local,+ fileStrategies: { avatar: FileSources.cloudfront },+ cloudfront: cloudfrontConfig,+ } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeCloudFront).toHaveBeenCalledTimes(1);+ expect(initializeCloudFront).toHaveBeenCalledWith(cloudfrontConfig);+ expect(initializeS3).not.toHaveBeenCalled();+ });++ it('does not call any initializer when fileStrategy is local with no fileStrategies', () => {+ const appConfig = { ...baseAppConfig, fileStrategy: FileSources.local } as AppConfig;+ initializeFileStorage(appConfig);+ expect(initializeS3).not.toHaveBeenCalled();+ expect(initializeFirebase).not.toHaveBeenCalled();+ expect(initializeAzureBlobService).not.toHaveBeenCalled();+ expect(initializeCloudFront).not.toHaveBeenCalled();+ });+});diff --git a/packages/api/src/app/cdn.ts b/packages/api/src/app/cdn.tsindex 451eeb8897..9feb606cfb 100644--- a/packages/api/src/app/cdn.ts+++ b/packages/api/src/app/cdn.ts@@ -4,23 +4,56 @@ import type { AppConfig } from '@librechat/data-schemas';import { initializeAzureBlobService } from '~/cdn/azure';import { initializeFirebase } from '~/cdn/firebase';import { initializeS3 } from '~/cdn/s3';+import { initializeCloudFront } from '~/cdn/cloudfront';-/**- * Initializes file storage clients based on the configured file strategy.- * This should be called after loading the app configuration.- * @param {Object} options- * @param {AppConfig} options.appConfig - The application configuration- */-export function initializeFileStorage(appConfig: AppConfig) {- const { fileStrategy } = appConfig;-- if (fileStrategy === FileSources.firebase) {+function initializeStrategy(strategy: FileSources, appConfig: AppConfig): void {+ if (strategy === FileSources.firebase) {initializeFirebase();- } else if (fileStrategy === FileSources.azure_blob) {+ } else if (strategy === FileSources.azure_blob) {initializeAzureBlobService().catch((error) => {logger.error('Error initializing Azure Blob Service:', error);});- } else if (fileStrategy === FileSources.s3) {+ } else if (strategy === FileSources.s3) {initializeS3();+ } else if (strategy === FileSources.cloudfront) {+ const cloudfrontConfig = appConfig.cloudfront;+ if (!cloudfrontConfig) {+ logger.error(+ '[initializeFileStorage] CloudFront strategy requires cloudfront config in librechat.yaml',+ );+ return;+ }+ const initialized = initializeCloudFront(cloudfrontConfig);+ if (!initialized) {+ logger.error(+ '[initializeFileStorage] CloudFront initialization failed. CloudFront operations will not work.',+ );+ }+ }+}++/**+ * Initializes file storage clients based on the configured file strategies.+ * Handles both the main fileStrategy and granular fileStrategies config.+ */+export function initializeFileStorage(appConfig: AppConfig): void {+ const { fileStrategy, fileStrategies } = appConfig;++ const strategiesToInit = new Set<FileSources>();++ if (fileStrategy) {+ strategiesToInit.add(fileStrategy);+ }++ if (fileStrategies) {+ for (const value of Object.values(fileStrategies)) {+ if (value) {+ strategiesToInit.add(value);+ }+ }+ }++ for (const strategy of strategiesToInit) {+ initializeStrategy(strategy, appConfig);}}diff --git a/packages/api/src/cdn/__tests__/cloudfront-cookies.test.ts b/packages/api/src/cdn/__tests__/cloudfront-cookies.test.tsnew file mode 100644index 0000000000..73f0e25872--- /dev/null+++ b/packages/api/src/cdn/__tests__/cloudfront-cookies.test.ts@@ -0,0 +1,407 @@+import type { CloudfrontSignInput } from '@aws-sdk/cloudfront-signer';++const mockGetCloudFrontConfig = jest.fn();+const mockGetSignedCookies = jest.fn();++jest.mock('~/cdn/cloudfront', () => ({+ getCloudFrontConfig: () => mockGetCloudFrontConfig(),+}));++jest.mock('@aws-sdk/cloudfront-signer', () => ({+ getSignedCookies: (params: CloudfrontSignInput) => mockGetSignedCookies(params),+}));++jest.mock('@librechat/data-schemas', () => ({+ logger: { warn: jest.fn(), error: jest.fn(), info: jest.fn(), debug: jest.fn() },+}));++import type { Response } from 'express';+import { setCloudFrontCookies, clearCloudFrontCookies } from '../cloudfront-cookies';++const { logger: mockLogger } = jest.requireMock('@librechat/data-schemas') as {+ logger: { warn: jest.Mock; error: jest.Mock; info: jest.Mock; debug: jest.Mock };+};++describe('setCloudFrontCookies', () => {+ let mockRes: Partial<Response>;+ let cookieArgs: Array<[string, string, object]>;++ beforeEach(() => {+ jest.clearAllMocks();+ cookieArgs = [];+ mockRes = {+ cookie: jest.fn((name: string, value: string, options: object) => {+ cookieArgs.push([name, value, options]);+ return mockRes as Response;+ }) as unknown as Response['cookie'],+ };+ });++ it('returns false when CloudFront config is null', () => {+ mockGetCloudFrontConfig.mockReturnValue(null);++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ });++ it('returns false when imageSigning is not "cookies"', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'none',+ cookieDomain: '.example.com',+ privateKey: 'test-key',+ keyPairId: 'K123',+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ });++ it('returns false when signing keys are missing', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ privateKey: null,+ keyPairId: null,+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ });++ it('returns false when cookieDomain is missing', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ });++ it('uses default expiry of 1800s when cookieExpiry is missing from config (Zod default not applied)', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ // cookieExpiry intentionally absent — simulates raw YAML without Zod defaults+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({+ 'CloudFront-Policy': 'policy-value',+ 'CloudFront-Signature': 'signature-value',+ 'CloudFront-Key-Pair-Id': 'K123ABC',+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(true);+ expect(mockLogger.warn).not.toHaveBeenCalled();+ const [, , options] = cookieArgs[0];+ expect((options as { expires: Date }).expires).toBeInstanceOf(Date);+ expect(isNaN((options as { expires: Date }).expires.getTime())).toBe(false);+ });++ it('sets three CloudFront cookies when enabled', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({+ 'CloudFront-Policy': 'policy-value',+ 'CloudFront-Signature': 'signature-value',+ 'CloudFront-Key-Pair-Id': 'K123ABC',+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(true);+ expect(mockRes.cookie).toHaveBeenCalledTimes(3);++ const cookieNames = cookieArgs.map(([name]) => name);+ expect(cookieNames).toContain('CloudFront-Policy');+ expect(cookieNames).toContain('CloudFront-Signature');+ expect(cookieNames).toContain('CloudFront-Key-Pair-Id');+ });++ it('uses cookieDomain from config with path', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({+ 'CloudFront-Policy': 'policy-value',+ 'CloudFront-Signature': 'signature-value',+ 'CloudFront-Key-Pair-Id': 'K123ABC',+ });++ setCloudFrontCookies(mockRes as Response);++ const [, , options] = cookieArgs[0];+ expect(options).toMatchObject({+ httpOnly: true,+ secure: true,+ sameSite: 'none',+ domain: '.example.com',+ path: '/images',+ });+ });++ it('builds correct custom policy for images resource', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({+ 'CloudFront-Policy': 'policy-value',+ 'CloudFront-Signature': 'signature-value',+ 'CloudFront-Key-Pair-Id': 'K123ABC',+ });++ setCloudFrontCookies(mockRes as Response);++ expect(mockGetSignedCookies).toHaveBeenCalledWith(+ expect.objectContaining({+ keyPairId: 'K123ABC',+ privateKey: expect.stringContaining('BEGIN RSA PRIVATE KEY'),+ policy: expect.stringContaining('https://cdn.example.com/images/*'),+ }),+ );+ });++ it('handles multiple trailing slashes in domain', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com///',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({+ 'CloudFront-Policy': 'policy-value',+ 'CloudFront-Signature': 'signature-value',+ 'CloudFront-Key-Pair-Id': 'K123ABC',+ });++ setCloudFrontCookies(mockRes as Response);++ expect(mockGetSignedCookies).toHaveBeenCalledWith(+ expect.objectContaining({+ policy: expect.stringContaining('https://cdn.example.com/images/*'),+ }),+ );+ });++ it('returns false when getSignedCookies returns empty object', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({});++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining('Missing expected cookie from AWS SDK'),+ );+ });++ it('returns false when getSignedCookies returns partial result', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----',+ keyPairId: 'K123ABC',+ });++ mockGetSignedCookies.mockReturnValue({ 'CloudFront-Policy': 'policy-value' });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ });++ it('returns false and logs error on signing error', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieExpiry: 1800,+ cookieDomain: '.example.com',+ privateKey: 'invalid-key',+ keyPairId: 'K123ABC',+ });++ const signingError = new Error('Invalid private key');+ mockGetSignedCookies.mockImplementation(() => {+ throw signingError;+ });++ const result = setCloudFrontCookies(mockRes as Response);++ expect(result).toBe(false);+ expect(mockRes.cookie).not.toHaveBeenCalled();+ expect(mockLogger.error).toHaveBeenCalledWith(+ '[setCloudFrontCookies] Failed to generate signed cookies:',+ signingError,+ );+ });+});++describe('clearCloudFrontCookies', () => {+ let mockRes: Partial<Response>;+ let clearedCookies: Array<[string, object]>;++ beforeEach(() => {+ jest.clearAllMocks();+ clearedCookies = [];+ mockRes = {+ clearCookie: jest.fn((name: string, options: object) => {+ clearedCookies.push([name, options]);+ return mockRes as Response;+ }) as unknown as Response['clearCookie'],+ };+ });++ it('does nothing when config is null', () => {+ mockGetCloudFrontConfig.mockReturnValue(null);++ clearCloudFrontCookies(mockRes as Response);++ expect(mockRes.clearCookie).not.toHaveBeenCalled();+ });++ it('does nothing when imageSigning is not "cookies"', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'none',+ cookieDomain: '.example.com',+ });++ clearCloudFrontCookies(mockRes as Response);++ expect(mockRes.clearCookie).not.toHaveBeenCalled();+ });++ it('does nothing when cookieDomain is missing', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ });++ clearCloudFrontCookies(mockRes as Response);++ expect(mockRes.clearCookie).not.toHaveBeenCalled();+ });++ it('clears all three CloudFront cookies with correct domain', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ privateKey: 'test-key',+ keyPairId: 'K123',+ });++ clearCloudFrontCookies(mockRes as Response);++ expect(mockRes.clearCookie).toHaveBeenCalledTimes(3);++ const expectedOptions = {+ domain: '.example.com',+ path: '/images',+ httpOnly: true,+ secure: true,+ sameSite: 'none',+ };+ expect(clearedCookies).toContainEqual(['CloudFront-Policy', expectedOptions]);+ expect(clearedCookies).toContainEqual(['CloudFront-Signature', expectedOptions]);+ expect(clearedCookies).toContainEqual(['CloudFront-Key-Pair-Id', expectedOptions]);+ });++ it('clears cookies with full security attributes matching set path', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ privateKey: 'test-key',+ keyPairId: 'K123',+ });++ clearCloudFrontCookies(mockRes as Response);++ expect(mockRes.clearCookie).toHaveBeenCalledTimes(3);++ const expectedOptions = {+ domain: '.example.com',+ path: '/images',+ httpOnly: true,+ secure: true,+ sameSite: 'none',+ };+ expect(clearedCookies).toContainEqual(['CloudFront-Policy', expectedOptions]);+ expect(clearedCookies).toContainEqual(['CloudFront-Signature', expectedOptions]);+ expect(clearedCookies).toContainEqual(['CloudFront-Key-Pair-Id', expectedOptions]);+ });++ it('logs warning and does not throw when clearing fails', () => {+ mockGetCloudFrontConfig.mockReturnValue({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ privateKey: 'test-key',+ keyPairId: 'K123',+ });++ const clearError = new Error('Cookie clear failed');+ mockRes.clearCookie = jest.fn(() => {+ throw clearError;+ }) as unknown as Response['clearCookie'];++ expect(() => clearCloudFrontCookies(mockRes as Response)).not.toThrow();+ expect(mockLogger.warn).toHaveBeenCalledWith(+ '[clearCloudFrontCookies] Failed to clear cookies:',+ clearError,+ );+ });+});diff --git a/packages/api/src/cdn/__tests__/cloudfront.test.ts b/packages/api/src/cdn/__tests__/cloudfront.test.tsnew file mode 100644index 0000000000..bcdf202fe6--- /dev/null+++ b/packages/api/src/cdn/__tests__/cloudfront.test.ts@@ -0,0 +1,182 @@+import type { CloudFrontConfig } from 'librechat-data-provider';++const mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn() };+const mockInitializeS3 = jest.fn();++jest.mock('@librechat/data-schemas', () => ({+ logger: mockLogger,+}));++jest.mock('../s3', () => ({+ initializeS3: mockInitializeS3,+}));++type RequiredCloudFrontConfig = NonNullable<CloudFrontConfig>;++/** Build a fully-typed config object, filling in all Zod-defaulted fields. */+function makeConfig(overrides: Partial<RequiredCloudFrontConfig> = {}): RequiredCloudFrontConfig {+ return {+ domain: 'https://d123.cloudfront.net',+ invalidateOnDelete: false,+ imageSigning: 'none',+ urlExpiry: 3600,+ cookieExpiry: 1800,+ ...overrides,+ };+}++describe('CloudFront CDN module', () => {+ beforeEach(() => {+ jest.resetModules();+ jest.clearAllMocks();+ mockInitializeS3.mockReturnValue({});+ delete process.env.CLOUDFRONT_KEY_PAIR_ID;+ delete process.env.CLOUDFRONT_PRIVATE_KEY;+ });++ async function load() {+ jest.mock('@librechat/data-schemas', () => ({ logger: mockLogger }));+ jest.mock('../s3', () => ({ initializeS3: mockInitializeS3 }));+ return import('../cloudfront');+ }++ describe('initializeCloudFront', () => {+ it('returns false when domain is not provided', async () => {+ const { initializeCloudFront } = await load();+ expect(initializeCloudFront({} as never)).toBe(false); // intentionally invalid input to test runtime guard+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining('[initializeCloudFront] CloudFront domain is required'),+ );+ });++ it('returns false when S3 is not initialized', async () => {+ mockInitializeS3.mockReturnValue(null);+ const { initializeCloudFront } = await load();+ expect(initializeCloudFront(makeConfig())).toBe(false);+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining('[initializeCloudFront] S3 must be initialized'),+ );+ });++ it('returns true and logs without signing keys when keys are absent', async () => {+ const { initializeCloudFront } = await load();+ expect(initializeCloudFront(makeConfig())).toBe(true);+ expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('without signing keys'));+ });++ it('returns true without signing-key warnings when keys are set and imageSigning is "none"', async () => {+ process.env.CLOUDFRONT_KEY_PAIR_ID = 'K123';+ process.env.CLOUDFRONT_PRIVATE_KEY =+ '-----BEGIN RSA PRIVATE KEY-----\ntest\n-----END RSA PRIVATE KEY-----';+ const { initializeCloudFront } = await load();+ expect(initializeCloudFront(makeConfig())).toBe(true);+ expect(mockLogger.warn).not.toHaveBeenCalledWith(+ expect.stringContaining('Signing keys are configured'),+ );+ expect(mockLogger.info).not.toHaveBeenCalledWith(+ expect.stringContaining('without signing keys'),+ );+ });++ it('returns true immediately when already initialized (no re-init)', async () => {+ const { initializeCloudFront } = await load();+ initializeCloudFront(makeConfig());+ jest.clearAllMocks();+ expect(initializeCloudFront(makeConfig({ domain: 'https://different.cloudfront.net' }))).toBe(+ true,+ );+ expect(mockInitializeS3).not.toHaveBeenCalled();+ expect(mockLogger.error).not.toHaveBeenCalled();+ });++ it('logs cache invalidation message when invalidateOnDelete is enabled', async () => {+ const { initializeCloudFront } = await load();+ initializeCloudFront(makeConfig({ distributionId: 'E123ABC', invalidateOnDelete: true }));+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining('Cache invalidation on delete enabled'),+ );+ });++ it('does not log cache invalidation message when invalidateOnDelete is false', async () => {+ const { initializeCloudFront } = await load();+ initializeCloudFront(makeConfig({ invalidateOnDelete: false }));+ expect(mockLogger.info).not.toHaveBeenCalledWith(+ expect.stringContaining('Cache invalidation'),+ );+ });++ it('returns false and errors when imageSigning is "cookies" but signing keys are missing', async () => {+ const { initializeCloudFront } = await load();+ const result = initializeCloudFront(makeConfig({ imageSigning: 'cookies' }));+ expect(result).toBe(false);+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining(+ '[initializeCloudFront] imageSigning="cookies" requires CLOUDFRONT_KEY_PAIR_ID',+ ),+ );+ });++ it('logs info when imageSigning is "cookies" and signing keys are present', async () => {+ process.env.CLOUDFRONT_KEY_PAIR_ID = 'K123';+ process.env.CLOUDFRONT_PRIVATE_KEY = 'my-private-key';+ const { initializeCloudFront } = await load();+ initializeCloudFront(makeConfig({ imageSigning: 'cookies' }));+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining('CloudFront cookie signing enabled'),+ );+ });++ it('warns when imageSigning is "url"', async () => {+ const { initializeCloudFront } = await load();+ initializeCloudFront(makeConfig({ imageSigning: 'url' }));+ expect(mockLogger.warn).toHaveBeenCalledWith(+ expect.stringContaining(+ '[initializeCloudFront] imageSigning="url" is configured but not yet implemented',+ ),+ );+ });+ });++ describe('getCloudFrontConfig', () => {+ it('returns null before initialization', async () => {+ const { getCloudFrontConfig } = await load();+ expect(getCloudFrontConfig()).toBeNull();+ });++ it('returns config with domain after initialization', async () => {+ const { initializeCloudFront, getCloudFrontConfig } = await load();+ initializeCloudFront(makeConfig());+ expect(getCloudFrontConfig()?.domain).toBe('https://d123.cloudfront.net');+ });++ it('returns config with null signing keys when env vars absent', async () => {+ const { initializeCloudFront, getCloudFrontConfig } = await load();+ initializeCloudFront(makeConfig());+ const config = getCloudFrontConfig();+ expect(config?.privateKey).toBeNull();+ expect(config?.keyPairId).toBeNull();+ });++ it('returns config with signing keys embedded when env vars are set', async () => {+ process.env.CLOUDFRONT_KEY_PAIR_ID = 'K456';+ process.env.CLOUDFRONT_PRIVATE_KEY = 'my-private-key';+ const { initializeCloudFront, getCloudFrontConfig } = await load();+ initializeCloudFront(makeConfig());+ const config = getCloudFrontConfig();+ expect(config?.keyPairId).toBe('K456');+ expect(config?.privateKey).toBe('my-private-key');+ });++ it('returns config with urlExpiry when provided', async () => {+ const { initializeCloudFront, getCloudFrontConfig } = await load();+ initializeCloudFront(makeConfig({ urlExpiry: 7200 }));+ expect(getCloudFrontConfig()?.urlExpiry).toBe(7200);+ });++ it('persists same config on second getCloudFrontConfig call', async () => {+ const { initializeCloudFront, getCloudFrontConfig } = await load();+ initializeCloudFront(makeConfig());+ expect(getCloudFrontConfig()).toBe(getCloudFrontConfig());+ });+ });+});diff --git a/packages/api/src/cdn/cloudfront-cookies.ts b/packages/api/src/cdn/cloudfront-cookies.tsnew file mode 100644index 0000000000..8ed23dc1d1--- /dev/null+++ b/packages/api/src/cdn/cloudfront-cookies.ts@@ -0,0 +1,109 @@+import { logger } from '@librechat/data-schemas';+import { getSignedCookies } from '@aws-sdk/cloudfront-signer';++import type { Response } from 'express';++import { getCloudFrontConfig } from './cloudfront';++const DEFAULT_COOKIE_EXPIRY = 1800;++const REQUIRED_CF_COOKIES = [+ 'CloudFront-Policy',+ 'CloudFront-Signature',+ 'CloudFront-Key-Pair-Id',+] as const;++/**+ * Clears CloudFront signed cookies from the response.+ * Should be called during logout to revoke CDN access.+ */+export function clearCloudFrontCookies(res: Response): void {+ try {+ const config = getCloudFrontConfig();+ if (!config?.cookieDomain || config.imageSigning !== 'cookies') {+ return;+ }+ const options = {+ domain: config.cookieDomain,+ path: '/images',+ httpOnly: true,+ secure: true,+ sameSite: 'none' as const,+ };+ res.clearCookie('CloudFront-Policy', options);+ res.clearCookie('CloudFront-Signature', options);+ res.clearCookie('CloudFront-Key-Pair-Id', options);+ } catch (error) {+ logger.warn('[clearCloudFrontCookies] Failed to clear cookies:', error);+ }+}++/**+ * Sets CloudFront signed cookies on the response for CDN access.+ * Returns true if cookies were set, false if CloudFront cookies are not enabled.+ */+export function setCloudFrontCookies(res: Response): boolean {+ const config = getCloudFrontConfig();+ if (+ !config ||+ config.imageSigning !== 'cookies' ||+ !config.privateKey ||+ !config.keyPairId ||+ !config.cookieDomain+ ) {+ return false;+ }++ try {+ const cookieExpiry = config.cookieExpiry ?? DEFAULT_COOKIE_EXPIRY;+ const expiresAtMs = Date.now() + cookieExpiry * 1000;+ const expiresAt = new Date(expiresAtMs);+ const expiresAtEpoch = Math.floor(expiresAtMs / 1000);++ const resourceUrl = `${config.domain.replace(/\/+$/, '')}/images/*`;++ const policy = JSON.stringify({+ Statement: [+ {+ Resource: resourceUrl,+ Condition: {+ DateLessThan: {+ 'AWS:EpochTime': expiresAtEpoch,+ },+ },+ },+ ],+ });++ const signedCookies = getSignedCookies({+ keyPairId: config.keyPairId,+ privateKey: config.privateKey,+ policy,+ });++ const cookieOptions = {+ expires: expiresAt,+ httpOnly: true,+ secure: true,+ sameSite: 'none' as const,+ domain: config.cookieDomain,+ path: '/images',+ };++ for (const key of REQUIRED_CF_COOKIES) {+ if (!signedCookies[key]) {+ logger.error(`[setCloudFrontCookies] Missing expected cookie from AWS SDK: ${key}`);+ return false;+ }+ }++ for (const key of REQUIRED_CF_COOKIES) {+ res.cookie(key, signedCookies[key], cookieOptions);+ }++ return true;+ } catch (error) {+ logger.error('[setCloudFrontCookies] Failed to generate signed cookies:', error);+ return false;+ }+}diff --git a/packages/api/src/cdn/cloudfront.ts b/packages/api/src/cdn/cloudfront.tsnew file mode 100644index 0000000000..4bf56de43c--- /dev/null+++ b/packages/api/src/cdn/cloudfront.ts@@ -0,0 +1,66 @@+import { logger } from '@librechat/data-schemas';+import type { CloudFrontConfig } from 'librechat-data-provider';+import { initializeS3 } from './s3';++export interface CloudFrontFullConfig extends NonNullable<CloudFrontConfig> {+ privateKey: string | null;+ keyPairId: string | null;+}++let cloudFrontConfig: CloudFrontFullConfig | null = null;++export function initializeCloudFront(config: CloudFrontConfig): boolean {+ if (cloudFrontConfig) {+ logger.debug('[initializeCloudFront] Already initialized; skipping re-initialization.');+ return true;+ }++ if (!config?.domain) {+ logger.error('[initializeCloudFront] CloudFront domain is required in config.');+ return false;+ }++ const s3 = initializeS3();+ if (!s3) {+ logger.error('[initializeCloudFront] S3 must be initialized for CloudFront to work.');+ return false;+ }++ const keyPairId = process.env.CLOUDFRONT_KEY_PAIR_ID ?? null;+ const privateKey = process.env.CLOUDFRONT_PRIVATE_KEY ?? null;++ if (config.imageSigning === 'cookies' && (!keyPairId || !privateKey)) {+ logger.error(+ '[initializeCloudFront] imageSigning="cookies" requires CLOUDFRONT_KEY_PAIR_ID and CLOUDFRONT_PRIVATE_KEY env vars.',+ );+ return false;+ }++ cloudFrontConfig = { ...config, privateKey, keyPairId };++ if (config.imageSigning === 'cookies') {+ logger.info(+ '[initializeCloudFront] CloudFront cookie signing enabled. Cookies will be set during auth.',+ );+ } else if (config.imageSigning === 'url') {+ logger.warn(+ '[initializeCloudFront] imageSigning="url" is configured but not yet implemented for images.',+ );+ }++ if (!keyPairId || !privateKey) {+ logger.info(+ '[initializeCloudFront] CloudFront initialized without signing keys (public OAC only).',+ );+ }++ if (config.invalidateOnDelete) {+ logger.info('[initializeCloudFront] Cache invalidation on delete enabled.');+ }++ return true;+}++export function getCloudFrontConfig(): Readonly<CloudFrontFullConfig> | null {+ return cloudFrontConfig;+}diff --git a/packages/api/src/cdn/index.ts b/packages/api/src/cdn/index.tsindex 04be850216..69febb17d9 100644--- a/packages/api/src/cdn/index.ts+++ b/packages/api/src/cdn/index.ts@@ -1,3 +1,5 @@export * from './azure';+export * from './cloudfront';+export * from './cloudfront-cookies';export * from './firebase';export * from './s3';diff --git a/packages/api/src/storage/__tests__/images.test.ts b/packages/api/src/storage/__tests__/images.test.tsnew file mode 100644index 0000000000..9d151a1044--- /dev/null+++ b/packages/api/src/storage/__tests__/images.test.ts@@ -0,0 +1,309 @@+import fs from 'fs';+import sharp from 'sharp';+import type { ServerRequest } from '~/types';+import type { SaveBufferFn } from '~/storage/types';+import type { ImageServiceDeps } from '~/storage/images';+import { ImageService } from '~/storage/images';++jest.mock('fs', () => {+ const actualFs = jest.requireActual<typeof import('fs')>('fs');+ return {+ ...actualFs,+ promises: {+ ...actualFs.promises,+ readFile: jest.fn(),+ unlink: jest.fn(),+ },+ };+});++jest.mock('sharp', () => {+ const mockSharp = jest.fn(() => ({+ metadata: jest.fn().mockResolvedValue({ format: 'png', width: 100, height: 100 }),+ toFormat: jest.fn().mockReturnThis(),+ toBuffer: jest.fn().mockResolvedValue(Buffer.from('processed')),+ }));+ return mockSharp;+});++describe('ImageService', () => {+ let mockSaveBuffer: jest.MockedFunction<SaveBufferFn>;+ let mockDeps: ImageServiceDeps;+ let service: ImageService;++ beforeEach(() => {+ jest.clearAllMocks();++ mockSaveBuffer = jest+ .fn()+ .mockResolvedValue('https://storage.example.com/images/user123/file.webp');++ mockDeps = {+ resizeImageBuffer: jest.fn().mockResolvedValue({+ buffer: Buffer.from('resized'),+ width: 800,+ height: 600,+ }),+ updateUser: jest.fn().mockResolvedValue(undefined),+ updateFile: jest.fn().mockResolvedValue(null),+ };++ service = new ImageService(mockSaveBuffer, mockDeps);+ });++ describe('uploadImage', () => {+ const mockReq = {+ user: { id: 'user123' },+ config: { imageOutputType: 'webp' },+ };++ const mockFile = {+ path: '/tmp/upload-123.jpg',+ originalname: 'photo.jpg',+ } as Express.Multer.File;++ beforeEach(() => {+ (fs.promises.readFile as jest.Mock).mockResolvedValue(Buffer.from('original'));+ (fs.promises.unlink as jest.Mock).mockResolvedValue(undefined);+ });++ it('uploads and processes an image successfully', async () => {+ const result = await service.uploadImage({+ req: mockReq as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ });++ expect(result).toEqual({+ filepath: 'https://storage.example.com/images/user123/file.webp',+ bytes: expect.any(Number),+ width: 800,+ height: 600,+ });++ expect(mockDeps.resizeImageBuffer).toHaveBeenCalledWith(expect.any(Buffer), 'high', 'openAI');++ expect(mockSaveBuffer).toHaveBeenCalledWith({+ userId: 'user123',+ buffer: expect.any(Buffer),+ fileName: expect.stringContaining('file-456__'),+ basePath: 'images',+ });++ expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/upload-123.jpg');+ });++ it('throws error when user not authenticated', async () => {+ const reqNoUser = { config: {} };++ await expect(+ service.uploadImage({+ req: reqNoUser as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ }),+ ).rejects.toThrow('User not authenticated');+ });++ it('skips format conversion when extension matches target', async () => {+ const webpFile = {+ path: '/tmp/upload-123.webp',+ originalname: 'photo.webp',+ } as Express.Multer.File;++ await service.uploadImage({+ req: mockReq as ServerRequest,+ file: webpFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ });++ expect(sharp).not.toHaveBeenCalled();+ });++ it('uses custom resolution when provided', async () => {+ await service.uploadImage({+ req: mockReq as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ resolution: 'low',+ });++ expect(mockDeps.resizeImageBuffer).toHaveBeenCalledWith(expect.any(Buffer), 'low', 'openAI');+ });++ it('uses custom basePath when provided', async () => {+ await service.uploadImage({+ req: mockReq as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ basePath: 'avatars',+ });++ expect(mockSaveBuffer).toHaveBeenCalledWith(expect.objectContaining({ basePath: 'avatars' }));+ });++ it('defaults to webp when imageOutputType not configured', async () => {+ const reqNoConfig = { user: { id: 'user123' }, config: {} };++ await service.uploadImage({+ req: reqNoConfig as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ });++ expect(mockSaveBuffer).toHaveBeenCalledWith(+ expect.objectContaining({+ fileName: expect.stringContaining('.webp'),+ }),+ );+ });++ it('deletes temp file when readFile throws', async () => {+ (fs.promises.readFile as jest.Mock).mockRejectedValueOnce(new Error('ENOENT'));++ await expect(+ service.uploadImage({+ req: mockReq as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ }),+ ).rejects.toThrow('ENOENT');++ expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/upload-123.jpg');+ });++ it('deletes temp file when resize throws', async () => {+ (fs.promises.readFile as jest.Mock).mockResolvedValueOnce(Buffer.from('raw'));+ (mockDeps.resizeImageBuffer as jest.Mock).mockRejectedValueOnce(new Error('Resize failed'));++ await expect(+ service.uploadImage({+ req: mockReq as ServerRequest,+ file: mockFile,+ file_id: 'file-456',+ endpoint: 'openAI',+ }),+ ).rejects.toThrow('Resize failed');++ expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/upload-123.jpg');+ });+ });++ describe('prepareImageURL', () => {+ it('updates file and returns the updated document alongside its filepath', async () => {+ const file = { file_id: 'file-123', filepath: 'https://example.com/image.webp' };++ const result = await service.prepareImageURL(file);++ expect(result).toEqual([null, 'https://example.com/image.webp']);+ expect(mockDeps.updateFile).toHaveBeenCalledWith({ file_id: 'file-123' });+ });++ it('returns the updated MongoFile as the first element when found', async () => {+ const mongoFile = { file_id: 'file-123', filepath: 'https://example.com/image.webp' };+ (mockDeps.updateFile as jest.Mock).mockResolvedValue(mongoFile);++ const file = { file_id: 'file-123', filepath: 'https://example.com/image.webp' };+ const result = await service.prepareImageURL(file);++ expect(result[0]).toEqual(mongoFile);+ expect(result[1]).toBe('https://example.com/image.webp');+ });+ });++ describe('processAvatar', () => {+ it('processes and uploads avatar for user', async () => {+ const buffer = Buffer.from('avatar-data');++ const result = await service.processAvatar({+ buffer,+ userId: 'user123',+ manual: 'true',+ });++ expect(result).toBe('https://storage.example.com/images/user123/file.webp');+ expect(mockSaveBuffer).toHaveBeenCalledWith({+ userId: 'user123',+ buffer,+ fileName: expect.stringMatching(/^avatar-\d+\.png$/),+ basePath: 'images',+ });+ expect(mockDeps.updateUser).toHaveBeenCalledWith('user123', {+ avatar: 'https://storage.example.com/images/user123/file.webp',+ });+ });++ it('does not update user when manual is false', async () => {+ const buffer = Buffer.from('avatar-data');++ await service.processAvatar({+ buffer,+ userId: 'user123',+ manual: 'false',+ });++ expect(mockDeps.updateUser).not.toHaveBeenCalled();+ });++ it('creates agent avatar with correct filename and skips user update', async () => {+ const buffer = Buffer.from('avatar-data');++ await service.processAvatar({+ buffer,+ userId: 'user123',+ manual: 'true',+ agentId: 'agent-456',+ });++ expect(mockSaveBuffer).toHaveBeenCalledWith(+ expect.objectContaining({+ fileName: expect.stringMatching(/^agent-agent-456-avatar-\d+\.png$/),+ }),+ );+ expect(mockDeps.updateUser).not.toHaveBeenCalled();+ });++ it('appends manual param when config.appendManualParam is true', async () => {+ const serviceWithManualParam = new ImageService(mockSaveBuffer, mockDeps, {+ appendManualParam: true,+ });++ const buffer = Buffer.from('avatar-data');++ const result = await serviceWithManualParam.processAvatar({+ buffer,+ userId: 'user123',+ manual: 'true',+ });++ expect(result).toBe('https://storage.example.com/images/user123/file.webp?manual=true');+ });++ it('uses gif extension for animated images', async () => {+ (sharp as unknown as jest.Mock).mockImplementationOnce(() => ({+ metadata: jest.fn().mockResolvedValue({ format: 'gif' }),+ }));++ const buffer = Buffer.from('gif-data');++ await service.processAvatar({+ buffer,+ userId: 'user123',+ manual: 'false',+ });++ expect(mockSaveBuffer).toHaveBeenCalledWith(+ expect.objectContaining({+ fileName: expect.stringMatching(/\.gif$/),+ }),+ );+ });+ });+});diff --git a/packages/api/src/storage/cloudfront/__tests__/crud.test.ts b/packages/api/src/storage/cloudfront/__tests__/crud.test.tsnew file mode 100644index 0000000000..e5da63e836--- /dev/null+++ b/packages/api/src/storage/cloudfront/__tests__/crud.test.ts@@ -0,0 +1,440 @@+import { Readable } from 'stream';+import type { TFile } from 'librechat-data-provider';+import type { CloudFrontFullConfig } from '~/cdn/cloudfront';+import type { ServerRequest } from '~/types';++const mockGetCloudFrontConfig = jest.fn<CloudFrontFullConfig | null, []>();+const mockGetS3Key = jest.fn<string, [string, string, string]>();+const mockSaveBufferToS3 = jest.fn();+const mockSaveURLToS3 = jest.fn();+const mockUploadFileToS3 = jest.fn();+const mockDeleteFileFromS3 = jest.fn();+const mockGetS3FileStream = jest.fn();+const mockExtractKeyFromS3Url = jest.fn<string, [string]>();+const mockCloudFrontSend = jest.fn();+const mockGetSignedUrl = jest.fn<string, [object]>();+const mockLogger = { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() };++jest.mock('~/cdn/cloudfront', () => ({+ getCloudFrontConfig: mockGetCloudFrontConfig,+}));++jest.mock('~/storage/s3/crud', () => ({+ getS3Key: mockGetS3Key,+ saveBufferToS3: mockSaveBufferToS3,+ saveURLToS3: mockSaveURLToS3,+ uploadFileToS3: mockUploadFileToS3,+ deleteFileFromS3: mockDeleteFileFromS3,+ getS3FileStream: mockGetS3FileStream,+ extractKeyFromS3Url: mockExtractKeyFromS3Url,+}));++jest.mock('@aws-sdk/cloudfront-signer', () => ({+ getSignedUrl: mockGetSignedUrl,+}));++jest.mock('@aws-sdk/client-cloudfront', () => ({+ CloudFrontClient: jest.fn().mockImplementation(() => ({ send: mockCloudFrontSend })),+ CreateInvalidationCommand: jest.fn().mockImplementation((input) => ({ input })),+}));++jest.mock('@librechat/data-schemas', () => ({ logger: mockLogger }));++jest.mock('~/storage/s3/s3Config', () => ({+ s3Config: { S3_URL_EXPIRY_SECONDS: 900, AWS_REGION: 'us-east-1' },+}));++function makeConfig(overrides: Partial<CloudFrontFullConfig> = {}): CloudFrontFullConfig {+ return {+ domain: 'https://d123.cloudfront.net',+ invalidateOnDelete: false,+ imageSigning: 'none',+ urlExpiry: 3600,+ cookieExpiry: 1800,+ privateKey: null,+ keyPairId: null,+ ...overrides,+ };+}++describe('CloudFront CRUD', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ mockGetS3Key.mockImplementation(+ (basePath, userId, fileName) => `${basePath}/${userId}/${fileName}`,+ );+ mockGetCloudFrontConfig.mockReturnValue(makeConfig());+ });++ describe('getCloudFrontURL', () => {+ it('returns plain CloudFront URL when sign is false (default)', async () => {+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({ userId: 'user1', fileName: 'photo.webp' });+ expect(url).toBe('https://d123.cloudfront.net/images/user1/photo.webp');+ expect(mockGetSignedUrl).not.toHaveBeenCalled();+ });++ it('uses custom basePath when provided', async () => {+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({+ userId: 'user1',+ fileName: 'doc.pdf',+ basePath: 'documents',+ });+ expect(url).toBe('https://d123.cloudfront.net/documents/user1/doc.pdf');+ });++ it('strips trailing slash from domain', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ domain: 'https://d123.cloudfront.net/' }),+ );+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({ userId: 'user1', fileName: 'photo.webp' });+ expect(url).toBe('https://d123.cloudfront.net/images/user1/photo.webp');+ });++ it('strips multiple trailing slashes from domain', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ domain: 'https://d123.cloudfront.net///' }),+ );+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({ userId: 'user1', fileName: 'photo.webp' });+ expect(url).toBe('https://d123.cloudfront.net/images/user1/photo.webp');+ });++ it('strips leading slash from S3 key', async () => {+ mockGetS3Key.mockReturnValue('/images/user1/photo.webp');+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({ userId: 'user1', fileName: 'photo.webp' });+ expect(url).toBe('https://d123.cloudfront.net/images/user1/photo.webp');+ });++ it('strips multiple leading slashes from S3 key', async () => {+ mockGetS3Key.mockReturnValue('///images/user1/photo.webp');+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({ userId: 'user1', fileName: 'photo.webp' });+ expect(url).toBe('https://d123.cloudfront.net/images/user1/photo.webp');+ });++ it('returns signed URL when sign is true', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ privateKey: 'pk-secret', keyPairId: 'K123' }),+ );+ mockGetSignedUrl.mockReturnValue(+ 'https://d123.cloudfront.net/doc.pdf?Policy=abc&Signature=xyz',+ );+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ const url = await getCloudFrontURL({+ userId: 'user1',+ fileName: 'doc.pdf',+ basePath: 'documents',+ sign: true,+ });+ expect(mockGetSignedUrl).toHaveBeenCalledWith(+ expect.objectContaining({+ url: 'https://d123.cloudfront.net/documents/user1/doc.pdf',+ keyPairId: 'K123',+ privateKey: 'pk-secret',+ dateLessThan: expect.any(String),+ }),+ );+ expect(url).toContain('Policy=abc');+ });++ it('uses urlExpiry from config for signed URL', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ privateKey: 'pk', keyPairId: 'K1', urlExpiry: 7200 }),+ );+ mockGetSignedUrl.mockReturnValue('https://d123.cloudfront.net/doc.pdf?signed');+ const before = Date.now();+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ await getCloudFrontURL({ userId: 'u', fileName: 'f.pdf', sign: true });+ const after = Date.now();++ const { dateLessThan } = mockGetSignedUrl.mock.calls[0][0] as { dateLessThan: string };+ const expiry = new Date(dateLessThan).getTime();+ expect(expiry).toBeGreaterThanOrEqual(before + 7200 * 1000);+ expect(expiry).toBeLessThanOrEqual(after + 7200 * 1000 + 100);+ });++ it('falls back to s3Config expiry when urlExpiry not set', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ privateKey: 'pk', keyPairId: 'K1', urlExpiry: undefined as never }), // intentionally invalid input to test runtime guard+ );+ mockGetSignedUrl.mockReturnValue('https://d123.cloudfront.net/doc.pdf?signed');+ const before = Date.now();+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ await getCloudFrontURL({ userId: 'u', fileName: 'f.pdf', sign: true });+ const after = Date.now();++ const { dateLessThan } = mockGetSignedUrl.mock.calls[0][0] as { dateLessThan: string };+ const expiry = new Date(dateLessThan).getTime();+ // 900s fallback from mocked s3Config+ expect(expiry).toBeGreaterThanOrEqual(before + 900 * 1000);+ expect(expiry).toBeLessThanOrEqual(after + 900 * 1000 + 100);+ });++ it('throws when CloudFront is not initialized', async () => {+ mockGetCloudFrontConfig.mockReturnValue(null);+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ await expect(getCloudFrontURL({ userId: 'u', fileName: 'f.png' })).rejects.toThrow(+ 'CloudFront not initialized',+ );+ });++ it('throws when signing requested but keys not configured', async () => {+ // config with no keys+ mockGetCloudFrontConfig.mockReturnValue(makeConfig({ privateKey: null, keyPairId: null }));+ const { getCloudFrontURL } = await import('~/storage/cloudfront/crud');+ await expect(+ getCloudFrontURL({ userId: 'u', fileName: 'doc.pdf', sign: true }),+ ).rejects.toThrow('Signing keys not configured');+ });+ });++ describe('saveBufferToCloudFront', () => {+ it('calls saveBufferToS3 with correct params and urlBuilder', async () => {+ mockSaveBufferToS3.mockResolvedValue('https://d123.cloudfront.net/images/u/f.webp');+ const { saveBufferToCloudFront } = await import('~/storage/cloudfront/crud');+ const result = await saveBufferToCloudFront({+ userId: 'u',+ buffer: Buffer.from('data'),+ fileName: 'f.webp',+ basePath: 'images',+ });++ expect(mockSaveBufferToS3).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'u',+ buffer: Buffer.from('data'),+ fileName: 'f.webp',+ basePath: 'images',+ urlBuilder: expect.any(Function),+ }),+ );+ expect(result).toBe('https://d123.cloudfront.net/images/u/f.webp');+ });++ it('passes sign=false to urlBuilder by default', async () => {+ let capturedUrlBuilder: ((p: object) => Promise<string>) | null = null;+ mockSaveBufferToS3.mockImplementation(+ ({ urlBuilder }: { urlBuilder: (p: object) => Promise<string> }) => {+ capturedUrlBuilder = urlBuilder;+ return Promise.resolve('https://d123.cloudfront.net/images/u/f.webp');+ },+ );++ const { saveBufferToCloudFront } = await import('~/storage/cloudfront/crud');+ await saveBufferToCloudFront({ userId: 'u', buffer: Buffer.from('x'), fileName: 'f.webp' });++ // urlBuilder invoked without sign should not call getSignedUrl+ await capturedUrlBuilder!({ userId: 'u', fileName: 'f.webp', basePath: 'images' });+ expect(mockGetSignedUrl).not.toHaveBeenCalled();+ });++ it('passes sign=true to urlBuilder when requested', async () => {+ mockGetCloudFrontConfig.mockReturnValue(makeConfig({ privateKey: 'pk', keyPairId: 'K1' }));+ mockGetSignedUrl.mockReturnValue('https://d123.cloudfront.net/images/u/f.webp?signed');++ let capturedUrlBuilder: ((p: object) => Promise<string>) | null = null;+ mockSaveBufferToS3.mockImplementation(+ ({ urlBuilder }: { urlBuilder: (p: object) => Promise<string> }) => {+ capturedUrlBuilder = urlBuilder;+ return Promise.resolve('https://d123.cloudfront.net/images/u/f.webp?signed');+ },+ );++ const { saveBufferToCloudFront } = await import('~/storage/cloudfront/crud');+ await saveBufferToCloudFront({+ userId: 'u',+ buffer: Buffer.from('x'),+ fileName: 'f.webp',+ sign: true,+ });++ await capturedUrlBuilder!({ userId: 'u', fileName: 'f.webp', basePath: 'images' });+ expect(mockGetSignedUrl).toHaveBeenCalled();+ });+ });++ describe('saveURLToCloudFront', () => {+ it('delegates to saveURLToS3 with a urlBuilder', async () => {+ mockSaveURLToS3.mockResolvedValue('https://d123.cloudfront.net/images/u/f.webp');+ const { saveURLToCloudFront } = await import('~/storage/cloudfront/crud');+ const result = await saveURLToCloudFront({+ userId: 'u',+ URL: 'https://external.com/image.jpg',+ fileName: 'f.webp',+ });++ expect(mockSaveURLToS3).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'u',+ URL: 'https://external.com/image.jpg',+ fileName: 'f.webp',+ urlBuilder: expect.any(Function),+ }),+ );+ expect(result).toBe('https://d123.cloudfront.net/images/u/f.webp');+ });+ });++ describe('uploadFileToCloudFront', () => {+ it('delegates to uploadFileToS3 with a urlBuilder', async () => {+ const uploadResult = { filepath: 'https://d123.cloudfront.net/images/u/f.pdf', bytes: 1024 };+ mockUploadFileToS3.mockResolvedValue(uploadResult);++ const mockReq = { user: { id: 'u' } } as ServerRequest;+ const mockFile = { path: '/tmp/f.pdf' } as Express.Multer.File;++ const { uploadFileToCloudFront } = await import('~/storage/cloudfront/crud');+ const result = await uploadFileToCloudFront({+ req: mockReq,+ file: mockFile,+ file_id: 'fid-1',+ });++ expect(mockUploadFileToS3).toHaveBeenCalledWith(+ expect.objectContaining({+ req: mockReq,+ file: mockFile,+ file_id: 'fid-1',+ urlBuilder: expect.any(Function),+ }),+ );+ expect(result).toEqual(uploadResult);+ });+ });++ describe('deleteFileFromCloudFront', () => {+ const mockReq = { user: { id: 'u' } } as ServerRequest;+ const mockFile = {+ file_id: 'fid-1',+ filepath: 'https://d123.cloudfront.net/images/u/file.webp',+ source: 'cloudfront',+ } as unknown as TFile;++ beforeEach(() => {+ mockDeleteFileFromS3.mockResolvedValue(undefined);+ mockExtractKeyFromS3Url.mockReturnValue('images/u/file.webp');+ });++ it('calls deleteFileFromS3 to remove the file', async () => {+ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);+ expect(mockDeleteFileFromS3).toHaveBeenCalledWith(mockReq, mockFile);+ });++ it('does not create invalidation when invalidateOnDelete is false', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: false, distributionId: 'E123' }),+ );+ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);+ expect(mockCloudFrontSend).not.toHaveBeenCalled();+ });++ it('does not create invalidation when distributionId is missing', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: true, distributionId: undefined }),+ );+ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);+ expect(mockCloudFrontSend).not.toHaveBeenCalled();+ });++ it('creates CloudFront invalidation when invalidateOnDelete is true', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: true, distributionId: 'E123ABC' }),+ );+ mockCloudFrontSend.mockResolvedValue({});+ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);++ expect(mockCloudFrontSend).toHaveBeenCalledTimes(1);+ const { CreateInvalidationCommand } = await import('@aws-sdk/client-cloudfront');+ expect(CreateInvalidationCommand).toHaveBeenCalledWith(+ expect.objectContaining({+ DistributionId: 'E123ABC',+ InvalidationBatch: expect.objectContaining({+ Paths: { Quantity: 1, Items: ['/images/u/file.webp'] },+ }),+ }),+ );+ });++ it('prefixes key with / for invalidation path', async () => {+ mockExtractKeyFromS3Url.mockReturnValue('images/u/file.webp'); // no leading slash+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: true, distributionId: 'E123' }),+ );+ mockCloudFrontSend.mockResolvedValue({});++ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);++ const { CreateInvalidationCommand } = await import('@aws-sdk/client-cloudfront');+ expect(CreateInvalidationCommand).toHaveBeenCalledWith(+ expect.objectContaining({+ InvalidationBatch: expect.objectContaining({+ Paths: expect.objectContaining({ Items: ['/images/u/file.webp'] }),+ }),+ }),+ );+ });++ it('does not re-prefix path that already has leading slash', async () => {+ mockExtractKeyFromS3Url.mockReturnValue('/images/u/file.webp'); // already has slash+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: true, distributionId: 'E123' }),+ );+ mockCloudFrontSend.mockResolvedValue({});++ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await deleteFileFromCloudFront(mockReq, mockFile);++ const { CreateInvalidationCommand } = await import('@aws-sdk/client-cloudfront');+ expect(CreateInvalidationCommand).toHaveBeenCalledWith(+ expect.objectContaining({+ InvalidationBatch: expect.objectContaining({+ Paths: expect.objectContaining({ Items: ['/images/u/file.webp'] }),+ }),+ }),+ );+ });++ it('logs error and continues when invalidation fails', async () => {+ mockGetCloudFrontConfig.mockReturnValue(+ makeConfig({ invalidateOnDelete: true, distributionId: 'E123' }),+ );+ mockCloudFrontSend.mockRejectedValue(new Error('Access denied'));++ const { deleteFileFromCloudFront } = await import('~/storage/cloudfront/crud');+ await expect(deleteFileFromCloudFront(mockReq, mockFile)).resolves.toBeUndefined();+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining('[deleteFileFromCloudFront] Cache invalidation failed:'),+ 'Access denied',+ );+ });+ });++ describe('getCloudFrontFileStream', () => {+ it('delegates to getS3FileStream', async () => {+ const readable = new Readable();+ mockGetS3FileStream.mockResolvedValue(readable);++ const mockReq = { user: { id: 'u' } } as ServerRequest;+ const { getCloudFrontFileStream } = await import('~/storage/cloudfront/crud');+ const result = await getCloudFrontFileStream(+ mockReq,+ 'https://d123.cloudfront.net/images/u/f.webp',+ );++ expect(mockGetS3FileStream).toHaveBeenCalledWith(+ mockReq,+ 'https://d123.cloudfront.net/images/u/f.webp',+ );+ expect(result).toBe(readable);+ });+ });+});diff --git a/packages/api/src/storage/cloudfront/crud.ts b/packages/api/src/storage/cloudfront/crud.tsnew file mode 100644index 0000000000..37e41f5fa4--- /dev/null+++ b/packages/api/src/storage/cloudfront/crud.ts@@ -0,0 +1,149 @@+import crypto from 'crypto';+import { logger } from '@librechat/data-schemas';+import { getSignedUrl } from '@aws-sdk/cloudfront-signer';+import { CloudFrontClient, CreateInvalidationCommand } from '@aws-sdk/client-cloudfront';+import type { TFile } from 'librechat-data-provider';+import type { Readable } from 'stream';+import type { ServerRequest } from '~/types';+import type {+ SaveBufferParams,+ GetURLParams,+ SaveURLParams,+ UploadFileParams,+ UploadResult,+} from '~/storage/types';+import { getCloudFrontConfig } from '~/cdn/cloudfront';+import { s3Config } from '~/storage/s3/s3Config';+import { DEFAULT_BASE_PATH as defaultBasePath } from '~/storage/constants';+import {+ getS3Key,+ saveBufferToS3,+ saveURLToS3,+ uploadFileToS3,+ deleteFileFromS3,+ getS3FileStream,+ extractKeyFromS3Url,+} from '~/storage/s3/crud';++let _cloudFrontClient: CloudFrontClient | null = null;++function getOrCreateCloudFrontClient(): CloudFrontClient {+ if (!_cloudFrontClient) {+ const region = s3Config.AWS_REGION || process.env.AWS_REGION;+ if (!region) {+ throw new Error('[CloudFront] AWS_REGION is required for cache invalidation');+ }+ _cloudFrontClient = new CloudFrontClient({ region });+ }+ return _cloudFrontClient;+}++export interface CloudFrontURLParams extends GetURLParams {+ sign?: boolean;+}++function buildCloudFrontUrl(s3Key: string): string {+ const config = getCloudFrontConfig();+ if (!config?.domain) {+ throw new Error('[buildCloudFrontUrl] CloudFront not initialized.');+ }+ const cleanDomain = config.domain.replace(/\/+$/, '');+ const cleanKey = s3Key.replace(/^\/+/, '');+ return `${cleanDomain}/${cleanKey}`;+}++function signUrl(url: string): string {+ const config = getCloudFrontConfig();+ if (!config?.privateKey || !config?.keyPairId) {+ throw new Error('[signUrl] Signing keys not configured.');+ }++ const expiry = config.urlExpiry ?? s3Config.S3_URL_EXPIRY_SECONDS;+ const dateLessThan = new Date(Date.now() + expiry * 1000).toISOString();++ return getSignedUrl({+ url,+ keyPairId: config.keyPairId,+ privateKey: config.privateKey,+ dateLessThan,+ });+}++/**+ * Get CloudFront URL for a file.+ * @param sign - If true, returns a signed URL. Caller (strategy) decides based on config.+ */+export async function getCloudFrontURL({+ userId,+ fileName,+ basePath = defaultBasePath,+ sign = false,+}: CloudFrontURLParams): Promise<string> {+ const key = getS3Key(basePath, userId, fileName);+ const url = buildCloudFrontUrl(key);+ return sign ? signUrl(url) : url;+}++/** Save buffer to S3 and return CloudFront URL. */+export async function saveBufferToCloudFront(+ params: SaveBufferParams & { sign?: boolean },+): Promise<string> {+ const { sign = false, ...rest } = params;+ return saveBufferToS3({ ...rest, urlBuilder: (p) => getCloudFrontURL({ ...p, sign }) });+}++/** Save file from URL to S3 and return CloudFront URL. */+export async function saveURLToCloudFront(+ params: SaveURLParams & { sign?: boolean },+): Promise<string> {+ const { sign = false, ...rest } = params;+ return saveURLToS3({ ...rest, urlBuilder: (p) => getCloudFrontURL({ ...p, sign }) });+}++/** Upload file to S3 and return CloudFront URL. */+export async function uploadFileToCloudFront(+ params: UploadFileParams & { sign?: boolean },+): Promise<UploadResult> {+ const { sign = false, ...rest } = params;+ return uploadFileToS3({ ...rest, urlBuilder: (p) => getCloudFrontURL({ ...p, sign }) });+}++/** Delete file from S3 and optionally invalidate CloudFront cache. */+export async function deleteFileFromCloudFront(req: ServerRequest, file: TFile): Promise<void> {+ const config = getCloudFrontConfig();++ await deleteFileFromS3(req, file);++ if (config?.invalidateOnDelete && config.distributionId) {+ try {+ const client = getOrCreateCloudFrontClient();+ // CloudFront URL pathname matches S3 key when no origin path prefix is configured+ const key = extractKeyFromS3Url(file.filepath);+ const path = key.startsWith('/') ? key : `/${key}`;++ await client.send(+ new CreateInvalidationCommand({+ DistributionId: config.distributionId,+ InvalidationBatch: {+ CallerReference: crypto.randomUUID(),+ Paths: { Quantity: 1, Items: [path] },+ },+ }),+ );+ logger.debug(`[deleteFileFromCloudFront] Invalidation created for: ${path}`);+ } catch (error) {+ logger.error(+ '[deleteFileFromCloudFront] Cache invalidation failed:',+ (error as Error).message,+ );+ }+ }+}++/** Get file stream from S3 storage. */+export async function getCloudFrontFileStream(+ req: ServerRequest,+ filePath: string,+): Promise<Readable> {+ return getS3FileStream(req, filePath);+}diff --git a/packages/api/src/storage/cloudfront/index.ts b/packages/api/src/storage/cloudfront/index.tsnew file mode 100644index 0000000000..f9b6bca108--- /dev/null+++ b/packages/api/src/storage/cloudfront/index.ts@@ -0,0 +1 @@+export * from './crud';diff --git a/packages/api/src/storage/constants.ts b/packages/api/src/storage/constants.tsnew file mode 100644index 0000000000..e6f5330aaf--- /dev/null+++ b/packages/api/src/storage/constants.ts@@ -0,0 +1,2 @@+/** Default base path for cloud-stored files (used by all storage strategies). */+export const DEFAULT_BASE_PATH = 'images';diff --git a/packages/api/src/storage/s3/images.ts b/packages/api/src/storage/images.tssimilarity index 56%rename from packages/api/src/storage/s3/images.tsrename to packages/api/src/storage/images.tsindex b9d7322359..479763102a 100644--- a/packages/api/src/storage/s3/images.ts+++ b/packages/api/src/storage/images.ts@@ -5,13 +5,15 @@ import { logger } from '@librechat/data-schemas';import type { IUser } from '@librechat/data-schemas';import type { TFile } from 'librechat-data-provider';import type { FormatEnum } from 'sharp';-import type { UploadImageParams, ImageUploadResult, ProcessAvatarParams } from '~/storage/types';-import { saveBufferToS3 } from './crud';-import { s3Config } from './s3Config';--const { DEFAULT_BASE_PATH: defaultBasePath } = s3Config;--export interface S3ImageServiceDeps {+import type {+ SaveBufferFn,+ UploadImageParams,+ ImageUploadResult,+ ProcessAvatarParams,+} from '~/storage/types';+import { DEFAULT_BASE_PATH as defaultBasePath } from '~/storage/constants';++export interface ImageServiceDeps {resizeImageBuffer: (buffer: Buffer,resolution: string,@@ -21,14 +23,34 @@ export interface S3ImageServiceDeps {updateFile: (params: { file_id: string }) => Promise<TFile>;}-export class S3ImageService {- private deps: S3ImageServiceDeps;-- constructor(deps: S3ImageServiceDeps) {- this.deps = deps;- }+export interface ImageServiceConfig {+ /** If true, appends ?manual=... to avatar URLs (Firebase/Azure behavior) */+ appendManualParam?: boolean;+}- async uploadImageToS3({+/**+ * Unified image service for cloud storage strategies.+ * Handles image uploads, URL preparation, and avatar processing+ * via an injected `saveBuffer` function, enabling any storage backend+ * (S3, CloudFront, Azure, Firebase, etc.) without subclassing.+ */+export class ImageService {+ /**+ * @param saveBuffer - Strategy-specific function that persists a buffer and returns a download URL.+ * @param deps - External dependencies (resize, user/file update callbacks).+ * @param config - Optional per-strategy configuration.+ */+ constructor(+ private saveBuffer: SaveBufferFn,+ private deps: ImageServiceDeps,+ private config: ImageServiceConfig = {},+ ) {}++ /**+ * Resizes, converts, and uploads an image file to cloud storage.+ * Deletes the local temp file after a successful upload.+ */+ async uploadImage({req,file,file_id,@@ -39,7 +61,7 @@ export class S3ImageService {const inputFilePath = file.path;try {if (!req.user) {- throw new Error('[S3ImageService.uploadImageToS3] User not authenticated');+ throw new Error('[ImageService.uploadImage] User not authenticated');}const appConfig = req.config;@@ -53,15 +75,16 @@ export class S3ImageService {const extension = path.extname(inputFilePath);const userId = req.user.id;+ const outputType = appConfig?.imageOutputType ?? 'webp';+ const targetExtension = `.${outputType}`;let processedBuffer: Buffer;let fileName = `${file_id}__${path.basename(inputFilePath)}`;- const targetExtension = `.${appConfig?.imageOutputType ?? 'webp'}`;if (extension.toLowerCase() === targetExtension) {processedBuffer = resizedBuffer;} else {- const outputFormat = (appConfig?.imageOutputType ?? 'webp') as keyof FormatEnum;+ const outputFormat = outputType as keyof FormatEnum;processedBuffer = await sharp(resizedBuffer).toFormat(outputFormat).toBuffer();fileName = fileName.replace(new RegExp(path.extname(fileName) + '$'), targetExtension);if (!path.extname(fileName)) {@@ -69,7 +92,7 @@ export class S3ImageService {}}- const downloadURL = await saveBufferToS3({+ const downloadURL = await this.saveBuffer({userId,buffer: processedBuffer,fileName,@@ -78,17 +101,14 @@ export class S3ImageService {const bytes = processedBuffer.length;return { filepath: downloadURL, bytes, width, height };} catch (error) {- logger.error(- '[S3ImageService.uploadImageToS3] Error uploading image to S3:',- (error as Error).message,- );+ logger.error('[ImageService.uploadImage] Error uploading image:', (error as Error).message);throw error;} finally {await fs.promises.unlink(inputFilePath).catch((e: unknown) =>logger.error(- '[S3ImageService.uploadImageToS3] Failed to delete temp file:',+ '[ImageService.uploadImage] Failed to delete temp file:',(e as Error).message,),);@@ -100,13 +120,18 @@ export class S3ImageService {return await Promise.all([this.deps.updateFile({ file_id: file.file_id }), file.filepath]);} catch (error) {logger.error(- '[S3ImageService.prepareImageURL] Error preparing image URL:',+ '[ImageService.prepareImageURL] Error preparing image URL:',(error as Error).message,);throw error;}}+ /**+ * Processes and uploads an avatar image.+ * Detects GIF vs PNG, generates a timestamped filename, and optionally+ * persists the URL to the user record when `manual` is `'true'`.+ */async processAvatar({buffer,userId,@@ -123,16 +148,20 @@ export class S3ImageService {? `agent-${agentId}-avatar-${timestamp}.${extension}`: `avatar-${timestamp}.${extension}`;- const downloadURL = await saveBufferToS3({ userId, buffer, fileName, basePath });+ const downloadURL = await this.saveBuffer({ userId, buffer, fileName, basePath });++ const finalURL = this.config.appendManualParam+ ? `${downloadURL}?manual=${manual === 'true'}`+ : downloadURL;if (manual === 'true' && !agentId) {- await this.deps.updateUser(userId, { avatar: downloadURL });+ await this.deps.updateUser(userId, { avatar: finalURL });}- return downloadURL;+ return finalURL;} catch (error) {logger.error(- '[S3ImageService.processAvatar] Error processing S3 avatar:',+ '[ImageService.processAvatar] Error processing avatar:',(error as Error).message,);throw error;diff --git a/packages/api/src/storage/index.ts b/packages/api/src/storage/index.tsindex ebd7bd63a9..0d2be2208a 100644--- a/packages/api/src/storage/index.ts+++ b/packages/api/src/storage/index.ts@@ -1,2 +1,4 @@+export * from './cloudfront';export * from './s3';export * from './types';+export * from './images';diff --git a/packages/api/src/storage/s3/__tests__/images.test.ts b/packages/api/src/storage/s3/__tests__/images.test.tsdeleted file mode 100644index 065c73cebd..0000000000--- a/packages/api/src/storage/s3/__tests__/images.test.ts+++ /dev/null@@ -1,182 +0,0 @@-import fs from 'fs';-import type { S3ImageServiceDeps } from '~/storage/s3/images';-import type { ServerRequest } from '~/types';-import { S3ImageService } from '~/storage/s3/images';-import { saveBufferToS3 } from '~/storage/s3/crud';--jest.mock('fs', () => ({- ...jest.requireActual('fs'),- promises: {- readFile: jest.fn(),- unlink: jest.fn().mockResolvedValue(undefined),- },-}));--jest.mock('../crud', () => ({- saveBufferToS3: jest- .fn()- .mockResolvedValue('https://bucket.s3.amazonaws.com/avatar.png?signed=true'),-}));--const mockSaveBufferToS3 = jest.mocked(saveBufferToS3);--jest.mock('sharp', () => {- return jest.fn(() => ({- metadata: jest.fn().mockResolvedValue({ format: 'png', width: 100, height: 100 }),- toFormat: jest.fn().mockReturnThis(),- toBuffer: jest.fn().mockResolvedValue(Buffer.from('processed')),- }));-});--describe('S3ImageService', () => {- let service: S3ImageService;- let mockDeps: S3ImageServiceDeps;-- beforeEach(() => {- jest.clearAllMocks();-- mockDeps = {- resizeImageBuffer: jest.fn().mockResolvedValue({- buffer: Buffer.from('resized'),- width: 100,- height: 100,- }),- updateUser: jest.fn().mockResolvedValue(undefined),- updateFile: jest.fn().mockResolvedValue(undefined),- };-- service = new S3ImageService(mockDeps);- });-- describe('processAvatar', () => {- it('uploads avatar and returns URL', async () => {- const result = await service.processAvatar({- buffer: Buffer.from('test'),- userId: 'user123',- manual: 'false',- });-- expect(result).toContain('signed=true');- });-- it('updates user avatar when manual is true', async () => {- await service.processAvatar({- buffer: Buffer.from('test'),- userId: 'user123',- manual: 'true',- });-- expect(mockDeps.updateUser).toHaveBeenCalledWith(- 'user123',- expect.objectContaining({ avatar: expect.any(String) }),- );- });-- it('does not update user when agentId is provided', async () => {- await service.processAvatar({- buffer: Buffer.from('test'),- userId: 'user123',- manual: 'true',- agentId: 'agent456',- });-- expect(mockDeps.updateUser).not.toHaveBeenCalled();- });-- it('generates agent avatar filename when agentId provided', async () => {- await service.processAvatar({- buffer: Buffer.from('test'),- userId: 'user123',- manual: 'false',- agentId: 'agent456',- });-- expect(mockSaveBufferToS3).toHaveBeenCalledWith(- expect.objectContaining({- fileName: expect.stringContaining('agent-agent456-avatar-'),- }),- );- });- });-- describe('prepareImageURL', () => {- it('returns tuple with resolved promise and filepath', async () => {- const file = { file_id: 'file123', filepath: 'https://example.com/file.png' };- const result = await service.prepareImageURL(file);-- expect(Array.isArray(result)).toBe(true);- expect(result[1]).toBe('https://example.com/file.png');- });-- it('calls updateFile with file_id', async () => {- const file = { file_id: 'file123', filepath: 'https://example.com/file.png' };- await service.prepareImageURL(file);-- expect(mockDeps.updateFile).toHaveBeenCalledWith({ file_id: 'file123' });- });- });-- describe('constructor', () => {- it('requires dependencies to be passed', () => {- const newService = new S3ImageService(mockDeps);- expect(newService).toBeInstanceOf(S3ImageService);- });- });-- describe('uploadImageToS3', () => {- const mockReq = {- user: { id: 'user123' },- config: { imageOutputType: 'webp' },- } as unknown as ServerRequest;-- it('deletes temp file on early failure (readFile throws)', async () => {- (fs.promises.readFile as jest.Mock).mockRejectedValueOnce(- new Error('ENOENT: no such file or directory'),- );- (fs.promises.unlink as jest.Mock).mockResolvedValueOnce(undefined);-- await expect(- service.uploadImageToS3({- req: mockReq,- file: { path: '/tmp/input.jpg' } as Express.Multer.File,- file_id: 'file123',- endpoint: 'openai',- }),- ).rejects.toThrow('ENOENT: no such file or directory');-- expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/input.jpg');- });-- it('deletes temp file on resize failure (resizeImageBuffer throws)', async () => {- (fs.promises.readFile as jest.Mock).mockResolvedValueOnce(Buffer.from('raw'));- (mockDeps.resizeImageBuffer as jest.Mock).mockRejectedValueOnce(new Error('Resize failed'));- (fs.promises.unlink as jest.Mock).mockResolvedValueOnce(undefined);-- await expect(- service.uploadImageToS3({- req: mockReq,- file: { path: '/tmp/input.jpg' } as Express.Multer.File,- file_id: 'file123',- endpoint: 'openai',- }),- ).rejects.toThrow('Resize failed');-- expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/input.jpg');- });-- it('deletes temp file on success', async () => {- (fs.promises.readFile as jest.Mock).mockResolvedValueOnce(Buffer.from('raw'));- (fs.promises.unlink as jest.Mock).mockResolvedValueOnce(undefined);-- const result = await service.uploadImageToS3({- req: mockReq,- file: { path: '/tmp/input.webp' } as Express.Multer.File,- file_id: 'file123',- endpoint: 'openai',- });-- expect(result.filepath).toContain('signed=true');- expect(fs.promises.unlink).toHaveBeenCalledWith('/tmp/input.webp');- });- });-});diff --git a/packages/api/src/storage/s3/__tests__/s3.integration.spec.ts b/packages/api/src/storage/s3/__tests__/s3.integration.spec.tsindex de80e7409b..5dc1e3b754 100644--- a/packages/api/src/storage/s3/__tests__/s3.integration.spec.ts+++ b/packages/api/src/storage/s3/__tests__/s3.integration.spec.ts@@ -108,13 +108,13 @@ describe('S3 Integration Tests', () => {describe('getS3Key', () => {it('constructs key from basePath, userId, and fileName', async () => {- const { getS3Key } = await import('../crud');+ const { getS3Key } = await import('~/storage/s3/crud');const key = getS3Key(TEST_BASE_PATH, TEST_USER_ID, 'test-file.txt');expect(key).toBe(`${TEST_BASE_PATH}/${TEST_USER_ID}/test-file.txt`);});it('handles nested file names', async () => {- const { getS3Key } = await import('../crud');+ const { getS3Key } = await import('~/storage/s3/crud');const key = getS3Key(TEST_BASE_PATH, TEST_USER_ID, 'folder/nested/file.pdf');expect(key).toBe(`${TEST_BASE_PATH}/${TEST_USER_ID}/folder/nested/file.pdf`);});@@ -122,7 +122,7 @@ describe('S3 Integration Tests', () => {describe('saveBufferToS3 and getS3URL', () => {it('uploads buffer and returns signed URL', async () => {- const { saveBufferToS3 } = await import('../crud');+ const { saveBufferToS3 } = await import('~/storage/s3/crud');const testContent = 'Hello, S3!';const buffer = Buffer.from(testContent);const fileName = `test-${Date.now()}.txt`;@@ -140,7 +140,7 @@ describe('S3 Integration Tests', () => {});it('can get signed URL for existing file', async () => {- const { saveBufferToS3, getS3URL } = await import('../crud');+ const { saveBufferToS3, getS3URL } = await import('~/storage/s3/crud');const buffer = Buffer.from('test content for URL');const fileName = `url-test-${Date.now()}.txt`;@@ -162,7 +162,7 @@ describe('S3 Integration Tests', () => {});it('can get signed URL with custom filename and content type', async () => {- const { saveBufferToS3, getS3URL } = await import('../crud');+ const { saveBufferToS3, getS3URL } = await import('~/storage/s3/crud');const buffer = Buffer.from('custom headers test');const fileName = `headers-test-${Date.now()}.txt`;@@ -188,7 +188,7 @@ describe('S3 Integration Tests', () => {describe('saveURLToS3', () => {it('fetches URL content and uploads to S3', async () => {- const { saveURLToS3 } = await import('../crud');+ const { saveURLToS3 } = await import('~/storage/s3/crud');const fileName = `url-upload-${Date.now()}.json`;const downloadURL = await saveURLToS3({@@ -205,7 +205,7 @@ describe('S3 Integration Tests', () => {describe('extractKeyFromS3Url', () => {it('extracts key from signed URL', async () => {- const { saveBufferToS3, extractKeyFromS3Url } = await import('../crud');+ const { saveBufferToS3, extractKeyFromS3Url } = await import('~/storage/s3/crud');const buffer = Buffer.from('extract key test');const fileName = `extract-key-${Date.now()}.txt`;@@ -221,7 +221,7 @@ describe('S3 Integration Tests', () => {});it('returns key as-is when not a URL', async () => {- const { extractKeyFromS3Url } = await import('../crud');+ const { extractKeyFromS3Url } = await import('~/storage/s3/crud');const key = `${TEST_BASE_PATH}/${TEST_USER_ID}/file.txt`;expect(extractKeyFromS3Url(key)).toBe(key);});@@ -229,7 +229,7 @@ describe('S3 Integration Tests', () => {describe('uploadFileToS3', () => {it('uploads file and returns filepath with bytes', async () => {- const { uploadFileToS3 } = await import('../crud');+ const { uploadFileToS3 } = await import('~/storage/s3/crud');const testContent = 'File upload test content';const testFilePath = path.join(tempDir, 'upload-test.txt');fs.writeFileSync(testFilePath, testContent);@@ -266,7 +266,7 @@ describe('S3 Integration Tests', () => {});it('throws error when user is not authenticated', async () => {- const { uploadFileToS3 } = await import('../crud');+ const { uploadFileToS3 } = await import('~/storage/s3/crud');const mockReq = {} as ServerRequest;const mockFile = {path: '/fake/path.txt',@@ -286,7 +286,7 @@ describe('S3 Integration Tests', () => {describe('getS3FileStream', () => {it('returns readable stream for existing file', async () => {- const { saveBufferToS3, getS3FileStream } = await import('../crud');+ const { saveBufferToS3, getS3FileStream } = await import('~/storage/s3/crud');const testContent = 'Stream test content';const buffer = Buffer.from(testContent);const fileName = `stream-test-${Date.now()}.txt`;@@ -317,12 +317,12 @@ describe('S3 Integration Tests', () => {describe('needsRefresh', () => {it('returns false for non-signed URLs', async () => {- const { needsRefresh } = await import('../crud');+ const { needsRefresh } = await import('~/storage/s3/crud');expect(needsRefresh('https://example.com/file.png', 3600)).toBe(false);});it('returns true for expired signed URLs', async () => {- const { saveBufferToS3, needsRefresh } = await import('../crud');+ const { saveBufferToS3, needsRefresh } = await import('~/storage/s3/crud');const buffer = Buffer.from('refresh test');const fileName = `refresh-test-${Date.now()}.txt`;@@ -338,7 +338,7 @@ describe('S3 Integration Tests', () => {});it('returns false for fresh signed URLs', async () => {- const { saveBufferToS3, needsRefresh } = await import('../crud');+ const { saveBufferToS3, needsRefresh } = await import('~/storage/s3/crud');const buffer = Buffer.from('fresh test');const fileName = `fresh-test-${Date.now()}.txt`;@@ -356,7 +356,7 @@ describe('S3 Integration Tests', () => {describe('getNewS3URL', () => {it('generates signed URL from existing URL', async () => {- const { saveBufferToS3, getNewS3URL } = await import('../crud');+ const { saveBufferToS3, getNewS3URL } = await import('~/storage/s3/crud');const buffer = Buffer.from('new url test');const fileName = `new-url-${Date.now()}.txt`;@@ -377,7 +377,7 @@ describe('S3 Integration Tests', () => {describe('refreshS3Url', () => {it('returns original URL for non-S3 source', async () => {- const { refreshS3Url } = await import('../crud');+ const { refreshS3Url } = await import('~/storage/s3/crud');const fileObj = {filepath: 'https://example.com/file.png',source: 'local',@@ -388,7 +388,7 @@ describe('S3 Integration Tests', () => {});it('refreshes URL for S3 source when needed', async () => {- const { saveBufferToS3, refreshS3Url } = await import('../crud');+ const { saveBufferToS3, refreshS3Url } = await import('~/storage/s3/crud');const buffer = Buffer.from('s3 refresh test');const fileName = `s3-refresh-${Date.now()}.txt`;@@ -411,9 +411,10 @@ describe('S3 Integration Tests', () => {});});- describe('S3ImageService', () => {+ describe('ImageService (S3 strategy)', () => {it('uploads avatar and returns URL', async () => {- const { S3ImageService } = await import('../images');+ const { ImageService } = await import('~/storage/images');+ const { saveBufferToS3 } = await import('~/storage/s3/crud');const mockDeps = {resizeImageBuffer: jest.fn().mockImplementation(async (buffer: Buffer) => ({@@ -422,10 +423,10 @@ describe('S3 Integration Tests', () => {height: 100,})),updateUser: jest.fn().mockResolvedValue(undefined),- updateFile: jest.fn().mockResolvedValue(undefined),+ updateFile: jest.fn().mockResolvedValue(null),};- const imageService = new S3ImageService(mockDeps);+ const imageService = new ImageService(saveBufferToS3, mockDeps);const pngBuffer = MINIMAL_PNG;@@ -442,7 +443,8 @@ describe('S3 Integration Tests', () => {});it('updates user when manual is true', async () => {- const { S3ImageService } = await import('../images');+ const { ImageService } = await import('~/storage/images');+ const { saveBufferToS3 } = await import('~/storage/s3/crud');const mockDeps = {resizeImageBuffer: jest.fn().mockImplementation(async (buffer: Buffer) => ({@@ -451,10 +453,10 @@ describe('S3 Integration Tests', () => {height: 100,})),updateUser: jest.fn().mockResolvedValue(undefined),- updateFile: jest.fn().mockResolvedValue(undefined),+ updateFile: jest.fn().mockResolvedValue(null),};- const imageService = new S3ImageService(mockDeps);+ const imageService = new ImageService(saveBufferToS3, mockDeps);const pngBuffer = MINIMAL_PNG;@@ -472,7 +474,8 @@ describe('S3 Integration Tests', () => {});it('does not update user when agentId is provided', async () => {- const { S3ImageService } = await import('../images');+ const { ImageService } = await import('~/storage/images');+ const { saveBufferToS3 } = await import('~/storage/s3/crud');const mockDeps = {resizeImageBuffer: jest.fn().mockImplementation(async (buffer: Buffer) => ({@@ -481,10 +484,10 @@ describe('S3 Integration Tests', () => {height: 100,})),updateUser: jest.fn().mockResolvedValue(undefined),- updateFile: jest.fn().mockResolvedValue(undefined),+ updateFile: jest.fn().mockResolvedValue(null),};- const imageService = new S3ImageService(mockDeps);+ const imageService = new ImageService(saveBufferToS3, mockDeps);const pngBuffer = MINIMAL_PNG;@@ -500,7 +503,8 @@ describe('S3 Integration Tests', () => {});it('returns tuple with resolved promise and filepath in prepareImageURL', async () => {- const { S3ImageService } = await import('../images');+ const { ImageService } = await import('~/storage/images');+ const { saveBufferToS3 } = await import('~/storage/s3/crud');const mockDeps = {resizeImageBuffer: jest.fn().mockImplementation(async (buffer: Buffer) => ({@@ -509,10 +513,10 @@ describe('S3 Integration Tests', () => {height: 100,})),updateUser: jest.fn().mockResolvedValue(undefined),- updateFile: jest.fn().mockResolvedValue(undefined),+ updateFile: jest.fn().mockResolvedValue(null),};- const imageService = new S3ImageService(mockDeps);+ const imageService = new ImageService(saveBufferToS3, mockDeps);const testFile = {file_id: 'file-123',diff --git a/packages/api/src/storage/s3/crud.ts b/packages/api/src/storage/s3/crud.tsindex 1143a7ed7f..1ea6d32dd0 100644--- a/packages/api/src/storage/s3/crud.ts+++ b/packages/api/src/storage/s3/crud.ts@@ -1,16 +1,16 @@import fs from 'fs';-import { Readable } from 'stream';-import { logger } from '@librechat/data-schemas';-import { FileSources } from 'librechat-data-provider';-import { getSignedUrl } from '@aws-sdk/s3-request-presigner';import {PutObjectCommand,GetObjectCommand,HeadObjectCommand,DeleteObjectCommand,} from '@aws-sdk/client-s3';+import { logger } from '@librechat/data-schemas';+import { FileSources } from 'librechat-data-provider';+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';import type { GetObjectCommandInput } from '@aws-sdk/client-s3';import type { TFile } from 'librechat-data-provider';+import type { Readable } from 'stream';import type { ServerRequest } from '~/types';import type {UploadFileParams,@@ -19,6 +19,7 @@ import type {SaveURLParams,GetURLParams,UploadResult,+ UrlBuilder,S3FileRef,} from '~/storage/types';import { initializeS3 } from '~/cdn/s3';@@ -77,7 +78,8 @@ export async function saveBufferToS3({buffer,fileName,basePath = defaultBasePath,-}: SaveBufferParams): Promise<string> {+ urlBuilder,+}: SaveBufferParams & { urlBuilder?: UrlBuilder }): Promise<string> {const key = getS3Key(basePath, userId, fileName);const params = { Bucket: bucketName, Key: key, Body: buffer };@@ -88,7 +90,8 @@ export async function saveBufferToS3({}await s3.send(new PutObjectCommand(params));- return await getS3URL({ userId, fileName, basePath });+ const getUrl = urlBuilder ?? getS3URL;+ return await getUrl({ userId, fileName, basePath });} catch (error) {logger.error('[saveBufferToS3] Error uploading buffer to S3:', (error as Error).message);throw error;@@ -100,7 +103,8 @@ export async function saveURLToS3({URL,fileName,basePath = defaultBasePath,-}: SaveURLParams): Promise<string> {+ urlBuilder,+}: SaveURLParams & { urlBuilder?: UrlBuilder }): Promise<string> {try {const response = await fetch(URL);if (!response.ok) {@@ -108,7 +112,7 @@ export async function saveURLToS3({}const arrayBuffer = await response.arrayBuffer();const buffer = Buffer.from(arrayBuffer);- return await saveBufferToS3({ userId, buffer, fileName, basePath });+ return await saveBufferToS3({ userId, buffer, fileName, basePath, urlBuilder });} catch (error) {logger.error('[saveURLToS3] Error uploading file from URL to S3:', (error as Error).message);throw error;@@ -247,7 +251,8 @@ export async function uploadFileToS3({file,file_id,basePath = defaultBasePath,-}: UploadFileParams): Promise<UploadResult> {+ urlBuilder,+}: UploadFileParams & { urlBuilder?: UrlBuilder }): Promise<UploadResult> {if (!req.user) {throw new Error('[uploadFileToS3] User not authenticated');}@@ -274,7 +279,8 @@ export async function uploadFileToS3({};await s3.send(new PutObjectCommand(uploadParams));- const fileURL = await getS3URL({ userId, fileName, basePath });+ const getUrl = urlBuilder ?? getS3URL;+ const fileURL = await getUrl({ userId, fileName, basePath });// NOTE: temp file is intentionally NOT deleted on the success path.// The caller (processAgentFileUpload) reads file.path after this returns// to stream the file to the RAG vector embedding service (POST /embed).diff --git a/packages/api/src/storage/s3/index.ts b/packages/api/src/storage/s3/index.tsindex e700610bba..f9b6bca108 100644--- a/packages/api/src/storage/s3/index.ts+++ b/packages/api/src/storage/s3/index.ts@@ -1,2 +1 @@export * from './crud';-export * from './images';diff --git a/packages/api/src/storage/s3/s3Config.ts b/packages/api/src/storage/s3/s3Config.tsindex 766c0cf66e..9f7a0ce5eb 100644--- a/packages/api/src/storage/s3/s3Config.ts+++ b/packages/api/src/storage/s3/s3Config.ts@@ -1,9 +1,9 @@import { logger } from '@librechat/data-schemas';import { isEnabled } from '~/utils/common';+import { DEFAULT_BASE_PATH } from '~/storage/constants';const MAX_EXPIRY_SECONDS = 7 * 24 * 60 * 60; // 7 daysconst DEFAULT_EXPIRY_SECONDS = 2 * 60; // 2 minutes-const DEFAULT_BASE_PATH = 'images';const parseUrlExpiry = (): number => {if (process.env.S3_URL_EXPIRY_SECONDS === undefined) {diff --git a/packages/api/src/storage/types.ts b/packages/api/src/storage/types.tsindex 314719f38a..2a5380dec2 100644--- a/packages/api/src/storage/types.ts+++ b/packages/api/src/storage/types.ts@@ -57,4 +57,8 @@ export interface S3FileRef {source: string;}+export type SaveBufferFn = (params: SaveBufferParams) => Promise<string>;+export type BatchUpdateFn = (files: Array<{ file_id: string; filepath: string }>) => Promise<void>;++export type UrlBuilder = (params: GetURLParams) => Promise<string>;diff --git a/packages/data-provider/src/cloudfront-config.spec.ts b/packages/data-provider/src/cloudfront-config.spec.tsnew file mode 100644index 0000000000..4d7766c368--- /dev/null+++ b/packages/data-provider/src/cloudfront-config.spec.ts@@ -0,0 +1,77 @@+import { cloudfrontConfigSchema } from './config';++describe('cloudfrontConfigSchema cookieDomain validation', () => {+ it('accepts cookieDomain starting with dot', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ cookieDomain: '.example.com',+ });+ expect(result.success).toBe(true);+ });++ it('rejects cookieDomain without leading dot', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ cookieDomain: 'example.com',+ });+ expect(result.success).toBe(false);+ if (!result.success) {+ expect(result.error.issues[0].message).toContain('must start with a dot');+ }+ });++ it('allows omitting cookieDomain', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ });+ expect(result.success).toBe(true);+ });+});++describe('cloudfrontConfigSchema cross-field refinements', () => {+ it('rejects invalidateOnDelete=true without distributionId', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ invalidateOnDelete: true,+ });+ expect(result.success).toBe(false);+ if (!result.success) {+ expect(result.error.issues[0].message).toContain(+ 'distributionId is required when invalidateOnDelete is true',+ );+ expect(result.error.issues[0].path).toEqual(['distributionId']);+ }+ });++ it('accepts invalidateOnDelete=true with distributionId', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ invalidateOnDelete: true,+ distributionId: 'E1ABCDEFGHIJK',+ });+ expect(result.success).toBe(true);+ });++ it('rejects imageSigning="cookies" without cookieDomain', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ });+ expect(result.success).toBe(false);+ if (!result.success) {+ expect(result.error.issues[0].message).toContain(+ 'cookieDomain is required when imageSigning is "cookies"',+ );+ expect(result.error.issues[0].path).toEqual(['cookieDomain']);+ }+ });++ it('accepts imageSigning="cookies" with cookieDomain', () => {+ const result = cloudfrontConfigSchema.safeParse({+ domain: 'https://cdn.example.com',+ imageSigning: 'cookies',+ cookieDomain: '.example.com',+ });+ expect(result.success).toBe(true);+ });+});diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex ca6ec7cdae..d8fc071c6f 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -168,6 +168,7 @@ const FILE_STORAGE_BACKENDS = [FileSources.firebase,FileSources.s3,FileSources.azure_blob,+ FileSources.cloudfront,] as const satisfies ReadonlyArray<FileSources>;export const fileStorageSchema = z.enum(FILE_STORAGE_BACKENDS);@@ -184,6 +185,37 @@ export const fileStrategiesSchema = z}).optional();+const cloudfrontSigningSchema = z.enum(['none', 'cookies', 'url']);++export const cloudfrontConfigSchema = z+ .object({+ domain: z.string().url(),+ distributionId: z.string().optional(),+ invalidateOnDelete: z.boolean().default(false),+ imageSigning: cloudfrontSigningSchema.default('none'),+ urlExpiry: z.number().positive().default(3600),+ cookieExpiry: z.number().positive().max(604800).default(1800),+ cookieDomain: z+ .string()+ .min(1)+ .refine((d) => d.startsWith('.'), {+ message: 'cookieDomain must start with a dot (e.g., ".example.com") to apply to subdomains',+ })+ .optional(),+ })+ .refine((data) => !data.invalidateOnDelete || !!data.distributionId, {+ message: 'distributionId is required when invalidateOnDelete is true',+ path: ['distributionId'],+ })+ .refine((data) => data.imageSigning !== 'cookies' || !!data.cookieDomain, {+ message:+ 'cookieDomain is required when imageSigning is "cookies" (e.g., ".example.com" for API at api.example.com and CDN at cdn.example.com)',+ path: ['cookieDomain'],+ })+ .optional();++export type CloudFrontConfig = z.infer<typeof cloudfrontConfigSchema>;+// Helper type to extract the shape of the Zod object schematype SchemaShape<T> = T extends z.ZodObject<infer U> ? U : never;@@ -1296,6 +1328,7 @@ export const configSchema = z.object({turnstile: turnstileSchema.optional(),fileStrategy: fileStorageSchema.default(FileSources.local),fileStrategies: fileStrategiesSchema,+ cloudfront: cloudfrontConfigSchema,actions: z.object({allowedDomains: z.array(z.string()).optional(),diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.tsindex 2215e7c5b6..8168136685 100644--- a/packages/data-provider/src/types/files.ts+++ b/packages/data-provider/src/types/files.ts@@ -7,6 +7,7 @@ export enum FileSources {azure_blob = 'azure_blob',openai = 'openai',s3 = 's3',+ cloudfront = 'cloudfront',vectordb = 'vectordb',execute_code = 'execute_code',mistral_ocr = 'mistral_ocr',diff --git a/packages/data-schemas/src/app/service.ts b/packages/data-schemas/src/app/service.tsindex 57a5e603ac..19fec9f5a1 100644--- a/packages/data-schemas/src/app/service.ts+++ b/packages/data-schemas/src/app/service.ts@@ -89,7 +89,8 @@ export const AppService = async (params?: {| FileSources.local| FileSources.s3| FileSources.firebase- | FileSources.azure_blob;+ | FileSources.azure_blob+ | FileSources.cloudfront;const startBalance = process.env.START_BALANCE;const balance = config.balance ?? {enabled: process.env.CHECK_BALANCE?.toLowerCase().trim() === 'true',@@ -132,6 +133,7 @@ export const AppService = async (params?: {turnstileConfig,mcpConfig: mcpServersConfig,fileStrategies: config.fileStrategies,+ cloudfront: config.cloudfront as AppConfig['cloudfront'],};const agentsDefaults = agentsConfigSetup(config);diff --git a/packages/data-schemas/src/types/app.ts b/packages/data-schemas/src/types/app.tsindex 3b626694b4..53e4496f07 100644--- a/packages/data-schemas/src/types/app.ts+++ b/packages/data-schemas/src/types/app.ts@@ -8,6 +8,7 @@ import type {EModelEndpoint,TVertexAIConfig,TAgentsEndpoint,+ CloudFrontConfig,TCustomEndpoints,TAssistantEndpoint,TAnthropicEndpoint,@@ -61,10 +62,12 @@ export interface AppConfig {summarization?: SummarizationConfig;/** Web search configuration */webSearch?: TCustomConfig['webSearch'];- /** File storage strategy ('local', 's3', 'firebase', 'azure_blob') */+ /** File storage strategy ('local', 's3', 'firebase', 'azure_blob', 'cloudfront') */fileStrategy: FileStorage;/** File strategies configuration */fileStrategies?: TCustomConfig['fileStrategies'];+ /** CloudFront CDN configuration */+ cloudfront?: CloudFrontConfig;/** Registration configurations */registration?: TCustomConfig['registration'];/** Actions configurations */