Commit graph

3 commits

Author SHA1 Message Date
Danny Avila
9f617fc4ad
🧬 feat: Re-Derive Azure Groups, Vertex AI, Custom Parameters and Spec Defaults for Config Profiles (#17399)
* 🧬 feat: Re-Derive Azure Groups, Vertex AI, Custom Parameters and Spec Defaults for Config Profiles

AppService derives part of the served config from librechat.yaml at startup, and config
profiles merged into that output without deriving it again. Azure `groups` now merge by `group`
like `endpoints.custom` by `name`: a profile's partial group merges over the group of that
name, groups it does not name stay, indexed writes are refused, change batches take entry ops
on them, and groups that do not resolve over librechat.yaml and Base (or whose written `${VAR}`
is not set) answer `invalid_azure_groups`. Each merged group keeps the key below it unless the
profile supplies one, so the rebinding guard drops a key a partial item moves and a key a lower
layer dropped stays dropped; Azure re-entry compares groups merged the same way.

With `CONFIG_REDERIVE_ENDPOINTS=true` (opt-in for this release), a profile's Azure `groups`
resolve into what the Azure clients read (unconditional before, now behind the switch so stored
group overrides do not go live on upgrade), a profile's `endpoints.anthropic.vertex` derives
`vertexConfig` and the Anthropic models it serves where librechat.yaml configures Vertex AI, and
the Azure Assistants endpoint follows a profile's `assistants`. Startup logs the documents that
hold such overrides, the groups that would not resolve over librechat.yaml and Base, and the
Vertex AI overrides that never apply. Always on: Vertex AI's key file and region are base-only,
a profile may turn Vertex AI on only where librechat.yaml configures it, its settings may
reference only librechat.yaml's own Vertex AI variables (reads return them resolved), a
profile's `vertexConfig` is never applied and writes skip it (`derived_path`,
`rules.derivedPaths`), a model's own `deploymentName` resolves its `${VAR}` like the default one,
the region, project ID and the deployment name each model's requests send (the model name where
the client sends it as written) must stay in their URL host label or path segment, a `${VAR}`
there is a whole `${NAME}` reference only, the Anthropic client refuses any other deployment name
before building a request, and an invalid setup answers `invalid_vertex_config`. The rebinding
guard no longer binds the derived Vertex AI region, which is librechat.yaml's.

