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
import { logger } from '@librechat/data-schemas';
import { extractEnvVariable } from 'librechat-data-provider';
import type { MCPOptions } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { RequestBody } from '~/types';
import {
OPENID_TOKEN_FIELDS,
OPENID_CREDENTIAL_PLACEHOLDER_PATTERN,
isOpenIDTokenValid,
extractOpenIDTokenInfo,
processOpenIDPlaceholders,
OpenIDReauthRequiredError,
} from './oidc';
import { getAdminApiKeyHeader } from '~/mcp/headers';
/**
* Provenance marker for MCP servers contributed by an Agent Plugins package.
* Applied by the plugin loader, never by a plugin-authored `mcp.json` — that
* schema is closed, so a package declaring this field is rejected outright.
*/
export const MCP_PLUGIN_SOURCE = 'plugin';
/**
* True when a server configuration came from an Agent Plugins package, and so
* must reach the transport with every placeholder it declared left literal.
*/
export function isPluginSourced(config?: { source?: string } | null): boolean {
return config?.source === MCP_PLUGIN_SOURCE;
}
/**
* List of allowed user fields that can be used in MCP environment variables.
* These are non-sensitive string/boolean fields from the IUser interface.
*/
const ALLOWED_USER_FIELDS = [
'id',
'name',
'username',
'email',
'provider',
'role',
'googleId',
'facebookId',
'openidId',
'samlId',
'ldapId',
'githubId',
'discordId',
'appleId',
'emailVerified',
'twoFactorEnabled',
'termsAccepted',
'termsAcceptedAt',
] as const;
type AllowedUserField = (typeof ALLOWED_USER_FIELDS)[number];
type SafeUser = Pick<IUser, AllowedUserField>;
/**
* Encodes a string value to be safe for HTTP headers.
* HTTP headers are restricted to ASCII characters (0-255) per the Fetch API standard.
* Non-ASCII characters with Unicode values > 255 are Base64 encoded with 'b64:' prefix.
*
* NOTE: This is a LibreChat-specific encoding scheme to work around Fetch API limitations.
* MCP servers receiving headers with the 'b64:' prefix should:
* 1. Detect the 'b64:' prefix in header values
* 2. Remove the prefix and Base64-decode the remaining string
* 3. Use the decoded UTF-8 string as the actual value
*
* Example decoding (Node.js):
* if (headerValue.startsWith('b64:')) {
* const decoded = Buffer.from(headerValue.slice(4), 'base64').toString('utf8');
* }
*
* @param value - The string value to encode
* @returns ASCII-safe string (encoded if necessary)
*
* @example
* encodeHeaderValue("José") // Returns "José" (é = 233, safe)
* encodeHeaderValue("Marić") // Returns "b64:TWFyacSH" (ć = 263, needs encoding)
*/
export function encodeHeaderValue(value: string): string {
// Handle non-string or empty values
if (!value || typeof value !== 'string') {
return '';
}
// Check if string contains extended Unicode characters (> 255)
// Characters 0-255 (ASCII + Latin-1) are safe and don't need encoding
// Characters > 255 (e.g., ć=263, đ=272, ł=322) need Base64 encoding
// eslint-disable-next-line no-control-regex
const hasExtendedUnicode = /[^\u0000-\u00FF]/.test(value);
if (!hasExtendedUnicode) {
return value; // Safe to pass through
}
// Encode to Base64 for extended Unicode characters
const base64 = Buffer.from(value, 'utf8').toString('base64');
return `b64:${base64}`;
}
/**
* Creates a safe user object containing only allowed fields.
* Preserves federatedTokens for OpenID token template variable resolution.
*
* @param user - The user object to extract safe fields from
* @returns A new object containing only allowed fields plus federatedTokens if present
*/
export function createSafeUser(
user:
| (Partial<SafeUser> & Pick<IUser, 'tenantId'> & { federatedTokens?: IUser['federatedTokens'] })
| null
| undefined,
): Partial<SafeUser> & { federatedTokens?: IUser['federatedTokens'] } {
if (!user) {
return {};
}
const safeUser: Partial<SafeUser> & { federatedTokens?: IUser['federatedTokens'] } = {};
for (const field of ALLOWED_USER_FIELDS) {
if (field in user) {
/**
* Indexed write through a union-typed key would otherwise fail strict
* checking — TS computes the LHS type as the *intersection* of all
* field write types (which collapses to `undefined` when fields have
* mixed types). `Object.assign` widens the assignment so each field
* preserves its concrete type at runtime.
*/
Object.assign(safeUser, { [field]: user[field] });
}
}
// Fall back to `_id` when the mongoose virtual `id` is absent (e.g. lean/plain
// user objects), so `{{LIBRECHAT_USER_ID}}` placeholders still resolve.
if (!safeUser.id && '_id' in user) {
const _id = (user as unknown as { _id: { toString?: () => string } | string })._id;
safeUser.id = typeof _id === 'string' ? _id : _id?.toString?.();
}
if ('federatedTokens' in user) {
safeUser.federatedTokens = user.federatedTokens;
}
return safeUser;
}
/**
* List of allowed request body fields that can be used in header placeholders.
* These are common fields from the request body that are safe to expose in headers.
*/
export const ALLOWED_BODY_FIELDS = ['conversationId', 'parentMessageId', 'messageId'] as const;
const OPENID_PLACEHOLDER_NAMES = `LIBRECHAT_OPENID_(?:${OPENID_TOKEN_FIELDS.join('|')}|TOKEN)`;
/**
* Matches every placeholder this module knows how to resolve: the enumerated
* `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, and `{{LIBRECHAT_OPENID_*}}`
* names. Deliberately excludes unknown names (a typo'd placeholder staying
* literal is diagnosable) and `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}`, which is
* resolved asynchronously via the OBO flow outside this pipeline.
*/
const RESOLVABLE_PLACEHOLDER_PATTERN = new RegExp(
[
`LIBRECHAT_USER_(?:${ALLOWED_USER_FIELDS.map((field) => field.toUpperCase()).join('|')})`,
`LIBRECHAT_BODY_(?:${ALLOWED_BODY_FIELDS.map((field) => field.toUpperCase()).join('|')})`,
OPENID_PLACEHOLDER_NAMES,
]
.map((names) => `\\{\\{(?:${names})\\}\\}`)
.join('|'),
'g',
);
/**
* The credential placeholders that specifically need a usable *access* token, which is all
* `isOpenIDTokenValid` reports on. `ID_TOKEN` is absent because `processOpenIDPlaceholders`
* validates the ID token's own expiry, so an ID-token header still resolves while no access
* token is stored. Non-global so `exec` stays stateless.
*/
const OPENID_ACCESS_CREDENTIAL_PLACEHOLDER_PATTERN =
/\{\{LIBRECHAT_OPENID_(?:ACCESS_TOKEN|TOKEN)\}\}/;
/**
* Replaces resolvable-but-unresolved placeholders with an empty string so
* LibreChat's internal template syntax is never sent upstream as if it were
* real user data (e.g. a gateway trusting a literal
* `{{LIBRECHAT_USER_OPENIDID}}` as an account identity would pool unrelated
* users under that one string). Only for final resolution passes — staged
* flows that resolve again later with more context must not strip.
*/
export function stripUnresolvedPlaceholders(value: string): string {
return value.replace(RESOLVABLE_PLACEHOLDER_PATTERN, '');
}
/**
* Processes a string value to replace user field placeholders.
* When isHeader is true, non-ASCII characters in certain fields are Base64 encoded.
*
* @param value - The string value to process
* @param user - The user object
* @param isHeader - Whether this value will be used in an HTTP header
* @returns The processed string with placeholders replaced (and encoded if necessary)
*/
function processUserPlaceholders(
value: string,
user?: Partial<IUser>,
isHeader: boolean = false,
): string {
if (!user || typeof value !== 'string') {
return value;
}
for (const field of ALLOWED_USER_FIELDS) {
const placeholder = `{{LIBRECHAT_USER_${field.toUpperCase()}}}`;
if (typeof value !== 'string' || !value.includes(placeholder)) {
continue;
}
const fieldValue = user[field as keyof IUser];
// Skip replacement if field doesn't exist in user object
if (!(field in user)) {
continue;
}
// Special case for 'id' field: skip if undefined or empty
if (field === 'id' && (fieldValue === undefined || fieldValue === '')) {
continue;
}
let replacementValue = fieldValue == null ? '' : String(fieldValue);
// Encode non-ASCII characters when used in headers
// Fields like name, username, email can contain non-ASCII characters
// that would cause ByteString conversion errors in the Fetch API
if (isHeader) {
const fieldsToEncode = ['name', 'username', 'email'];
if (fieldsToEncode.includes(field)) {
replacementValue = encodeHeaderValue(replacementValue);
}
}
value = value.replace(new RegExp(placeholder, 'g'), replacementValue);
}
return value;
}
/**
* Replaces request body field placeholders within a string.
* Recognized placeholders: `{{LIBRECHAT_BODY_<FIELD>}}` where `<FIELD>` ∈ ALLOWED_BODY_FIELDS.
* If a body field is absent or null/undefined, it is replaced with an empty string.
*
* @param value - The string value to process
* @param body - The request body object
* @returns The processed string with placeholders replaced
*/
function processBodyPlaceholders(value: string, body: RequestBody): string {
// Type guard: ensure value is a string
if (typeof value !== 'string') {
return value;
}
for (const field of ALLOWED_BODY_FIELDS) {
const placeholder = `{{LIBRECHAT_BODY_${field.toUpperCase()}}}`;
if (!value.includes(placeholder)) {
continue;
}
const fieldValue = body[field];
const replacementValue = fieldValue == null ? '' : String(fieldValue);
value = value.replace(new RegExp(placeholder, 'g'), replacementValue);
}
return value;
}
/**
* Processes a single string value by replacing various types of placeholders
*
* @param originalValue - The original string value to process
* @param customUserVars - Optional custom user variables to replace placeholders
* @param user - Optional user object for replacing user field placeholders
* @param body - Optional request body object for replacing body field placeholders
* @param isHeader - Whether this value will be used in an HTTP header (enables encoding)
* @returns The processed string with all placeholders replaced
*/
function processSingleValue({
originalValue,
customUserVars,
user,
body = undefined,
isHeader = false,
dbSourced = false,
beforeCredentialResolution,
}: {
originalValue: string;
customUserVars?: Record<string, string>;
user?: Partial<IUser>;
body?: RequestBody;
isHeader?: boolean;
/** When true, only resolve customUserVars — skip env vars, user/OpenID/body placeholders */
dbSourced?: boolean;
beforeCredentialResolution?: (value: string) => string;
}): string {
// Type guard: ensure we're working with a string
if (typeof originalValue !== 'string') {
return String(originalValue);
}
let value = originalValue;
/**
* SECURITY INVARIANT — ordering matters:
* Resolve env vars on the admin-authored template BEFORE any user-controlled
* data is substituted (customUserVars, user fields, OIDC tokens, body placeholders).
* This prevents second-order injection where user values containing ${VAR}
* patterns would otherwise be expanded against process.env.
*/
if (!dbSourced) {
value = extractEnvVariable(value);
}
/** Runs for both dbSourced and non-dbSourced — it is the only resolution DB-stored servers get */
if (customUserVars) {
for (const [varName, varVal] of Object.entries(customUserVars)) {
const escapedVarName = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const placeholderRegex = new RegExp(`\\{\\{${escapedVarName}\\}\\}`, 'g');
value = value.replace(placeholderRegex, varVal);
}
}
if (dbSourced) {
return value;
}
value = processUserPlaceholders(value, user, isHeader);
value = beforeCredentialResolution?.(value) ?? value;
const openidTokenInfo = extractOpenIDTokenInfo(user);
if (openidTokenInfo && isOpenIDTokenValid(openidTokenInfo)) {
value = processOpenIDPlaceholders(value, openidTokenInfo);
} else if (openidTokenInfo) {
const unresolvable = OPENID_ACCESS_CREDENTIAL_PLACEHOLDER_PATTERN.exec(value);
if (unresolvable) {
logger.warn(
`OpenID token is expired or unavailable; cannot resolve ${unresolvable[0]} for the current request`,
);
throw new OpenIDReauthRequiredError(
`OpenID token is expired or unavailable; re-authentication is required to resolve ${unresolvable[0]}`,
);
}
/**
* `isOpenIDTokenValid` reports on the access token alone, so an ID token placeholder is not
* its to refuse: `processOpenIDPlaceholders` validates the ID token's own expiry and raises
* if it is stale. Every other placeholder keeps its literal-then-strip behaviour here.
*/
value = processOpenIDPlaceholders(value, openidTokenInfo, ['ID_TOKEN']);
}
if (body) {
value = processBodyPlaceholders(value, body);
}
return value;
}
function processAdminValue(originalValue: string, dbSourced: boolean): string {
if (typeof originalValue !== 'string') {
return String(originalValue);
}
return dbSourced ? originalValue : extractEnvVariable(originalValue);
}
/**
* Recursively processes an object to replace environment variables in string values
* @param params - Processing parameters
* @param params.options - The MCP options to process
* @param params.user - The user object containing all user fields
* @param params.customUserVars - vars that user set in settings
* @param params.body - the body of the request that is being processed
* @returns - The processed object with environment variables replaced
*/
export function processMCPEnv(params: {
options: Readonly<MCPOptions> & { dbId?: string; source?: string };
user?: Partial<IUser>;
customUserVars?: Record<string, string>;
body?: RequestBody;
/** When true, only resolve customUserVars — skip env vars, user/OpenID/body placeholders (for DB-stored servers) */
dbSourced?: boolean;
/** Trusted projection hook, after substitutions and before credential resolution. */
beforeCredentialResolution?: (value: string) => string;
}): MCPOptions {
const { options, user, body, beforeCredentialResolution } = params;
if (options === null || options === undefined) {
return options;
}
/**
* SECURITY INVARIANT — Agent Plugins configurations are returned verbatim.
* Plugin packages are portable third-party data, and the Agent Plugins
* specification (§7.2.1, §9.2) forbids resolving any placeholder a plugin
* declares. Without this gate a plugin could declare a header such as
* `Authorization: Bearer ${OPENAI_API_KEY}` and receive host credentials at
* its own origin. The check reads the config rather than a caller-supplied
* flag so no future call site can reintroduce the leak by omitting it.
*/
if (isPluginSourced(options)) {
return structuredClone(options) as MCPOptions;
}
/** Derive dbSourced from explicit param OR from dbId on the options (failsafe for callers that forget the flag) */
const dbSourced = params.dbSourced ?? !!options.dbId;
/** A shared-server editor can inject old auth-field names into any template. Only
* server-declared variables may resolve, including destination-bound API key fields. */
const userManaged = dbSourced || !!options.dbId || options.source === 'user';
const customUserVars =
userManaged && params.customUserVars
? Object.fromEntries(
Object.entries(params.customUserVars).filter(([name]) =>
Object.prototype.hasOwnProperty.call(options.customUserVars ?? {}, name),
),
)
: params.customUserVars;
const newObj: MCPOptions = structuredClone(options);
const adminHeader = getAdminApiKeyHeader(newObj.apiKey);
if (adminHeader) {
const objWithHeaders = newObj as { headers?: Record<string, string> };
objWithHeaders.headers = {
...objWithHeaders.headers,
[adminHeader.name]: adminHeader.value,
};
}
if ('env' in newObj && newObj.env) {
const processedEnv: Record<string, string> = {};
for (const [key, originalValue] of Object.entries(newObj.env)) {
processedEnv[key] = processSingleValue({
user,
body,
dbSourced,
beforeCredentialResolution,
originalValue,
customUserVars,
});
}
newObj.env = processedEnv;
}
if ('args' in newObj && newObj.args) {
const processedArgs: string[] = [];
for (const originalValue of newObj.args) {
processedArgs.push(
processSingleValue({
originalValue,
customUserVars,
user,
body,
dbSourced,
beforeCredentialResolution,
}),
);
}
newObj.args = processedArgs;
}
// Process headers if they exist (for WebSocket, SSE, StreamableHTTP types)
// Note: `env` and `headers` are on different branches of the MCPOptions union type.
if ('headers' in newObj && newObj.headers) {
const processedHeaders: Record<string, string> = {};
for (const [key, originalValue] of Object.entries(newObj.headers)) {
processedHeaders[key] = processSingleValue({
user,
body,
dbSourced,
beforeCredentialResolution,
originalValue,
customUserVars,
isHeader: true, // Important: Enable header encoding
});
}
newObj.headers = processedHeaders;
}
// Process OAuth headers if they exist; sent on OAuth discovery/token requests
if ('oauth_headers' in newObj && newObj.oauth_headers) {
const processedOAuthHeaders: Record<string, string> = {};
for (const [key, originalValue] of Object.entries(newObj.oauth_headers)) {
processedOAuthHeaders[key] = processSingleValue({
user,
body,
dbSourced,
beforeCredentialResolution,
originalValue,
customUserVars,
isHeader: true,
});
}
newObj.oauth_headers = processedOAuthHeaders;
}
// Process URL if it exists (for WebSocket, SSE, StreamableHTTP types)
if ('url' in newObj && newObj.url) {
newObj.url = processSingleValue({
user,
body,
dbSourced,
beforeCredentialResolution,
customUserVars,
originalValue: newObj.url,
});
}
// Process outbound proxy if it exists (for SSE and StreamableHTTP types)
if ('proxy' in newObj && newObj.proxy) {
newObj.proxy = processAdminValue(newObj.proxy, dbSourced);
}
// Process OAuth configuration if it exists (for all transport types)
if ('oauth' in newObj && newObj.oauth) {
const processedOAuth: Record<string, boolean | string | string[] | undefined> = {};
for (const [key, originalValue] of Object.entries(newObj.oauth)) {
// Only process string values for environment variables
// token_exchange_method is an enum and shouldn't be processed
if (typeof originalValue === 'string') {
processedOAuth[key] = processSingleValue({
user,
body,
dbSourced,
beforeCredentialResolution,
originalValue,
customUserVars,
});
} else {
processedOAuth[key] = originalValue;
}
}
newObj.oauth = processedOAuth;
}
return newObj;
}
/**
* Resolves header values by replacing user placeholders, body variables, custom variables, and environment variables.
* Automatically encodes non-ASCII characters for header safety.
*
* @param options - Optional configuration object
* @param options.headers - The headers object to process
* @param options.user - Optional user object for replacing user field placeholders (can be partial with just id)
* @param options.body - Optional request body object for replacing body field placeholders
* @param options.customUserVars - Optional custom user variables to replace placeholders
* @param options.stripUnresolved - When true (final resolution passes only), replaces any
* remaining resolvable placeholders with an empty string so internal template syntax is
* never forwarded upstream. Leave unset for staged flows whose values are resolved again
* later with more context.
* @returns The processed headers with all placeholders replaced
*/
export function resolveHeaders(options?: {
headers: Record<string, string> | undefined;
user?: Partial<IUser> | { id: string };
body?: RequestBody;
customUserVars?: Record<string, string>;
stripUnresolved?: boolean;
}): Record<string, string> {
const { headers, user, body, customUserVars, stripUnresolved = false } = options ?? {};
const inputHeaders = headers ?? {};
const resolvedHeaders: Record<string, string> = { ...inputHeaders };
if (inputHeaders && typeof inputHeaders === 'object' && !Array.isArray(inputHeaders)) {
Object.keys(inputHeaders).forEach((key) => {
const processed = processSingleValue({
originalValue: inputHeaders[key],
customUserVars,
user: user as IUser,
body,
isHeader: true, // Important: Enable header encoding
});
if (!stripUnresolved) {
resolvedHeaders[key] = processed;
return;
}
/** Reached only when the credential guard did not fire, i.e. the user has no OpenID identity at all: blanking the credential would emit `Authorization: Bearer `, which RFC 6750 rejects for a missing b64token */
const unresolvedCredential = OPENID_CREDENTIAL_PLACEHOLDER_PATTERN.exec(processed);
if (unresolvedCredential) {
logger.warn(
`Omitting header "${key}": ${unresolvedCredential[0]} could not be resolved for the current request`,
);
delete resolvedHeaders[key];
return;
}
resolvedHeaders[key] = stripUnresolvedPlaceholders(processed);
});
}
return resolvedHeaders;
}