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: Custom Request Headers For Langfuse (#14945)
Danny Avilaa47ba7168f05
diff --git a/api/server/routes/admin/langfuse.js b/api/server/routes/admin/langfuse.jsindex a8ab284dfd..515a5893b7 100644--- a/api/server/routes/admin/langfuse.js+++ b/api/server/routes/admin/langfuse.js@@ -6,6 +6,7 @@ const {requireCapability,} = require('~/server/middleware/roles/capabilities');const { invalidateConfigCaches } = require('~/server/services/Config');+const configMiddleware = require('~/server/middleware/config/app');const { requireJwtAuth } = require('~/server/middleware');const db = require('~/models');@@ -42,7 +43,10 @@ const handlers = createAdminLangfuseHandlers({invalidateConfigCaches,});-router.use(requireJwtAuth, requireAdminAccess, requireLangfuseManage);+// `configMiddleware` runs last so unauthorized callers are rejected before the+// config resolves; credential verification reads the deployment's Langfuse+// headers off `req.config`, so without it proxied hosts reject every request.+router.use(requireJwtAuth, requireAdminAccess, requireLangfuseManage, configMiddleware);router.get('/connection', handlers.getConnection);router.get('/connection/session/:conversationId', handlers.getSessionLink);diff --git a/api/server/routes/admin/langfuse.test.js b/api/server/routes/admin/langfuse.test.jsindex 10b4d26629..52a1338691 100644--- a/api/server/routes/admin/langfuse.test.js+++ b/api/server/routes/admin/langfuse.test.js@@ -45,6 +45,17 @@ jest.mock('~/server/services/Config', () => ({invalidateConfigCaches: jest.fn(),}));+const mockConfigMiddleware = jest.fn((req, _res, next) => {+ middlewareCalls.push('config');+ req.config = { langfuse: { headers: { 'CF-Access-Client-Id': 'proxy-client' } } };+ next();+});++jest.mock(+ '~/server/middleware/config/app',+ () => (req, res, next) => mockConfigMiddleware(req, res, next),+);+jest.mock('~/models', () => ({findConfigByPrincipal: jest.fn(),patchConfigFields: jest.fn(),@@ -73,7 +84,7 @@ describe('admin Langfuse routes', () => {const response = await request(createApp()).get('/api/admin/langfuse/connection').expect(200);expect(response.body).toEqual({ handler: 'get' });- expect(middlewareCalls).toEqual(['jwt', 'access:admin']);+ expect(middlewareCalls).toEqual(['jwt', 'access:admin', 'config']);expect(mockHasConfigCapability).toHaveBeenCalledWith({id: 'user-1',@@ -100,7 +111,7 @@ describe('admin Langfuse routes', () => {};expect(response.body).toEqual({ handler: expectedHandlers[handlerName] });- expect(middlewareCalls).toEqual(['jwt', 'access:admin']);+ expect(middlewareCalls).toEqual(['jwt', 'access:admin', 'config']);expect(mockHandlers[handlerName]).toHaveBeenCalledTimes(1);});@@ -115,4 +126,30 @@ describe('admin Langfuse routes', () => {expect(mockHandlers[handlerName]).not.toHaveBeenCalled();});++ /**+ * Credential verification reads the deployment's Langfuse headers off+ * `req.config`. The handler unit tests inject `config` into their mock+ * requests, so only the mounted router proves the middleware supplying it is+ * actually wired up — without it a proxied Langfuse host rejects every+ * verification while the handler suite stays green.+ */+ it.each([+ ['PUT', '/api/admin/langfuse/connection', 'updateConnection'],+ ['POST', '/api/admin/langfuse/connection/test', 'testConnection'],+ ])('resolves the app config before %s %s reaches its handler', async (method, path, handler) => {+ await request(createApp())[method.toLowerCase()](path).send({}).expect(200);++ expect(mockConfigMiddleware).toHaveBeenCalledTimes(1);+ const [req] = mockHandlers[handler].mock.calls[0];+ expect(req.config?.langfuse?.headers).toEqual({ 'CF-Access-Client-Id': 'proxy-client' });+ });++ it('resolves the app config only after the access checks reject', async () => {+ canManageLangfuse = false;++ await request(createApp()).post('/api/admin/langfuse/connection/test').send({}).expect(403);++ expect(mockConfigMiddleware).not.toHaveBeenCalled();+ });});diff --git a/api/server/services/Config/loadCustomConfig.js b/api/server/services/Config/loadCustomConfig.jsindex c719a84665..2629ed1c8f 100644--- a/api/server/services/Config/loadCustomConfig.js+++ b/api/server/services/Config/loadCustomConfig.js@@ -2,7 +2,7 @@ const path = require('path');const axios = require('axios');const yaml = require('js-yaml');const keyBy = require('lodash/keyBy');-const { loadYaml } = require('@librechat/api');+const { loadYaml, redactConfigSecretMaps } = require('@librechat/api');const { Providers } = require('@librechat/agents');const { logger } = require('@librechat/data-schemas');const {@@ -156,9 +156,12 @@ https://www.librechat.ai/docs/configuration/stt_tts`);process.exit(1);} else {if (printConfig) {+ // Masks map-valued secrets (e.g. `langfuse.headers`) so literal gateway+ // credentials are not copied into application logs on every startup.+ const loggableConfig = redactConfigSecretMaps(customConfig);logger.info('Custom config file loaded:');- logger.info(JSON.stringify(customConfig, null, 2));- logger.debug('Custom config:', customConfig);+ logger.info(JSON.stringify(loggableConfig, null, 2));+ logger.debug('Custom config:', loggableConfig);}}diff --git a/api/server/services/Config/loadCustomConfig.spec.js b/api/server/services/Config/loadCustomConfig.spec.jsindex ff7ee90629..ca767a5600 100644--- a/api/server/services/Config/loadCustomConfig.spec.js+++ b/api/server/services/Config/loadCustomConfig.spec.js@@ -234,6 +234,33 @@ describe('loadCustomConfig', () => {expect(logger.debug).toHaveBeenCalledWith('Custom config:', mockConfig);});+ it('masks literal Langfuse header credentials in the startup log', async () => {+ const mockConfig = {+ version: '1.0',+ cache: true,+ langfuse: {+ enabled: true,+ publicKey: 'pk-lf-1',+ headers: {+ 'CF-Access-Client-Id': 'client-id',+ 'CF-Access-Client-Secret': 'gateway-credential',+ },+ },+ };+ process.env.CONFIG_PATH = 'validConfig.yaml';+ loadYaml.mockReturnValueOnce(mockConfig);++ const result = await loadCustomConfig();++ const logged = logger.info.mock.calls.map(([value]) => value).join('\n');+ const debugged = JSON.stringify(logger.debug.mock.calls);+ expect(logged).not.toContain('gateway-credential');+ expect(debugged).not.toContain('gateway-credential');+ expect(logged).toContain('***');+ // The masking is for logging only — the live config keeps real values.+ expect(result.langfuse.headers['CF-Access-Client-Secret']).toBe('gateway-credential');+ });+describe('parseCustomParams', () => {const mockConfig = {version: '1.0',diff --git a/librechat.example.yaml b/librechat.example.yamlindex 493ba92060..0d4da0fa5e 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -11,6 +11,35 @@ cache: true# That flow verifies the credentials and stores the secret key encrypted; do not# place a plaintext langfuse.secretKey in this file. Environment-managed central# credentials and optional fanout routing are documented in .env.example.+#+# Self-hosted Langfuse behind an authenticating proxy or gateway can be given+# custom request headers. They are sent on every outbound Langfuse request —+# trace and media export, feedback scores, and credential verification.+# Values support ${ENV_VAR} interpolation; a header whose variable is unset is+# dropped with a warning rather than sent as a literal placeholder.+#+# These are deployment-level: trace export batches spans from every user through+# a single exporter, so unlike endpoints.custom headers they cannot carry+# per-user placeholders such as {{LIBRECHAT_USER_ID}}.+#+# Values are masked in admin config reads and in the startup config log, but+# prefer ${ENV_VAR} references over literal credentials here regardless.+#+# Scope: these are sent only when the deployment configures exactly ONE Langfuse+# origin (a self-hosted base URL, or a single tenant destination URL), and only+# to that origin. The map has no way to say which endpoint it authenticates to,+# so a deployment configuring several origins — e.g. a fanout collector plus a+# separate central host — gets a warning and no headers, rather than having a+# gateway credential sent somewhere it was not meant for.+#+# Fanout deployments additionally need collector support: the gateway forwards+# only Authorization upstream, so a tenant Langfuse behind its own proxy is not+# covered even when the collector receives these.+#+# langfuse:+# headers:+# CF-Access-Client-Id: "${CF_ACCESS_CLIENT_ID}"+# CF-Access-Client-Secret: "${CF_ACCESS_CLIENT_SECRET}"# File storage configuration# Single strategy for all file types (legacy format, still supported)diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.tsindex 1bc8be13c5..7d44f65a12 100644--- a/packages/api/src/admin/config.handler.spec.ts+++ b/packages/api/src/admin/config.handler.spec.ts@@ -436,6 +436,50 @@ describe('createAdminConfigHandlers', () => {expect(deps.upsertConfig).not.toHaveBeenCalled();});+ it('rejects Langfuse header overrides, which cannot be encrypted at rest', async () => {+ const { handlers, deps } = createHandlers();+ const req = mockReq({+ params: { principalType: 'user', principalId: 'u1' },+ body: {+ overrides: {+ langfuse: { enabled: true, headers: { 'X-Proxy-Token': 'leaked' } },+ },+ },+ });+ const res = mockRes();++ await handlers.upsertConfigOverrides(req, res);++ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Langfuse request headers can only be configured in librechat.yaml',+ });+ expect(deps.upsertConfig).not.toHaveBeenCalled();+ });++ it.each([+ ['nested dotted key', { langfuse: { 'headers.X-Proxy-Token': 'credential' } }],+ ['root dotted path', { 'langfuse.headers': { 'X-Proxy-Token': 'credential' } }],+ ['root dotted header path', { 'langfuse.headers.X-Proxy-Token': 'credential' }],+ ])('rejects Langfuse headers supplied as a %s', async (_label, overrides) => {+ const { handlers, deps } = createHandlers();+ const res = mockRes();++ await handlers.upsertConfigOverrides(+ mockReq({ params: { principalType: 'user', principalId: 'u1' }, body: { overrides } }),+ res,+ );++ /** `overrides` is a Mixed document written wholesale, so a dotted key+ * persists verbatim and the nested-map redactor never walks it — the+ * credential would come back in plaintext on the next read. */+ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Langfuse request headers can only be configured in librechat.yaml',+ });+ expect(deps.upsertConfig).not.toHaveBeenCalled();+ });+it('rejects process-backed MCP servers supplied through the runtime config alias', async () => {const { handlers, deps } = createHandlers();const req = mockReq({@@ -1042,6 +1086,27 @@ describe('createAdminConfigHandlers', () => {expect(deps.patchConfigFields).not.toHaveBeenCalled();});+ it('rejects Langfuse header field patches, including a single header path', async () => {+ const { handlers, deps } = createHandlers();++ for (const fieldPath of ['langfuse.headers', 'langfuse.headers.X-Proxy-Token']) {+ const res = mockRes();+ await handlers.patchConfigField(+ mockReq({+ params: { principalType: 'user', principalId: 'u1' },+ body: { entries: [{ fieldPath, value: 'leaked' }] },+ }),+ res,+ );++ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Langfuse request headers can only be configured in librechat.yaml',+ });+ }+ expect(deps.patchConfigFields).not.toHaveBeenCalled();+ });+it('rejects process-backed MCP field patches through the runtime config alias', async () => {const { handlers, deps } = createHandlers();const req = mockReq({diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.tsindex b6961eacd3..20852cc1a3 100644--- a/packages/api/src/admin/config.ts+++ b/packages/api/src/admin/config.ts@@ -36,6 +36,41 @@ const BASE_ONLY_OVERRIDE_SECTIONS = new Set<string>(BASE_ONLY_CONFIG_SECTIONS);const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set<string>(BASE_PRINCIPAL_CONFIG_SECTIONS);const PROCESS_MCP_CONFIG_ERROR ='Process-backed MCP servers can only be configured in librechat.yaml';+const LANGFUSE_HEADERS_CONFIG_ERROR =+ 'Langfuse request headers can only be configured in librechat.yaml';++/**+ * Langfuse export headers carry proxy/gateway credentials, but they are a map+ * of values rather than one scalar path, so the config secret registry cannot+ * encrypt them at rest or mask them on read. Keeping them out of stored+ * overrides is what makes them deployment-level: an admin-written map would sit+ * in Mongo in plaintext and come back in plaintext, unlike `langfuse.secretKey`.+ */+function isLangfuseHeadersFieldPath(fieldPath: string): boolean {+ return fieldPath === 'langfuse.headers' || fieldPath.startsWith('langfuse.headers.');+}++/**+ * Whether an overrides payload carries Langfuse headers under any spelling.+ *+ * `overrides` is a Mixed document written wholesale, so a dotted property name+ * survives verbatim: `{ langfuse: { "headers.X-Token": "..." } }` and+ * `{ "langfuse.headers": {...} }` both persist a credential that the nested-map+ * redactor never walks, and a later read returns it unchanged.+ */+function hasLangfuseHeadersOverride(rawOverrides: Record<string, unknown>): boolean {+ for (const key of Object.keys(rawOverrides)) {+ if (key === 'langfuse.headers' || key.startsWith('langfuse.headers.')) {+ return true;+ }+ }++ const rawLangfuse = rawOverrides.langfuse;+ if (rawLangfuse == null || typeof rawLangfuse !== 'object' || Array.isArray(rawLangfuse)) {+ return false;+ }+ return Object.keys(rawLangfuse).some((key) => key === 'headers' || key.startsWith('headers.'));+}export function isValidFieldPath(path: string): boolean {return (@@ -527,6 +562,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: PROCESS_MCP_CONFIG_ERROR });}+ if (hasLangfuseHeadersOverride(rawOverrides)) {+ return res.status(400).json({ error: LANGFUSE_HEADERS_CONFIG_ERROR });+ }+if (priority != null && (typeof priority !== 'number' || priority < 0)) {return res.status(400).json({ error: 'priority must be a non-negative number' });}@@ -731,6 +770,9 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {if (isProcessMCPServerFieldPath(entry.fieldPath, entry.value)) {return res.status(400).json({ error: PROCESS_MCP_CONFIG_ERROR });}+ if (isLangfuseHeadersFieldPath(entry.fieldPath)) {+ return res.status(400).json({ error: LANGFUSE_HEADERS_CONFIG_ERROR });+ }if (isConfigSecretDescendantPath(entry.fieldPath)) {return res.status(400)diff --git a/packages/api/src/admin/index.ts b/packages/api/src/admin/index.tsindex ef8ec27ad0..2f52e1cccf 100644--- a/packages/api/src/admin/index.ts+++ b/packages/api/src/admin/index.ts@@ -6,7 +6,7 @@ export { createAdminRolesHandlers } from './roles';export { createAdminSkillsSyncAccess, createAdminSkillsSyncHandlers } from './skills';export { createAdminUsersHandlers } from './users';export { createAdminAuditLogHandlers } from './auditLog';-export { resolveConfigSecret } from './secrets';+export { resolveConfigSecret, redactConfigSecretMaps } from './secrets';export type { AdminConfigDeps } from './config';export type { AdminLangfuseDeps } from './langfuse';export type { AdminGrantsDeps, GrantPrincipalType } from './grants';diff --git a/packages/api/src/admin/langfuse.handler.spec.ts b/packages/api/src/admin/langfuse.handler.spec.tsindex b316aca328..474029cab1 100644--- a/packages/api/src/admin/langfuse.handler.spec.ts+++ b/packages/api/src/admin/langfuse.handler.spec.ts@@ -957,5 +957,119 @@ describe('createAdminLangfuseHandlers', () => {expect(res.body).toEqual({ success: false, errorCode: 'missing_secret' });expect(global.fetch).not.toHaveBeenCalled();});++ it('sends the deployment headers on both verification requests', async () => {+ /** Single-tenant topology with one configured Langfuse origin — the+ * self-hosted-behind-a-proxy case — so the header map is unambiguous. */+ delete process.env.TENANT_ISOLATION_STRICT;+ delete process.env.LANGFUSE_FANOUT_ENABLED;+ delete process.env.LANGFUSE_FANOUT_COLLECTOR_URL;+ process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL = 'https://eu.langfuse.internal';+ global.fetch = jest+ .fn()+ .mockResolvedValueOnce(projectResponse())+ .mockResolvedValueOnce({ ok: true, status: 207 }) as unknown as typeof fetch;+ const { handlers } = createHandlers();+ const res = mockRes();++ await handlers.testConnection(+ mockReq({+ body: { destination: 'eu', publicKey: 'pk', secretKey: 'sk' },+ config: { langfuse: { headers: { 'CF-Access-Client-Id': 'proxy-client' } } },+ }),+ res,+ );++ expect(res.body).toEqual({ success: true });+ const [, projectsInit] = (global.fetch as unknown as jest.Mock).mock.calls[0];+ expect(projectsInit.headers['CF-Access-Client-Id']).toBe('proxy-client');+ expect(projectsInit.headers.Authorization).toMatch(/^Basic /);+ const [, ingestionInit] = (global.fetch as unknown as jest.Mock).mock.calls[1];+ expect(ingestionInit.headers['CF-Access-Client-Id']).toBe('proxy-client');+ expect(ingestionInit.headers.Authorization).toBe('Bearer pk');+ delete process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL;+ });++ it('withholds deployment headers when several Langfuse origins are configured', async () => {+ /** The collector from `beforeEach` plus an explicit tenant URL: the map+ * does not say which of them it authenticates to, so neither gets it. */+ process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL = 'https://eu.langfuse.internal';+ global.fetch = jest+ .fn()+ .mockResolvedValueOnce(projectResponse())+ .mockResolvedValueOnce({ ok: true, status: 207 }) as unknown as typeof fetch;+ const { handlers } = createHandlers();+ const res = mockRes();++ await handlers.testConnection(+ mockReq({+ body: { destination: 'eu', publicKey: 'pk', secretKey: 'sk' },+ config: { langfuse: { headers: { 'CF-Access-Client-Id': 'ambiguous-token' } } },+ }),+ res,+ );++ expect(JSON.stringify((global.fetch as unknown as jest.Mock).mock.calls)).not.toContain(+ 'ambiguous-token',+ );+ delete process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL;+ });++ it('withholds deployment headers when verifying an unconfigured destination', async () => {+ global.fetch = jest+ .fn()+ .mockResolvedValueOnce(projectResponse())+ .mockResolvedValueOnce({ ok: true, status: 207 }) as unknown as typeof fetch;+ const { handlers } = createHandlers();+ const res = mockRes();++ await handlers.testConnection(+ mockReq({+ body: { destination: 'eu', publicKey: 'pk', secretKey: 'sk' },+ config: { langfuse: { headers: { 'CF-Access-Client-Id': 'internal-gateway' } } },+ }),+ res,+ );++ /** `eu` here is the built-in Langfuse Cloud default; an admin selecting it+ * must not ship the internal gateway credential to that origin. */+ const calls = (global.fetch as unknown as jest.Mock).mock.calls;+ expect(JSON.stringify(calls)).not.toContain('internal-gateway');+ });++ it.each(['Authorization', 'authorization'])(+ 'keeps the Langfuse authorization when a deployment %s header collides',+ async (headerName) => {+ global.fetch = jest+ .fn()+ .mockResolvedValueOnce(projectResponse())+ .mockResolvedValueOnce({ ok: true, status: 207 }) as unknown as typeof fetch;+ const { handlers } = createHandlers();+ const res = mockRes();++ delete process.env.TENANT_ISOLATION_STRICT;+ delete process.env.LANGFUSE_FANOUT_ENABLED;+ delete process.env.LANGFUSE_FANOUT_COLLECTOR_URL;+ process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL = 'https://eu.langfuse.internal';+ await handlers.testConnection(+ mockReq({+ body: { destination: 'eu', publicKey: 'pk', secretKey: 'sk' },+ config: { langfuse: { headers: { [headerName]: 'Bearer proxy-token' } } },+ }),+ res,+ );+ delete process.env.LANGFUSE_FANOUT_TENANT_EU_BASE_URL;++ const [, projectsInit] = (global.fetch as unknown as jest.Mock).mock.calls[0];+ const headers = projectsInit.headers as Record<string, string>;+ /** A surviving case variant would be appended by fetch rather than+ * replaced, sending both credentials in one combined value. */+ expect(+ Object.keys(headers).filter((key) => key.toLowerCase() === 'authorization'),+ ).toHaveLength(1);+ expect(Object.values(headers)).not.toContain('Bearer proxy-token');+ expect(Object.values(headers).some((value) => value.startsWith('Basic '))).toBe(true);+ },+ );});});diff --git a/packages/api/src/admin/langfuse.ts b/packages/api/src/admin/langfuse.tsindex f7906d34f4..6a77fd6568 100644--- a/packages/api/src/admin/langfuse.ts+++ b/packages/api/src/admin/langfuse.ts@@ -2,7 +2,6 @@ import { PrincipalType, PrincipalModel } from 'librechat-data-provider';import { logger, BASE_CONFIG_PRINCIPAL_ID } from '@librechat/data-schemas';import type {TCustomConfig,- LangfuseConfig,TLangfuseConnectionStatus,TUpdateLangfuseConnectionRequest,TLangfuseConnectionTestErrorCode,@@ -19,9 +18,11 @@ import {getLangfuseTenantDestinations,resolveLangfuseTenantDestination,} from '~/langfuse/tenantDestinations';+import { getLangfuseDestinationId, scopeHeadersToDestination } from '~/langfuse/destinations';+import { redirectPolicyFor, resolveLangfuseHeaders } from '~/langfuse/utils';import { decryptConfigSecret, encryptConfigSecretFields } from './secrets';-import { getLangfuseDestinationId } from '~/langfuse/destinations';import { isLangfuseConnectionAvailable } from '~/langfuse/policy';+import { mergeHeaders } from '~/utils/headers';const DEFAULT_PRIORITY = 10;const ENCRYPTED_PREFIX = 'v3:';@@ -56,7 +57,10 @@ function getTenantId(req: ServerRequest): string | undefined {return (req.user as { tenantId?: string } | undefined)?.tenantId;}-function readStoredLangfuse(config: IConfig | null): LangfuseConfig | undefined {+/** Reads from the stored override tree, so this is `TCustomConfig`'s+ * `DeepPartial` view of the section rather than the standalone+ * `LangfuseConfig` — record-valued fields carry optional values here. */+function readStoredLangfuse(config: IConfig | null): TCustomConfig['langfuse'] {const overrides = config?.overrides as Partial<TCustomConfig> | undefined;return overrides?.langfuse;}@@ -136,13 +140,15 @@ async function verifyLangfuseCredentials(destination: LangfuseTenantDestination,publicKey: string,secretKey: string,+ headers?: Record<string, string>,): Promise<LangfuseVerificationResult> {try {const auth = Buffer.from(`${publicKey}:${secretKey}`).toString('base64');const signal = AbortSignal.timeout(LANGFUSE_VERIFICATION_TIMEOUT_MS);const secretResponse = await fetch(`${destination.baseUrl}/api/public/projects`, {- headers: { Authorization: `Basic ${auth}` },+ headers: mergeHeaders(headers, { Authorization: `Basic ${auth}` }),signal,+ ...redirectPolicyFor(headers),});if (!secretResponse.ok) {return {@@ -181,13 +187,14 @@ async function verifyLangfuseCredentials(const publicResponse = await fetch(`${destination.baseUrl}/api/public/ingestion`, {method: 'POST',- headers: {+ headers: mergeHeaders(headers, {Authorization: `Bearer ${publicKey}`,'X-Langfuse-Public-Key': publicKey,'Content-Type': 'application/json',- },+ }),body: JSON.stringify({ batch: [] }),signal,+ ...redirectPolicyFor(headers),});if (!publicResponse.ok) {return {@@ -372,6 +379,10 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {tenantDestination,publicKey,secretKey,+ scopeHeadersToDestination(+ resolveLangfuseHeaders(req.config?.langfuse?.headers),+ tenantDestination.baseUrl,+ ),);if (!verification.success) {return res@@ -463,7 +474,15 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {return res.status(200).json(failed);}- const result = await verifyLangfuseCredentials(tenantDestination, publicKey, secretKey);+ const result = await verifyLangfuseCredentials(+ tenantDestination,+ publicKey,+ secretKey,+ scopeHeadersToDestination(+ resolveLangfuseHeaders(req.config?.langfuse?.headers),+ tenantDestination.baseUrl,+ ),+ );const response: TLangfuseConnectionTestResponse = result.success? { success: true }: { success: false, errorCode: result.errorCode };diff --git a/packages/api/src/admin/secrets.spec.ts b/packages/api/src/admin/secrets.spec.tsindex 39557454a6..d076bc069f 100644--- a/packages/api/src/admin/secrets.spec.ts+++ b/packages/api/src/admin/secrets.spec.ts@@ -208,6 +208,38 @@ describe('Langfuse config secrets', () => {});});+ it('masks Langfuse header values while keeping their names', () => {+ const redacted = redactConfigSecrets({+ langfuse: {+ enabled: true,+ publicKey: 'pk-lf-1',+ headers: {+ 'CF-Access-Client-Id': 'client-id',+ 'CF-Access-Client-Secret': 'gateway-credential',+ },+ },+ });++ /** These reach `GET /api/admin/config/base` from librechat.yaml, where no+ * scalar secret registration covers them — unmasked, any delegated admin+ * with Langfuse read access receives the raw gateway credential. */+ expect(redacted.langfuse).toEqual({+ enabled: true,+ publicKey: 'pk-lf-1',+ headers: { 'CF-Access-Client-Id': '***', 'CF-Access-Client-Secret': '***' },+ });+ expect(JSON.stringify(redacted)).not.toContain('gateway-credential');+ });++ it('drops a malformed Langfuse headers value rather than serializing it', () => {+ const redacted = redactConfigSecrets({+ langfuse: { publicKey: 'pk-lf-1', headers: 'Bearer raw-credential' },+ });++ expect(redacted.langfuse).toEqual({ publicKey: 'pk-lf-1' });+ expect(JSON.stringify(redacted)).not.toContain('raw-credential');+ });+it('strips legacy displaySecretKey companions and migrates them on preserve', () => {const redacted = redactConfigSecrets({langfuse: { publicKey: 'pk-lf-1', secretKey: 'v3:abc:def', displaySecretKey: 'sk-lf-...old' },diff --git a/packages/api/src/admin/secrets.ts b/packages/api/src/admin/secrets.tsindex 2e80d3b5e4..8064dd6735 100644--- a/packages/api/src/admin/secrets.ts+++ b/packages/api/src/admin/secrets.ts@@ -781,11 +781,68 @@ export function preserveConfigSecrets<T>(next: T, existing?: unknown, basePath =return result;}+/**+ * Config paths holding a *map* of sensitive values rather than one scalar.+ * `CONFIG_SECRET_FIELDS` cannot describe these — it keys off a single path and+ * a `<path>Preview` companion — so they are masked on read instead.+ *+ * These are yaml-only (admin writes are rejected), which is what makes masking+ * safe: a masked read can never be round-tripped back over the real values.+ */+const CONFIG_SECRET_MAP_FIELDS: readonly string[] = ['langfuse.headers'];+const MASKED_MAP_VALUE = '***';++/**+ * Replaces every value of a registered secret map with a fixed mask, keeping+ * the key names so an admin can still see *which* headers a deployment sets+ * without receiving the gateway credentials themselves.+ */+/**+ * Masks registered secret maps on a cloned config, for callers outside the+ * admin read path that also serialize configuration — notably the startup+ * "Custom config file loaded" log, which would otherwise copy every literal+ * gateway credential into application logs.+ *+ * Only handles map-valued secrets; scalar secrets keep whatever handling the+ * caller already applies.+ */+export function redactConfigSecretMaps<T>(root: T): T {+ const clone = JSON.parse(JSON.stringify(root)) as T;+ const rootRecord = getPlainRecord(clone);+ if (!rootRecord) {+ return clone;+ }+ redactSecretMapFields(rootRecord);+ return clone;+}++function redactSecretMapFields(rootRecord: Record<string, unknown>): void {+ for (const path of CONFIG_SECRET_MAP_FIELDS) {+ const segments = path.split('.');+ const parent = walkToParent(rootRecord, segments);+ const key = segments[segments.length - 1];+ const value = parent?.[key];+ const map = getPlainRecord(value);+ if (parent == null) {+ continue;+ }+ if (map == null) {+ /** A non-object here is malformed for this path; drop it rather than+ * risk serializing a raw string credential. */+ if (value !== undefined) {+ delete parent[key];+ }+ continue;+ }+ parent[key] = Object.fromEntries(Object.keys(map).map((name) => [name, MASKED_MAP_VALUE]));+ }+}+/*** Deletes registered secret values from `root` in place so admin reads never* return them (encrypted or plaintext). Preview companions and plain* `${ENV_VAR}` references (for fields that allow them) are preserved.- * The caller passes a cloned object.+ * Secret *maps* are masked value-by-value. The caller passes a cloned object.*/export function redactConfigSecrets<T>(root: T): T {const rootRecord = getPlainRecord(root);@@ -793,6 +850,8 @@ export function redactConfigSecrets<T>(root: T): T {return root;}+ redactSecretMapFields(rootRecord);+for (const key of Object.keys(rootRecord)) {if (key.includes('.') && isConfigSecretRelatedPath(key)) {delete rootRecord[key];diff --git a/packages/api/src/langfuse/config.spec.ts b/packages/api/src/langfuse/config.spec.tsindex 6f10d6ee8b..76c53bb7d0 100644--- a/packages/api/src/langfuse/config.spec.ts+++ b/packages/api/src/langfuse/config.spec.ts@@ -475,4 +475,442 @@ describe('buildLangfuseConfig', () => {});},);++ it('sends configured headers with env-credential central export', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { buildLangfuseConfig } = await import('./config');++ expect(+ buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: { headers: { 'CF-Access-Client-Id': 'proxy-client' } },+ } as unknown as AppConfig,+ }),+ ).toEqual({+ deterministicTraceId: true,+ publicKey: 'pk-env',+ secretKey: 'sk-env',+ baseUrl: 'https://langfuse.internal',+ additionalHeaders: { 'CF-Access-Client-Id': 'proxy-client' },+ });+ });++ it('sends configured headers with a stored tenant connection', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_FANOUT_TENANT_US_BASE_URL = 'https://us.langfuse.internal';+ const { encryptV3 } = await import('@librechat/data-schemas');+ const { buildLangfuseConfig } = await import('./config');++ expect(+ buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ enabled: true,+ publicKey: 'pk-stored',+ secretKey: encryptV3('sk-stored'),+ destination: 'us',+ headers: { 'X-Proxy-Token': 'tenant-token' },+ },+ } as unknown as AppConfig,+ }),+ ).toEqual({+ deterministicTraceId: true,+ publicKey: 'pk-stored',+ secretKey: 'sk-stored',+ baseUrl: 'https://us.langfuse.internal',+ additionalHeaders: { 'X-Proxy-Token': 'tenant-token' },+ });+ delete process.env.LANGFUSE_FANOUT_TENANT_US_BASE_URL;+ });++ it('withholds headers from an origin the deployment never configured', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ const { encryptV3 } = await import('@librechat/data-schemas');+ const { buildLangfuseConfig } = await import('./config');++ /** The destination here is the built-in Langfuse Cloud default. A proxy+ * credential meant for an internal gateway must not be disclosed to a+ * third-party origin the operator never pointed at. */+ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ enabled: true,+ publicKey: 'pk-stored',+ secretKey: encryptV3('sk-stored'),+ destination: 'us',+ headers: { 'X-Proxy-Token': 'internal-gateway-token' },+ },+ } as unknown as AppConfig,+ });++ expect(built).not.toHaveProperty('additionalHeaders');+ expect(JSON.stringify(built)).not.toContain('internal-gateway-token');+ });++ it('withholds headers from central cloud export while the collector still receives them', async () => {+ process.env.LANGFUSE_FANOUT_ENABLED = 'true';+ process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector:4318';+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ const { buildLangfuseConfig } = await import('./config');++ const appConfig = {+ langfuse: { headers: { 'X-Gateway-Key': 'gateway' } },+ } as unknown as AppConfig;++ expect(buildLangfuseConfig({ tenantId: 'tenant-1', appConfig })).toMatchObject({+ baseUrl: 'http://collector:4318',+ additionalHeaders: { 'X-Gateway-Key': 'gateway' },+ });++ /** Without fanout the same config exports straight to Langfuse Cloud, which+ * must not receive the collector's credential. */+ delete process.env.LANGFUSE_FANOUT_ENABLED;+ delete process.env.LANGFUSE_FANOUT_COLLECTOR_URL;+ delete process.env.TENANT_ISOLATION_STRICT;+ const direct = buildLangfuseConfig({ runId: 'run-1', appConfig });+ expect(direct).toMatchObject({ baseUrl: 'https://cloud.langfuse.com' });+ expect(direct).not.toHaveProperty('additionalHeaders');+ });++ it('sends configured headers to the fanout collector', async () => {+ process.env.LANGFUSE_FANOUT_ENABLED = 'true';+ process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector:4318';+ const { buildLangfuseConfig } = await import('./config');++ expect(+ buildLangfuseConfig({+ tenantId: 'tenant-1',+ appConfig: {+ langfuse: { headers: { 'X-Gateway-Key': 'gateway' } },+ } as unknown as AppConfig,+ }),+ ).toMatchObject({+ baseUrl: 'http://collector:4318',+ additionalHeaders: { 'X-Gateway-Key': 'gateway' },+ });+ });++ it('interpolates env vars in headers and drops the unresolved', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_PROXY_TOKEN = 'resolved-token';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Proxy-Token': '${LANGFUSE_PROXY_TOKEN}',+ 'X-Missing': '${LANGFUSE_HEADER_NOT_SET}',+ 'X-Blank': ' ',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ expect(built.additionalHeaders).toEqual({ 'X-Proxy-Token': 'resolved-token' });+ delete process.env.LANGFUSE_PROXY_TOKEN;+ });++ it('collapses case-variant header names to a single spelling', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ authorization: 'Bearer first',+ AUTHORIZATION: 'Bearer second',+ 'X-Other': 'kept',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** Two spellings surviving would let one slip past the single-key+ * displacement in `mergeHeaders` and be appended by fetch. */+ expect(+ Object.keys(built.additionalHeaders ?? {}).filter(+ (key) => key.toLowerCase() === 'authorization',+ ),+ ).toHaveLength(1);+ expect(built.additionalHeaders?.['X-Other']).toBe('kept');+ });++ it('encodes header values that fetch cannot transmit verbatim', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_TEAM_HEADER = 'Marić';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Latin1': 'José',+ 'X-Extended': 'Marić',+ 'X-FromEnv': '${LANGFUSE_TEAM_HEADER}',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** Characters above U+00FF throw in the `Headers` constructor, so they must+ * be encoded before they reach any request. Latin-1 passes through. */+ expect(built.additionalHeaders?.['X-Latin1']).toBe('José');+ expect(built.additionalHeaders?.['X-Extended']).toBe('b64:TWFyacSH');+ expect(built.additionalHeaders?.['X-FromEnv']).toBe('b64:TWFyacSH');+ expect(() => new Headers(built.additionalHeaders)).not.toThrow();+ delete process.env.LANGFUSE_TEAM_HEADER;+ });++ it('drops header names that are not valid HTTP tokens', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X Proxy Token': 'spaces',+ 'X-Proxy-Token:': 'colon',+ ' X-Padded ': 'trimmed-to-valid',+ 'X-Valid': 'kept',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** An invalid name throws in the `Headers` constructor, which would take+ * down every request rather than just this header. */+ expect(built.additionalHeaders).toEqual({+ 'X-Padded': 'trimmed-to-valid',+ 'X-Valid': 'kept',+ });+ expect(() => new Headers(built.additionalHeaders)).not.toThrow();+ });++ it('keeps a resolved credential that itself contains ${...}', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_PROXY_TOKEN = 'abc${def}ghi';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Proxy-Token': '${LANGFUSE_PROXY_TOKEN}',+ 'X-Missing': '${LANGFUSE_HEADER_NOT_SET}',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** Gateway tokens are arbitrary strings; testing the *resolved* text for+ * `${...}` cannot distinguish a failed substitution from a credential+ * that merely contains those characters. */+ expect(built.additionalHeaders).toEqual({ 'X-Proxy-Token': 'abc${def}ghi' });+ delete process.env.LANGFUSE_PROXY_TOKEN;+ });++ it('does not strip a user placeholder that a resolved credential contains', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_PROXY_TOKEN = 'abc{{LIBRECHAT_USER_ID}}ghi';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Proxy-Token': '${LANGFUSE_PROXY_TOKEN}',+ 'X-Templated': 'keep{{LIBRECHAT_USER_ID}}me',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** The placeholder in the *configured* value is stripped; an identical span+ * that arrives inside the resolved credential is data, not syntax. */+ expect(built.additionalHeaders).toEqual({+ 'X-Proxy-Token': 'abc{{LIBRECHAT_USER_ID}}ghi',+ 'X-Templated': 'keepme',+ });+ delete process.env.LANGFUSE_PROXY_TOKEN;+ });++ it('does not re-expand a placeholder that a resolved credential contains', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_EMBEDDED_NAME = 'SHOULD-NOT-APPEAR';+ process.env.LANGFUSE_PROXY_TOKEN = 'abc${LANGFUSE_EMBEDDED_NAME}ghi';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: { headers: { 'X-Proxy-Token': '${LANGFUSE_PROXY_TOKEN}' } },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** The embedded name is *set* here, so a second expansion pass would+ * rewrite the credential rather than leave it — the earlier test only+ * covered an unset name and could not catch that. */+ expect(built.additionalHeaders).toEqual({+ 'X-Proxy-Token': 'abc${LANGFUSE_EMBEDDED_NAME}ghi',+ });+ delete process.env.LANGFUSE_EMBEDDED_NAME;+ delete process.env.LANGFUSE_PROXY_TOKEN;+ });++ it('drops headers referencing infrastructure secrets', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.JWT_SECRET = 'super-secret-jwt';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: { headers: { 'X-Leak': '${JWT_SECRET}' } },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ expect(built).not.toHaveProperty('additionalHeaders');+ expect(JSON.stringify(built)).not.toContain('super-secret-jwt');+ });++ it('drops header values carrying bytes illegal in an HTTP header', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Injected': 'token\r\nX-Evil: injected',+ 'X-Nul': 'tok en',+ 'X-Trailing-Newline': 'token\n',+ 'X-Clean': 'token',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** A trailing newline is the common `$(cat secret)` case and is trimmed;+ * an embedded CRLF is a request-splitting attempt and is dropped. */+ expect(built.additionalHeaders).toEqual({+ 'X-Trailing-Newline': 'token',+ 'X-Clean': 'token',+ });+ expect(() => new Headers(built.additionalHeaders)).not.toThrow();+ });++ it('expands a value built from several env references', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ process.env.LANGFUSE_CLIENT_ID = 'client-id';+ process.env.LANGFUSE_CLIENT_SECRET = 'client-secret';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'X-Pair': '${LANGFUSE_CLIENT_ID}:${LANGFUSE_CLIENT_SECRET}',+ 'X-Suffixed': 'Bearer ${LANGFUSE_CLIENT_SECRET}',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** `extractEnvVariable`'s anchored branch is greedy, so a value that both+ * starts and ends with a reference parses as one variable named+ * `LANGFUSE_CLIENT_ID}:${LANGFUSE_CLIENT_SECRET` and is sent raw. */+ expect(built.additionalHeaders).toEqual({+ 'X-Pair': 'client-id:client-secret',+ 'X-Suffixed': 'Bearer client-secret',+ });+ delete process.env.LANGFUSE_CLIENT_ID;+ delete process.env.LANGFUSE_CLIENT_SECRET;+ });++ it('drops headers that control request framing', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { buildLangfuseConfig } = await import('./config');++ const built = buildLangfuseConfig({+ runId: 'run-1',+ appConfig: {+ langfuse: {+ headers: {+ 'Transfer-Encoding': 'chunked',+ 'content-length': '42',+ Host: 'elsewhere.example',+ 'X-Valid': 'kept',+ },+ },+ } as unknown as AppConfig,+ }) as { additionalHeaders?: Record<string, string> };++ /** One of these on the shared map breaks every request the map is attached+ * to, rather than being ignored for that header. */+ expect(built.additionalHeaders).toEqual({ 'X-Valid': 'kept' });+ });++ it('omits headers entirely when none are configured', async () => {+ delete process.env.TENANT_ISOLATION_STRICT;+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';+ process.env.LANGFUSE_SECRET_KEY = 'sk-env';+ const { buildLangfuseConfig } = await import('./config');++ expect(+ buildLangfuseConfig({+ runId: 'run-1',+ appConfig: { langfuse: { headers: {} } } as unknown as AppConfig,+ }),+ ).not.toHaveProperty('additionalHeaders');+ });});diff --git a/packages/api/src/langfuse/config.ts b/packages/api/src/langfuse/config.tsindex cdea9160a7..b5232ac1fc 100644--- a/packages/api/src/langfuse/config.ts+++ b/packages/api/src/langfuse/config.ts@@ -9,8 +9,9 @@ import {isLangfuseTracingEnabled,usesLangfuseMultiTenantRouting,} from './policy';+import { normalizeBoolean, resolveLangfuseHeaders, resolveTenantCredentials } from './utils';import { resolveLangfuseTenantDestination } from './tenantDestinations';-import { normalizeBoolean, resolveTenantCredentials } from './utils';+import { scopeHeadersToDestination } from './destinations';import { normalizeString } from '~/utils/text';import { traceIdForMessage } from './trace';@@ -18,6 +19,7 @@ type LangfuseRunConfig = NonNullable<RunConfig['langfuse']>;type LangfuseRunConfigWithTraceAttributes = LangfuseRunConfig & {librechatTraceAttributes?: Record<string, string | number | boolean | null | undefined>;mediaUploadEnabled?: boolean;+ additionalHeaders?: Record<string, string>;};type LangfuseTenantDestination = NonNullable<ReturnType<typeof resolveLangfuseTenantDestination>>;type LangfuseExportPlan =@@ -77,6 +79,28 @@ function applyCentralEnvConfig(langfuse: LangfuseRunConfigWithTraceAttributes):}}+/**+ * Attaches the deployment's headers only once the export branch has settled on+ * a `baseUrl`, and only when that origin is one the operator configured.+ *+ * A run resolves to a single destination, but which one depends on the branch —+ * attaching earlier would send a gateway credential to whatever endpoint the+ * config happened to fall through to, including Langfuse Cloud.+ */+function applyCustomHeaders(+ langfuse: LangfuseRunConfigWithTraceAttributes,+ additionalHeaders?: Record<string, string>,+): LangfuseRunConfigWithTraceAttributes {+ if (langfuse.enabled === false || langfuse.baseUrl == null) {+ return langfuse;+ }+ const scoped = scopeHeadersToDestination(additionalHeaders, langfuse.baseUrl);+ if (scoped) {+ langfuse.additionalHeaders = scoped;+ }+ return langfuse;+}+function disableCentralExport(langfuse: LangfuseRunConfigWithTraceAttributes): void {langfuse.librechatTraceAttributes = {...(langfuse.librechatTraceAttributes ?? {}),@@ -166,6 +190,8 @@ export function buildLangfuseConfig({return langfuse;}+ const additionalHeaders = resolveLangfuseHeaders(config?.headers);+const tenantLangfuseEnabled = normalizeBoolean(config?.enabled) === true;if (!centralTraceExportEnabled) {disableCentralExport(langfuse);@@ -190,7 +216,7 @@ export function buildLangfuseConfig({} else if (config != null) {langfuse.enabled = false;}- return langfuse;+ return applyCustomHeaders(langfuse, additionalHeaders);}const exportPlan = resolveLangfuseExportPlan({@@ -217,9 +243,11 @@ export function buildLangfuseConfig({...(!centralTraceExportEnabled ? [CENTRAL_MEDIA_DISABLED_SEGMENT] : []),].join('/'),);- // TODO: Add support in @librechat/agents for Langfuse additionalHeaders and- // route by headers if we need multiple tenant Langfuse exports for one run.- // The destination-scoped URL is the current app-to-gateway routing contract.+ // Fanout routing stays destination-scoped by URL. `additionalHeaders` is+ // now available (and carries the deployment's proxy headers), but routing+ // multiple tenant Langfuse exports for one run by header would need the+ // collector to demultiplex them — the URL remains the app-to-gateway+ // routing contract until that is required.langfuse.librechatTraceAttributes = {...(langfuse.librechatTraceAttributes ?? {}),[TENANT_EXPORT_ATTRIBUTE]: 'true',@@ -240,5 +268,5 @@ export function buildLangfuseConfig({break;}- return langfuse;+ return applyCustomHeaders(langfuse, additionalHeaders);}diff --git a/packages/api/src/langfuse/destinations.ts b/packages/api/src/langfuse/destinations.tsindex ac5f6a7d36..54ccdf122b 100644--- a/packages/api/src/langfuse/destinations.ts+++ b/packages/api/src/langfuse/destinations.ts@@ -8,8 +8,19 @@ import {isLangfuseTraceSampled,usesLangfuseMultiTenantRouting,} from './policy';-import { normalizeBoolean, resolveTenantCredentials, toBasicAuthorization } from './utils';-import { resolveLangfuseTenantDestination } from './tenantDestinations';+import {+ normalizeBoolean,+ redirectPolicyFor,+ resolveLangfuseHeaders,+ resolveTenantCredentials,+ toBasicAuthorization,+} from './utils';+import {+ allowsLangfuseCustomHeaders,+ hasAmbiguousLangfuseOrigins,+ resolveLangfuseTenantDestination,+} from './tenantDestinations';+import { mergeHeaders } from '~/utils/headers';import { normalizeString } from '~/utils/text';import { traceIdForMessage } from './trace';@@ -28,6 +39,8 @@ export type LangfuseScoreDestination = {name: 'central' | 'tenant' | 'connection';baseUrl: string;authorization: string;+ /** Deployment proxy/gateway headers, merged beneath `Authorization`. */+ headers?: Record<string, string>;};export type LangfuseScoreDestinationOptions = {@@ -40,6 +53,30 @@ export type LangfuseScoreDestinationOptions = {centralTraceExportEnabled?: boolean;};+let warnedAmbiguousOrigins = false;++/** Drops the deployment's headers unless this destination is the one configured+ * Langfuse origin — a run can resolve to several destinations, and only the+ * intended one may receive the gateway credential. */+export function scopeHeadersToDestination(+ headers: Record<string, string> | undefined,+ baseUrl: string,+): Record<string, string> | undefined {+ if (headers == null) {+ return undefined;+ }+ if (allowsLangfuseCustomHeaders(baseUrl)) {+ return headers;+ }+ if (hasAmbiguousLangfuseOrigins() && !warnedAmbiguousOrigins) {+ warnedAmbiguousOrigins = true;+ logger.warn(+ '[langfuse] Not sending langfuse.headers: this deployment configures more than one Langfuse origin, and the headers do not say which one they authenticate to.',+ );+ }+ return undefined;+}+export function getLangfuseDestinationId(baseUrl: string, projectId: string): string {return createHash('sha256').update(`${baseUrl.replace(/\/+$/, '')}\n${projectId}`)@@ -60,14 +97,18 @@ async function resolveCentralProjectId(publicKey: string,secretKey: string,waitForLookup: boolean,+ headers?: Record<string, string>,): Promise<string | undefined> {const configuredProjectId = normalizeString(process.env.LANGFUSE_PROJECT_ID);if (configuredProjectId) {return configuredProjectId;}+ /** Headers participate in the key so the header-less module warm-up below+ * cannot record a proxy rejection against the entry the request path+ * (which does send them) later reads. */const cacheKey = createHash('sha256')- .update(`${baseUrl}\n${publicKey}\n${secretKey}`)+ .update(`${baseUrl}\n${publicKey}\n${secretKey}\n${JSON.stringify(headers ?? null)}`).digest('hex');const cached = centralProjectIdCache.get(cacheKey) ?? { retryAt: 0 };centralProjectIdCache.set(cacheKey, cached);@@ -79,8 +120,11 @@ async function resolveCentralProjectId(cached.lookup = (async () => {try {const response = await fetch(`${baseUrl}/api/public/projects`, {- headers: { Authorization: toBasicAuthorization(publicKey, secretKey) },+ headers: mergeHeaders(headers, {+ Authorization: toBasicAuthorization(publicKey, secretKey),+ }),signal: AbortSignal.timeout(PROJECT_LOOKUP_TIMEOUT_MS),+ ...redirectPolicyFor(headers),});if (!response.ok) {logger.warn(@@ -125,6 +169,7 @@ async function resolveCentralProjectId(async function getCentralScoreDestination(waitForProjectId: boolean,+ headers?: Record<string, string>,): Promise<LangfuseScoreDestination | undefined> {// Central feedback scores are sent directly by the app, not through the// collector, so they use LibreChat's normal central Langfuse credentials.@@ -136,16 +181,27 @@ async function getCentralScoreDestination(}const baseUrl = getCentralEnvBaseUrl();- const projectId = await resolveCentralProjectId(baseUrl, publicKey, secretKey, waitForProjectId);+ const scopedHeaders = scopeHeadersToDestination(headers, baseUrl);+ const projectId = await resolveCentralProjectId(+ baseUrl,+ publicKey,+ secretKey,+ waitForProjectId,+ scopedHeaders,+ );return {id: projectId ? getLangfuseDestinationId(baseUrl, projectId) : undefined,name: 'central',baseUrl,authorization: toBasicAuthorization(publicKey, secretKey),+ ...(scopedHeaders ? { headers: scopedHeaders } : {}),};}-function getTenantScoreDestination(appConfig?: AppConfig): LangfuseScoreDestination | undefined {+function getTenantScoreDestination(+ appConfig?: AppConfig,+ headers?: Record<string, string>,+): LangfuseScoreDestination | undefined {if (!isLangfuseTenantExportEnabled()) {return undefined;}@@ -171,6 +227,7 @@ function getTenantScoreDestination(appConfig?: AppConfig): LangfuseScoreDestinatreturn undefined;}+ const scopedHeaders = scopeHeadersToDestination(headers, destination.baseUrl);return {id: config?.projectId? getLangfuseDestinationId(destination.baseUrl, config.projectId)@@ -178,11 +235,13 @@ function getTenantScoreDestination(appConfig?: AppConfig): LangfuseScoreDestinatname: 'tenant',baseUrl: destination.baseUrl,authorization: toBasicAuthorization(tenantCredentials.publicKey, tenantCredentials.secretKey),+ ...(scopedHeaders ? { headers: scopedHeaders } : {}),};}function getConfiguredScoreDestination(appConfig?: AppConfig,+ headers?: Record<string, string>,): LangfuseScoreDestination | undefined {const config = appConfig?.langfuse;if (normalizeBoolean(config?.enabled) !== true) {@@ -195,6 +254,7 @@ function getConfiguredScoreDestination(return undefined;}+ const scopedHeaders = scopeHeadersToDestination(headers, destination.baseUrl);return {id: config?.projectId? getLangfuseDestinationId(destination.baseUrl, config.projectId)@@ -202,6 +262,7 @@ function getConfiguredScoreDestination(name: 'connection',baseUrl: destination.baseUrl,authorization: toBasicAuthorization(credentials.publicKey, credentials.secretKey),+ ...(scopedHeaders ? { headers: scopedHeaders } : {}),};}@@ -227,6 +288,8 @@ export async function getScoreDestinations(return [];}+ const headers = resolveLangfuseHeaders(appConfig?.langfuse?.headers);+if (!usesLangfuseMultiTenantRouting()) {/** Mirrors `resolveLangfuseExportPlan`: without fanout there is no tenant* route to fall back on, so suppressing central export disables the trace@@ -236,19 +299,19 @@ export async function getScoreDestinations(return [];}return hasLangfuseEnvCredentials()- ? [await getCentralScoreDestination(waitForCentralProjectId)].filter(+ ? [await getCentralScoreDestination(waitForCentralProjectId, headers)].filter((destination): destination is LangfuseScoreDestination => Boolean(destination),)- : [getConfiguredScoreDestination(appConfig)].filter(+ : [getConfiguredScoreDestination(appConfig, headers)].filter((destination): destination is LangfuseScoreDestination => Boolean(destination),);}const destinations = [centralTraceExportEnabled- ? await getCentralScoreDestination(waitForCentralProjectId)+ ? await getCentralScoreDestination(waitForCentralProjectId, headers): undefined,- getTenantScoreDestination(appConfig),+ getTenantScoreDestination(appConfig, headers),].filter((destination): destination is LangfuseScoreDestination => Boolean(destination));const unique = new Map<string, LangfuseScoreDestination>();for (const destination of destinations) {diff --git a/packages/api/src/langfuse/feedback.spec.ts b/packages/api/src/langfuse/feedback.spec.tsindex 9c4be391b1..b4efa3a085 100644--- a/packages/api/src/langfuse/feedback.spec.ts+++ b/packages/api/src/langfuse/feedback.spec.ts@@ -1284,4 +1284,155 @@ describe('Langfuse feedback scores', () => {}),);});++ it('sends configured headers with score creation', async () => {+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({+ headers: { 'CF-Access-Client-Id': 'proxy-client' },+ }),+ });++ expect(getFetchMock()).toHaveBeenCalledWith(+ 'https://langfuse.internal/api/public/scores',+ expect.objectContaining({+ method: 'POST',+ headers: expect.objectContaining({+ 'CF-Access-Client-Id': 'proxy-client',+ Authorization: getCentralAuthorization(),+ 'Content-Type': 'application/json',+ }),+ }),+ );+ });++ it('refuses redirects on requests carrying custom headers', async () => {+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({+ headers: { 'X-Proxy-Token': 'proxy-token' },+ }),+ });++ /** Node drops `Authorization` across a cross-origin redirect but keeps+ * arbitrary headers, so following one would hand the gateway credential+ * to a host that passed no origin check. */+ const [, init] = getFetchMock().mock.calls[0] as [string, RequestInit];+ expect(init.redirect).toBe('error');+ });++ it('keeps default redirect handling when no custom headers are configured', async () => {+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({}),+ });++ const [, init] = getFetchMock().mock.calls[0] as [string, RequestInit];+ expect(init.redirect).toBeUndefined();+ });++ it('withholds configured headers from an unconfigured origin', async () => {+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({+ headers: { 'CF-Access-Client-Id': 'internal-gateway-token' },+ }),+ });++ /** Default central export is Langfuse Cloud, which the operator never+ * pointed at — a gateway credential must not be disclosed to it. */+ const [url, init] = getFetchMock().mock.calls[0] as [string, RequestInit];+ expect(url).toBe('https://cloud.langfuse.com/api/public/scores');+ expect(JSON.stringify(init.headers)).not.toContain('internal-gateway-token');+ });++ it('sends configured headers with score deletion', async () => {+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: null,+ appConfig: appConfigWithLangfuse({+ headers: { 'CF-Access-Client-Id': 'proxy-client' },+ }),+ });++ expect(getFetchMock()).toHaveBeenCalledWith(+ expect.stringContaining('/api/public/scores/'),+ expect.objectContaining({+ method: 'DELETE',+ headers: expect.objectContaining({+ 'CF-Access-Client-Id': 'proxy-client',+ Authorization: getCentralAuthorization(),+ }),+ }),+ );+ });++ it.each(['Authorization', 'authorization', 'AUTHORIZATION'])(+ 'never lets a configured %s header displace the Langfuse authorization',+ async (headerName) => {+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({+ headers: { [headerName]: 'Bearer proxy-token' },+ }),+ });++ const [, init] = getFetchMock().mock.calls[0] as [string, RequestInit];+ const headers = init.headers as Record<string, string>;+ /** A surviving case variant would be *appended* by fetch, sending a+ * combined "Bearer proxy-token, Basic ..." value rather than ours. */+ expect(+ Object.keys(headers).filter((key) => key.toLowerCase() === 'authorization'),+ ).toHaveLength(1);+ expect(Object.values(headers)).toContain(getCentralAuthorization());+ expect(Object.values(headers)).not.toContain('Bearer proxy-token');+ },+ );++ it('sends configured headers with the central project identity lookup', async () => {+ delete process.env.LANGFUSE_PROJECT_ID;+ process.env.LANGFUSE_BASE_URL = 'https://langfuse.internal';+ fetchMock.mockResolvedValue(+ new Response(JSON.stringify({ data: [{ id: 'discovered-project' }] }), { status: 200 }),+ );+ const { sendFeedbackScore } = await loadFeedback();++ await sendFeedbackScore({+ traceId: '86d413435f8b0d7f32d4d010ce769e2e',+ feedback: { rating: 'thumbsUp' },+ appConfig: appConfigWithLangfuse({+ headers: { 'CF-Access-Client-Id': 'proxy-client' },+ }),+ });++ expect(getFetchMock()).toHaveBeenCalledWith(+ 'https://langfuse.internal/api/public/projects',+ expect.objectContaining({+ headers: expect.objectContaining({+ 'CF-Access-Client-Id': 'proxy-client',+ Authorization: getCentralAuthorization(),+ }),+ }),+ );+ });});diff --git a/packages/api/src/langfuse/feedback.ts b/packages/api/src/langfuse/feedback.tsindex ca34ac0750..77a8d4db6d 100644--- a/packages/api/src/langfuse/feedback.ts+++ b/packages/api/src/langfuse/feedback.ts@@ -1,6 +1,8 @@import { logger } from '@librechat/data-schemas';import type { AppConfig } from '@librechat/data-schemas';import { getScoreDestinations, type LangfuseScoreDestination } from './destinations';+import { mergeHeaders } from '~/utils/headers';+import { redirectPolicyFor } from './utils';export type LangfuseFeedback = {rating?: 'thumbsUp' | 'thumbsDown';@@ -61,7 +63,8 @@ async function deleteScore(destination: LangfuseScoreDestination, scoreId: strin`${destination.baseUrl}/api/public/scores/${encodeURIComponent(scoreId)}`,{method: 'DELETE',- headers: { Authorization: destination.authorization },+ headers: mergeHeaders(destination.headers, { Authorization: destination.authorization }),+ ...redirectPolicyFor(destination.headers),},);if (!res.ok && res.status !== 404) {@@ -75,8 +78,12 @@ async function createScore(): Promise<void> {const res = await fetch(`${destination.baseUrl}/api/public/scores`, {method: 'POST',- headers: { Authorization: destination.authorization, 'Content-Type': 'application/json' },+ headers: mergeHeaders(destination.headers, {+ Authorization: destination.authorization,+ 'Content-Type': 'application/json',+ }),body: JSON.stringify(payload),+ ...redirectPolicyFor(destination.headers),});if (!res.ok) {throw new Error(`score create ${res.status}: ${await res.text()}`);diff --git a/packages/api/src/langfuse/tenantDestinations.ts b/packages/api/src/langfuse/tenantDestinations.tsindex 6ba3272235..c475efcb9e 100644--- a/packages/api/src/langfuse/tenantDestinations.ts+++ b/packages/api/src/langfuse/tenantDestinations.ts@@ -91,6 +91,79 @@ export function getLangfuseTenantDestinations(): LangfuseTenantDestination[] {return uniqueDestinations(defaults);}+function originOf(value: string): string | undefined {+ try {+ return new URL(value).origin;+ } catch {+ return undefined;+ }+}++/**+ * Origins the deployment explicitly pointed Langfuse traffic at — a self-hosted+ * base URL, the fanout collector, or a tenant destination whose URL was set by+ * env. The built-in `*.cloud.langfuse.com` defaults are deliberately excluded:+ * they are third-party origins nobody configured.+ */+function getConfiguredLangfuseOrigins(): Set<string> {+ const origins = new Set<string>();+ const add = (value: unknown): void => {+ const baseUrl = normalizeBaseUrl(value);+ const origin = baseUrl ? originOf(baseUrl) : undefined;+ if (origin) {+ origins.add(origin);+ }+ };++ add(process.env.LANGFUSE_BASE_URL);+ add(process.env.LANGFUSE_HOST);+ add(process.env.LANGFUSE_BASEURL);+ add(process.env.LANGFUSE_FANOUT_COLLECTOR_URL);++ const configuredList = normalizeString(process.env[DESTINATIONS_ENV]);+ if (configuredList) {+ for (const destination of parseDestinationList(configuredList)) {+ add(destination.baseUrl);+ }+ return origins;+ }++ for (const [key] of DEFAULT_TENANT_DESTINATIONS) {+ add(process.env[destinationEnvName(key)]);+ }+ return origins;+}++/**+ * Whether custom Langfuse headers may be sent to `baseUrl`.+ *+ * `langfuse.headers` is a single map with no way to say *which* endpoint it+ * authenticates to, so it is only unambiguous when the deployment configured+ * exactly one Langfuse origin. With several — a collector plus a self-hosted+ * central, say — any rule for picking recipients is a guess, and guessing wrong+ * discloses a gateway credential to the other origin. So the headers are sent+ * only when there is one configured origin and this is it.+ *+ * That covers the self-hosted-behind-a-proxy case this feature exists for.+ * Multi-destination deployments need per-destination header configuration,+ * which the schema does not yet express.+ */+export function allowsLangfuseCustomHeaders(baseUrl: string): boolean {+ const configured = getConfiguredLangfuseOrigins();+ if (configured.size !== 1) {+ return false;+ }+ const origin = originOf(baseUrl);+ return origin != null && configured.has(origin);+}++/** True when headers were configured but the deployment has several possible+ * Langfuse origins, so none can be given the map. Callers use this to explain+ * the silence rather than leaving an operator debugging a missing header. */+export function hasAmbiguousLangfuseOrigins(): boolean {+ return getConfiguredLangfuseOrigins().size > 1;+}+export function resolveLangfuseTenantDestination(destinationKey: unknown,): LangfuseTenantDestination | undefined {diff --git a/packages/api/src/langfuse/utils.ts b/packages/api/src/langfuse/utils.tsindex aefc093e38..1766fe7b5a 100644--- a/packages/api/src/langfuse/utils.ts+++ b/packages/api/src/langfuse/utils.ts@@ -1,13 +1,231 @@+import { logger } from '@librechat/data-schemas';+import { isSensitiveEnvVar } from 'librechat-data-provider';import type { AppConfig } from '@librechat/data-schemas';+import { encodeHeaderValue, stripUnresolvedPlaceholders } from '~/utils/env';import { decryptConfigSecret } from '~/admin/secrets';import { normalizeString } from '~/utils/text';type LangfuseAppConfig = NonNullable<AppConfig['langfuse']>;+/** RFC 7230 token characters — the only bytes legal in an HTTP field name. */+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;+/** Legal field-value bytes: visible ASCII, space/tab, and obs-text. A newline,+ * carriage return, or NUL is both rejected by `Headers` and a request-splitting+ * vector, so such a value is dropped rather than sanitized. */++const HEADER_VALUE_PATTERN = /^[\t\x20-\x7e\x80-\xff]*$/;++/**+ * Names that break the request rather than travel with it. `fetch` throws on+ * `Transfer-Encoding`, and a fixed `Content-Length` misdescribes the body as+ * soon as this shared map is reused on a request with a different one. Since+ * the map is attached to export, verification, lookup, and feedback alike, one+ * such entry disables the whole integration instead of being ignored.+ */+const FORBIDDEN_HEADER_NAMES = new Set([+ 'connection',+ 'content-length',+ 'expect',+ 'host',+ 'keep-alive',+ 'te',+ 'trailer',+ 'transfer-encoding',+ 'upgrade',+]);++/** Header names already reported, so a per-run resolution cannot spam the log.+ * Bounded by the deployment's configured header names. */+const droppedHeaderWarnings = new Set<string>();++function warnDroppedHeader(name: string, reason: string): void {+ const key = `${name}\n${reason}`;+ if (droppedHeaderWarnings.has(key)) {+ return;+ }+ droppedHeaderWarnings.add(key);+ logger.warn(`[langfuse] Dropping header "${name}": ${reason}`);+}++/**+ * Names of `${VAR}` references in a *configured* value that will not expand —+ * either unset, or on the infrastructure denylist `extractEnvVariable` refuses+ * to substitute.+ *+ * Deliberately inspects the pre-expansion text. Testing the resolved string for+ * `${...}` cannot tell a failed substitution from a credential that merely+ * contains those characters, and gateway tokens are arbitrary strings — a+ * working `abc${def}ghi` token would be silently dropped.+ */+function unresolvableEnvRefs(configuredValue: string): string[] {+ const unresolved: string[] = [];+ for (const match of configuredValue.matchAll(/\$\{([^}]+)\}/g)) {+ const name = match[1].trim();+ if (isSensitiveEnvVar(name) || !normalizeString(process.env[name])) {+ unresolved.push(name);+ }+ }+ return unresolved;+}++/**+ * Substitutes every `${VAR}` reference, which callers must have already checked+ * with `unresolvableEnvRefs`.+ *+ * Done here rather than left to `extractEnvVariable` because its whole-string+ * branch is anchored (`^\${(.+)}$`) and greedy, so a value composed of two+ * references — `${CLIENT_ID}:${CLIENT_SECRET}` — parses as one variable named+ * `CLIENT_ID}:${CLIENT_SECRET`, resolves to nothing, and the raw template is+ * sent as the credential.+ */+function expandEnvRefs(configuredValue: string): string {+ return configuredValue.replace(+ /\$\{([^}]+)\}/g,+ (fullMatch, rawName: string) => process.env[rawName.trim()] ?? fullMatch,+ );+}++/** Names already reported as duplicate spellings, keyed by lowercase name. */+const duplicateHeaderWarnings = new Set<string>();++/**+ * Collapses case-variant spellings of the same header name, keeping the last.+ *+ * HTTP header names are case-insensitive, but a config map can legally hold+ * `authorization` and `AUTHORIZATION` as distinct keys. Downstream merging+ * indexes one spelling per name and so can only displace one of them; the+ * survivor would then be *appended* by `Headers` into a combined value,+ * breaking the very credential it was meant to set.+ */+function collapseHeaderNameVariants(headers: Record<string, string>): Record<string, string> {+ const byLowerName = new Map<string, string>();+ for (const name of Object.keys(headers)) {+ const lower = name.toLowerCase();+ const existing = byLowerName.get(lower);+ if (existing != null && !duplicateHeaderWarnings.has(lower)) {+ duplicateHeaderWarnings.add(lower);+ logger.warn(+ `[langfuse] Header "${name}" duplicates "${existing}" (names are case-insensitive); using "${name}".`,+ );+ }+ byLowerName.set(lower, name);+ }++ if (byLowerName.size === Object.keys(headers).length) {+ return headers;+ }+ return Object.fromEntries([...byLowerName.values()].map((name) => [name, headers[name]]));+}+export function toBasicAuthorization(publicKey: string, secretKey: string): string {return `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString('base64')}`;}+/**+ * Refuses redirects on requests carrying custom headers.+ *+ * Node strips `Authorization` when a redirect crosses origins but keeps+ * arbitrary headers, so following one would hand the gateway credential to a+ * host that passed no origin check. Requests without custom headers keep the+ * default follow behavior, so this changes nothing for existing deployments.+ */+export function redirectPolicyFor(headers?: Record<string, string>): {+ redirect?: RequestRedirect;+} {+ return headers != null && Object.keys(headers).length > 0 ? { redirect: 'error' } : {};+}++/**+ * Resolves the deployment's custom Langfuse headers: `${ENV_VAR}` interpolation+ * and header-safe encoding, matching what endpoint headers get.+ *+ * No user or request body is involved — one exporter serves every user's spans,+ * so per-user placeholders have no meaning here and are stripped rather than+ * forwarded as template syntax. Anything that cannot be sent safely (unset+ * reference, illegal name, framing header, unencodable value) is dropped with a+ * warning rather than sent malformed: a proxy rejecting a broken credential is+ * far harder to diagnose than a missing one.+ *+ * @returns the resolved headers, or `undefined` when none survive.+ */+export function resolveLangfuseHeaders(+ headers?: Record<string, string | undefined>,+): Record<string, string> | undefined {+ if (headers == null) {+ return undefined;+ }++ /** `TCustomConfig` is a `DeepPartial`, so record values arrive as+ * `string | undefined` regardless of what the schema declares. */+ const declared: Record<string, string> = {};+ for (const [rawName, value] of Object.entries(headers)) {+ if (typeof value !== 'string') {+ continue;+ }+ const name = rawName.trim();+ if (name === '') {+ continue;+ }+ /** An illegal field name (` X-Token`, `X Proxy Token`) is rejected by the+ * `Headers` constructor, which would throw on every export, verification,+ * lookup, and feedback request instead of failing this one header. */+ if (!HEADER_NAME_PATTERN.test(name)) {+ warnDroppedHeader(rawName, 'it is not a valid HTTP header name.');+ continue;+ }+ if (FORBIDDEN_HEADER_NAMES.has(name.toLowerCase())) {+ warnDroppedHeader(name, 'it controls request framing and cannot be set on a fetch request.');+ continue;+ }+ declared[name] = value;+ }+ if (Object.keys(declared).length === 0) {+ return undefined;+ }++ const collapsed = collapseHeaderNameVariants(declared);+ const entries: Array<[string, string]> = [];+ for (const [name, configured] of Object.entries(collapsed)) {+ /**+ * Every template operation runs on the operator's configured text, and the+ * credential is substituted last and never touched again.+ *+ * Order matters in both directions: expanding first would let a strip or a+ * second expansion reinterpret characters that came out of the secret, so a+ * token containing `{{LIBRECHAT_USER_ID}}` would have that span deleted and+ * one containing `${PATH}` would be rewritten. Gateway credentials are+ * arbitrary strings; none of their bytes are template syntax.+ */+ const template = stripUnresolvedPlaceholders(configured);+ const unresolved = unresolvableEnvRefs(template);+ if (unresolved.length > 0) {+ warnDroppedHeader(name, `${unresolved.join(', ')} is not set in the environment.`);+ continue;+ }+ const value = expandEnvRefs(template);++ /** Trimmed because a credential read from a file or `$(...)` commonly+ * carries a trailing newline, which would otherwise fail validation. */+ const trimmed = value.trim();+ if (trimmed === '') {+ continue;+ }+ /** Nothing else encodes these values, so a literal or interpolated+ * character above U+00FF would reach `Headers` unencoded and throw,+ * taking down export, verification, and feedback alike. */+ const encoded = encodeHeaderValue(trimmed);+ /** `encodeHeaderValue` only encodes above U+00FF, so control bytes below it+ * still reach `Headers` and throw — an embedded CR/LF would also be a+ * request-splitting attempt, so this drops rather than strips. */+ if (!HEADER_VALUE_PATTERN.test(encoded)) {+ warnDroppedHeader(name, 'its value contains characters not allowed in an HTTP header.');+ continue;+ }+ entries.push([name, encoded]);+ }+ return entries.length > 0 ? Object.fromEntries(entries) : undefined;+}+export function resolveTenantCredentials(config?: LangfuseAppConfig,): { publicKey: string; secretKey: string } | undefined {diff --git a/packages/api/src/utils/env.ts b/packages/api/src/utils/env.tsindex 6c18825e72..1c39d0b9dd 100644--- a/packages/api/src/utils/env.ts+++ b/packages/api/src/utils/env.ts@@ -170,7 +170,7 @@ const RESOLVABLE_PLACEHOLDER_PATTERN = new RegExp(* users under that one string). Only for final resolution passes — staged* flows that resolve again later with more context must not strip.*/-function stripUnresolvedPlaceholders(value: string): string {+export function stripUnresolvedPlaceholders(value: string): string {return value.replace(RESOLVABLE_PLACEHOLDER_PATTERN, '');}diff --git a/packages/data-provider/specs/config-schemas.spec.ts b/packages/data-provider/specs/config-schemas.spec.tsindex d81b2ea491..4d3d3161cf 100644--- a/packages/data-provider/specs/config-schemas.spec.ts+++ b/packages/data-provider/specs/config-schemas.spec.ts@@ -1349,4 +1349,30 @@ describe('configSchema langfuse', () => {expect(result.success).toBe(true);});++ it('accepts custom Langfuse request headers', () => {+ const result = configSchema.safeParse({+ version: '1.3.7',+ langfuse: {+ enabled: true,+ headers: {+ 'CF-Access-Client-Id': 'proxy-client',+ 'X-Proxy-Token': '${LANGFUSE_PROXY_TOKEN}',+ },+ },+ });++ expect(result.success).toBe(true);+ });++ it('rejects non-string Langfuse header values', () => {+ const result = configSchema.safeParse({+ version: '1.3.7',+ langfuse: {+ headers: { 'X-Proxy-Token': 42 },+ },+ });++ expect(result.success).toBe(false);+ });});diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 5c2a785e8b..a1bcb6489a 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -2040,6 +2040,27 @@ export const langfuseConfigSchema = z.object({secretKeyPreview: z.string().optional(),/** Routing key for one of the deployment-configured tenant Langfuse destinations. */destination: z.string().optional(),+ /**+ * Custom request headers sent on every outbound Langfuse request — trace and+ * media export, feedback scores, and credential verification — for+ * self-hosted instances behind an authenticating proxy or gateway. Values+ * support `${ENV_VAR}` interpolation.+ *+ * Deployment-level only. Trace export batches spans from every user through+ * one exporter, so unlike endpoint headers these cannot carry per-user+ * placeholders. Headers referencing an unset variable, naming an+ * infrastructure secret, or carrying an invalid HTTP field name are dropped+ * with a warning rather than sent.+ *+ * Sent only when the deployment configures exactly one Langfuse origin, and+ * only to that origin. The map cannot say which endpoint it authenticates+ * to, so with several configured origins any choice of recipient would risk+ * disclosing a gateway credential to the others; a warning is logged instead.+ * Multi-destination deployments need per-destination headers, which this+ * schema does not yet express — and note the fanout collector forwards only+ * `Authorization` upstream regardless.+ */+ headers: z.record(z.string()).optional(),});export type LangfuseConfig = z.infer<typeof langfuseConfigSchema>;