Custom endpoint `customParams` are expanded by `expandCustomEndpoint` into the served copy, so
`appConfig.config` stays librechat.yaml as written, and each endpoint a profile writes is
expanded again from its merged form (a changed `defaultParamsEndpoint`, OpenRouter defaults
for a profile's own endpoint); invalid definitions answer `invalid_param_definitions`. After
tenant scoping, `getAppConfig` derives `modelSelect`, `parameters` and `presets` again for the
specs a principal is served where nothing sets them, the agents `memory` capability follows
the merged memory config, and a model spec naming an unconfigured endpoint answers
`unknown_spec_endpoint`. Meta flags: `azureGroupMergeKey`, `customParamsExpansion`,
`specInterfaceRederive` and `endpointRederive`.

* 🪜 fix: Judge Re-Derived Config on What Every Profile Layer Leaves

Two re-derivations decided whether a profile had set a field from whether any layer ever set
it, so a lower profile's value tombstoned by a higher one still counted as set.

- Vertex AI (CONFIG_REDERIVE_ENDPOINTS=true): the marker that keeps a profile's
  `endpoints.anthropic.models` over Vertex AI's is cleared by a later tombstone of those
  models (or of `endpoints.anthropic` or `endpoints`), and such a tombstone derives Vertex AI
  again, so the Anthropic endpoint serves Vertex AI's models instead of none. A tombstone of
  librechat.yaml's own models does the same.
- Spec-dependent controls: `modelSelect`, `parameters` and `presets` are derived again where
  their served value differs from the base config's, not only where the librechat.yaml-shaped
  value does, so a control one profile sets and a higher one tombstones, or a tombstone of one
  librechat.yaml leaves unset, follows the specs served instead of being dropped.

The memory capability, Azure Assistants, Azure groups and custom parameters already derive
from the merged result; tests now cover each set in one layer and tombstoned in a higher one,
and the reverse.

* 🧮 fix: Derive Each Config Part From What the Layers Leave

A tombstone of an object above a derived part's inputs, alone or followed by a layer that
recreates part of that object, left the part without what startup derives it to:

- An Azure endpoint recreated after a tombstone of `endpoints.azureOpenAI` or `endpoints` had
  no groupMap, modelGroupMap or model lists, so its model lists fell back to the environment's
  default Azure models, which requests could not map to a group. It now serves no group, with or
  without CONFIG_REDERIVE_ENDPOINTS (completeAzureResolution).
- A tombstone of the whole `interface` left modelSelect, parameters and presets out, which the
  client reads as off. They are derived from the specs served into a new interface.
- A tombstone of `endpoints.agents` or `endpoints` left no agents endpoint, while a tombstone of
  its capabilities served the defaults. The agents endpoint startup derives is served there.
- A tombstone of a Vertex AI setting that leaves the setup unable to load kept the vertexConfig
  derived below it. Vertex AI is off there, with a warning.

A table in service.spec.ts runs every derived part against every way a layer changes its inputs
(set, unset, a tombstone of the path and of each object above it, a layer recreating after such
a tombstone, Base on either side, tenant scoping, the switch off) through getAppConfig, and
compares each cell with what startup derives from the librechat.yaml the layers leave.

* 🧭 fix: Serve Only Model Specs Whose Endpoint the Layers Leave

A tombstone of `endpoints.custom` or `endpoints` in a higher profile (or the Base profile)
left the model specs of the custom endpoints it removes served, librechat.yaml's or a lower
profile's: the spec list pointed at endpoints /api/endpoints no longer offers, with the model
selector, parameters and presets still off for them. The write check only ran when the write
held `modelSpecs.list`, and the merge served stored specs as they were.

After the last layer, the merge now serves only the specs whose endpoint is a built-in endpoint
or a custom endpoint the YAML-shaped config the layers leave defines, the rule startup skips
librechat.yaml's specs by (deriveServedSpecs). A removed endpoint hides its specs until a layer
defines it again; where no spec is left, none is served (as with a tenant-hidden endpoint) and
the spec-dependent controls come back on. Tombstones of a built-in endpoint's settings keep its
specs, as startup does, and `addedEndpoints` stays as merged. A stored spec for an endpoint that
is not configured is left out on its own instead of being served; writes of one still answer
400 unknown_spec_endpoint.

The derived-part table in service.spec.ts gains the model specs served (with addedEndpoints and
the controls they decide) against tombstones of `endpoints.custom`, `endpoints`, and each of
`endpoints.openAI`, `azureOpenAI` and `anthropic`: by a profile, by Base under a profile, a lower
profile under a higher one, recreated above or by the same layer, with no spec left, and with
the switch off.

* 🧩 fix: Reconcile Re-Derived Config With Dev's Keyed Tombstones, Write Report and Read APIs

- Keyed tombstones of Azure groups (endpoints.azureOpenAI.groups["g"], now merged by key)
  resolve the groups left again where the merge resolves them, and stay inert without
  CONFIG_REDERIVE_ENDPOINTS.
- Keyed tombstones count as touching endpoints.custom, so served specs and custom parameters
  are derived again after one.
- The served-spec derivation keeps modelSpecs while added endpoints remain, as the hidden
  endpoint scoping does; hidden endpoint names leave addedEndpoints.
- Derived paths join the held paths every write skips, built on first use.
- Tests follow the merged behaviour: Azure groups merge by group, the agents endpoint is
  derived again below a tombstone.
2026-10-24 11:46:01 +02:00
Danny Avila
db225c0919
🔐 feat: Admin Config Secrets v2 (MCP and Azure Credentials, Re-entry, Env Allowlist, Rebinding) (#17353)
* 🔐 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.
2026-10-23 06:37:54 +02:00
Danny Avila
9ea3c5647d
🔑 fix: Use Admin-Stored Web Search Credentials at Runtime (#17323)
* 🔑 fix: Use Admin-Stored Web Search Credentials at Runtime

Use admin-stored (encrypted or literal) web search credentials as system
credentials at runtime, add the Keenable key to the secret registry, bind a
stored key to the layer that set its URL, and require re-entering the key when
a write changes or removes that URL (checked atomically with a version
precondition).

* 🧹 fix: Keep Dotted-Key Write Guarantees on Version-Checked Web Search Writes

A version-checked write the caller saw absent first creates an empty
document. When the database then refuses the write (a key name it cannot
store, answered 422 CONFIG_KEY_NOT_STORABLE), remove that document again
so a refused write stores nothing, unless another write has changed it.

Secret re-entry issues now carry `segments` like every other config
issue.

* 🚩 feat: Publish the webSearchStoredKeys Feature Flag in the Config Contract

GET /api/admin/config/meta now reports `webSearchStoredKeys: true`, so an
admin client can stop warning that only ${VAR} web search references work at
runtime. meta.spec probes the behaviour behind it: an encrypted stored key
reaches web search auth, the Keenable key is encrypted on write, and changing
a URL beside a stored key requires entering the key again.

* 🧪 test: Type the Refused-Write Driver Stub in the Config Methods Spec

* 🧪 test: Expect the Write Precondition Arguments in the Admin Config Route Test

The handler passes a session slot and an optional version precondition to
patchConfigFields since the web search re-entry check; the route test added
in #17322 asserted the earlier five-argument call.

* 🧹 fix: Surface a Failed Cleanup of the Empty Config Document

When a version-checked write the database refused cannot remove the empty
document created for it, let that failure reach the handler (500) instead
of logging it and answering 422 CONFIG_KEY_NOT_STORABLE, which promises that
nothing was stored.

* 📝 docs: State the Web Search Stored-Key Binding Rule Exactly in the webSearchStoredKeys Flag

The flag's doc said a stored key goes only to a URL the same layer set. The merge rule keeps a stored key over an inherited ${VAR} or default URL, so the doc now names the exact rule: a stored key reaches a URL stored in config only when one layer set both, a later layer that changes, blanks or removes the URL drops the key, and a write that changes or removes the URL must enter the key again.

* 🧹 refactor: Read the Secret Registry Through getConfigSecretRules Only

The dev merge kept this branch's getConfigSecretFields and getConfigArraySecretFields beside dev's getConfigSecretRules, which returns the same registry data. Only the secret specs used the two extra accessors. They now read getConfigSecretRules().secretFields and .arraySecretFields, so the accessors and their exported ConfigSecretField and ArraySecretField interfaces (duplicates of AdminConfigSecretFieldRule and AdminConfigArraySecretFieldRule) are gone.
2026-10-22 11:29:20 +02:00