🔐 feat(auth): add CloudFront signed cookie support

- Integrate CloudFront signed cookies into authentication flow for secure CDN access.
- Set cookies on login (setAuthTokens, setOpenIDAuthTokens) when imageSigning="cookies".
- Add cookieDomain and cookieExpiry config options with validation requiring shared parent domain.

Author: AtefBellaaj

api/server/services/AuthService.js

@@ -11,6 +11,7 @@ const {
   math,
   isEnabled,
   checkEmailConfig,
+  setCloudFrontCookies,
   isEmailDomainAllowed,
   shouldUseSecureCookie,
 } = require('@librechat/api');
@@ -406,6 +407,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);
@@ -523,6 +527,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);

api/server/services/AuthService.spec.js

@@ -14,6 +14,7 @@ jest.mock('@librechat/api', () => ({
   isEmailDomainAllowed: jest.fn(),
   math: jest.fn((val, fallback) => (val ? Number(val) : fallback)),
   shouldUseSecureCookie: jest.fn(() => false),
+  setCloudFrontCookies: jest.fn(() => true),
 }));
 jest.mock('~/models', () => ({
   findUser: jest.fn(),
@@ -35,8 +36,9 @@ jest.mock('~/strategies/validators', () => ({ registerSchema: { parse: jest.fn()
 jest.mock('~/server/services/Config', () => ({ getAppConfig: jest.fn() }));
 jest.mock('~/server/utils', () => ({ sendEmail: jest.fn() }));
 
-const { shouldUseSecureCookie } = require('@librechat/api');
-const { setOpenIDAuthTokens } = require('./AuthService');
+const { shouldUseSecureCookie, setCloudFrontCookies } = require('@librechat/api');
+const { createSession, generateToken, generateRefreshToken, getUserById } = require('~/models');
+const { setOpenIDAuthTokens, setAuthTokens } = require('./AuthService');
 
 /** Helper to build a mock Express response */
 function mockResponse() {
@@ -267,3 +269,67 @@ describe('setOpenIDAuthTokens', () => {
     });
   });
 });
+
+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');
+    });
+  });
+});

librechat.example.yaml

@@ -29,15 +29,17 @@ cache: true
 # 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 URLs: CLOUDFRONT_KEY_PAIR_ID, CLOUDFRONT_PRIVATE_KEY
+# For signed cookies/URLs: CLOUDFRONT_KEY_PAIR_ID, CLOUDFRONT_PRIVATE_KEY
 # cloudfront:
-#   domain: "https://d1234abcd.cloudfront.net"
-#   distributionId: "E1234ABCD"       # Required if invalidateOnDelete is true
-#   invalidateOnDelete: false         # Create cache invalidation on file delete
-#   # NOTE: imageSigning is not yet implemented. All URLs are unsigned regardless of value.
-#   # Do NOT restrict your CloudFront distribution to signed requests.
-#   imageSigning: "none"              # "none" | "cookies" | "url"
-#   urlExpiry: 3600                   # Signed URL expiry in seconds
+#   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 (default: 30 min)
+#   urlExpiry: 3600                         # Signed URL expiry for documents (default: 1 hour)
 
 # Custom interface configuration
 interface:

packages/api/src/auth/__tests__/cloudfront-cookies.test.ts

@@ -0,0 +1,224 @@
+const mockGetCloudFrontConfig = jest.fn();
+const mockGetSignedCookies = jest.fn();
+
+jest.mock('~/cdn/cloudfront', () => ({
+  getCloudFrontConfig: () => mockGetCloudFrontConfig(),
+}));
+
+jest.mock('@aws-sdk/cloudfront-signer', () => ({
+  getSignedCookies: (params: unknown) => mockGetSignedCookies(params),
+}));
+
+import type { Response } from 'express';
+import { isCloudFrontCookiesEnabled, setCloudFrontCookies } from '../cloudfront-cookies';
+
+describe('isCloudFrontCookiesEnabled', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('returns false when CloudFront config is null', () => {
+    mockGetCloudFrontConfig.mockReturnValue(null);
+
+    const result = isCloudFrontCookiesEnabled();
+
+    expect(result).toBe(false);
+  });
+
+  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 = isCloudFrontCookiesEnabled();
+
+    expect(result).toBe(false);
+  });
+
+  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 = isCloudFrontCookiesEnabled();
+
+    expect(result).toBe(false);
+  });
+
+  it('returns false when cookieDomain is missing', () => {
+    mockGetCloudFrontConfig.mockReturnValue({
+      domain: 'https://cdn.example.com',
+      imageSigning: 'cookies',
+      privateKey: 'test-key',
+      keyPairId: 'K123',
+    });
+
+    const result = isCloudFrontCookiesEnabled();
+
+    expect(result).toBe(false);
+  });
+
+  it('returns true when all conditions are met', () => {
+    mockGetCloudFrontConfig.mockReturnValue({
+      domain: 'https://cdn.example.com',
+      imageSigning: 'cookies',
+      cookieDomain: '.example.com',
+      privateKey: 'test-key',
+      keyPairId: 'K123',
+    });
+
+    const result = isCloudFrontCookiesEnabled();
+
+    expect(result).toBe(true);
+  });
+});
+
+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('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', () => {
+    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',
+    });
+  });
+
+  it('builds correct custom policy for wildcard 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/*'),
+      }),
+    );
+  });
+
+  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',
+      // cookieDomain is missing
+    });
+
+    const result = setCloudFrontCookies(mockRes as Response);
+
+    expect(result).toBe(false);
+    expect(mockRes.cookie).not.toHaveBeenCalled();
+  });
+
+  it('returns false and logs warning on signing error', () => {
+    mockGetCloudFrontConfig.mockReturnValue({
+      domain: 'https://cdn.example.com',
+      imageSigning: 'cookies',
+      cookieExpiry: 1800,
+      cookieDomain: '.example.com',
+      privateKey: 'invalid-key',
+      keyPairId: 'K123ABC',
+    });
+
+    mockGetSignedCookies.mockImplementation(() => {
+      throw new Error('Invalid private key');
+    });
+
+    const result = setCloudFrontCookies(mockRes as Response);
+
+    expect(result).toBe(false);
+    expect(mockRes.cookie).not.toHaveBeenCalled();
+  });
+});