mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-17 13:33:45 +00:00
* 🔐 feat: Admin Config Secrets v2 (MCP and Azure Credentials, Re-entry, Env Allowlist, Rebinding) The admin config API stored MCP server credentials and Azure group keys in plaintext, returned them to config readers, let an admin who cannot read a stored credential send it to a host of their choosing, and let override values reference any environment variable. MCP credentials and Azure keys, in `groups` and in the `groupMap` the Azure clients read, are now encrypted with masked previews, hidden from every read and decrypted once after the merge. A write that keeps a stored MCP credential or web search key while changing where it is sent must enter it again, judged by the value the written document holds. `${VAR}` references in overrides are limited to an allowlist, named where a change batch leaves them, and the merge drops a credential a layer moves to a new destination without entering it, listing it in write responses only for sections the caller can read. A custom endpoint's key is bound to its base URL, its provider and the destination options in addParams and dropParams (such as the anthropicApiUrl the native Anthropic client sends to), matched across layers under the name the merge folds (ollama is Ollama). A restated `${VAR}` counts as entered, so allowlisted names are not bound to a destination. Azure's `${INSTANCE_NAME}` and `${DEPLOYMENT_NAME}` stay templates in a group's `baseURL`, and a scheduled job's MCP consent no longer depends on the masked previews that change when an admin rotates the key in place. * ♻️ refactor: Move the MCP Key Re-entry Guard Out of the Binding Helpers to Break an Import Cycle With #17351's OpenID provisioning on dev, the app config service reached itself through the rebinding guard: app/service -> app/overrides -> app/rebinding -> mcp/registry/binding -> mcp/errors (and mcp/types) -> mcp/oauth/obo -> utils/identity -> auth/openid -> auth/provision -> app/resolve -> app/service. The binding helpers are pure diffs; only requireApiKeyReentryForRebinding needs the MCP error class, so it moves to mcp/registry/reentry.ts, and the helpers take MCPOptions from librechat-data-provider as mcp/headers.ts does. No behaviour changes. * 🧪 test: Drop a Base-Held Endpoint Key That a Lower-Priority Profile Moves Base merges first since #17352, so a profile below Base's priority still lands over it. The rebinding guard drops the key Base stores for a custom endpoint whose baseURL the profile changes, and the PATCH response lists it in `ignored`. * 🔐 fix: Serve Admin Azure Group Keys and Keep Deployment Keys at Their Own Destinations Azure groups a profile writes now take effect: the merge resolves a layer's `endpoints.azureOpenAI.groups` as AppService resolves librechat.yaml's (`resolveAzureGroups`, shared with `azureConfigSetup`) into the `groupMap`, `modelGroupMap`, model list and assistant models the Azure clients read. A layer's groups replace the groups below whole, as its array does; groups that do not resolve stay unread with a warning. The rebinding guard judges the resolved groups like any `groupMap` entry, and an Azure group's destination now also covers a deployment name its base URL takes its host from and the destination options of its `addParams`/`dropParams`. A write that keeps a stored Azure group key (in `groups` or `groupMap`) while changing where the group sends it answers 400 `CONFIG_SECRET_REENTRY_REQUIRED` on PUT, PATCH, field deletes, tombstones and change batches, judged as the document resolves over librechat.yaml and on each `groups` item as written. OCR fills an empty key from `OCR_API_KEY` only for its default destination (no base URL, or `${OCR_BASEURL}`), so a key the guard dropped for an override's `${VAR}` base URL is not replaced by the deployment's. The env reference policy includes the `${OCR_API_KEY}` loading fills in for an `ocr` section without a key, so a client can write back what GET `/base` returned. The custom endpoint guard no longer needs the layer's overrides to name an entry: an entry changed some other way is judged as inherited (positional tombstones inside the list are not applied by the merge, so none reached one). A web search URL a layer points at a `${VAR}` other than librechat.yaml's without entering its key is set back: web search sends the deployment's key, or its client's environment default, to any `${VAR}` URL. * 🔐 fix: Keep Azure Assistants Served, Opaque Keys as Entered and Batch Env Checks on the End State Azure assistants: a profile's `groups` replace the groups below whole, so groups with no model that supports assistants under librechat.yaml's `assistants: true` left `assistants` on with an empty `assistantModels`, and the Azure Assistants initializer picked `assistantModels[0]` (undefined). `azureConfigSetup` refuses that combination at startup; the merge now turns `assistants` off when none of the models it leaves supports them, with a warning, judged on the merged result so a later layer whose groups serve assistants keeps them on. The check is `lacksAzureAssistantModels`, shared with `azureConfigSetup`. Opaque credentials: every runtime reader of the OCR, speech, web search and Langfuse keys uses the decrypted value as is (`resolveConfigSecret`, `resolveStoredConfigSecret`, `decryptConfigSecret`), so a `${...}` inside a key the write encrypts is part of the key. Those fields are marked `opaque`: the write-time check skips a value the write encrypts there, and the runtime pass keeps their ciphertext instead of blanking it. A whole `${VAR}` reference there, which the field passes through and its reader resolves, is still checked, and so is stored plaintext. Custom endpoint (`initializeCustom`), Azure group (`mapModelToAzureConfig`) and MCP (`processMCPEnv`) credentials are expanded by their clients once decrypted and stay checked; the Assistants keys have no reader yet and stay checked too. Change batches: env references are judged on the document the batch leaves, as its other issues are. An issue counts only when the end state still holds a disallowed reference (ciphertext by its plaintext) where the batch sent one, at a location the batch changed, so a value a later op removes or replaces (`set ocr.baseURL`, then `unset ocr`) is no longer refused, and a stored reference the batch puts back where it was is left to merge time. * 🔐 fix: Proxy-Bound OAuth Secrets, Consistent Azure Group State, Batch Issues by Entry Key and Loaded Web Search References - The MCP proxy is part of the OAuth client secret's binding (user tier, admin re-entry and the merge's rebinding guard share `getChangedOAuthSecretBindingFields`): the access token the secret obtains travels through it. - A tombstone of `endpoints.azureOpenAI.groups` resolves the groups to none in the merge (empty `groupMap`, `modelGroupMap` and model lists, so the model list does not fall back to the environment's defaults), and removes what they resolve to in `applyConfigTombstones`. - The merged Azure model lists name only models a merged group serves (`narrowAzureServedModels`), so an override's `assistantModels` no group serves no longer keeps Azure assistants on. - `/changes` env issues are held by entry identity (`toConfigIdentityPath`), followed through renames and resolved on the batch's end state, so a removal or rename no longer shifts them. - References loading librechat.yaml introduces (OCR's `${OCR_API_KEY}`, the web search defaults) are allowed at the location they are loaded at, so GET /base's sections are accepted written back, and nowhere else. * 🔐 fix: Re-entry for Endpoint, OCR and Speech Keys, Own Keys Bound Over Base and User Key Destinations Kept - The document that stores a custom endpoint, OCR or speech key can no longer move its destination without the key: PUT, PATCH, field deletes, tombstones and change batches answer CONFIG_SECRET_REENTRY_REQUIRED at the changed field (getBoundKeyReentryIssues), judged by value as the document alone sends it. - A profile's own key for an endpoint, MCP server, OCR or speech service, or Azure groupMap group that Base defines is bound to that destination when it is entered: the rebinding guard reports a fingerprint of where it goes, the write stores it beside the key (<secret>Binding), and the guard keeps the key there until a lower layer moves it. Reads and the merged config leave the fingerprint out; kept keys carry it; client values are replaced. - An inherited custom endpoint or MCP server that sends a credential each user holds (user_provided, customUserVars, apiKey.source user, OpenID or Graph token placeholders) keeps its destination: a layer's move is set back and listed in ignored.
605 lines
22 KiB
TypeScript
605 lines
22 KiB
TypeScript
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;
|
|
}
|