LibreChat/api/server/routes/assistants/actions.js
Danny Avila 770238f22b
🔣 refactor: Replace Mongo Filters With Typed Criteria (#15580)
* ♻️ refactor: Take Typed Criteria, Not Mongo Filters, for Actions and Assistants

`createActionMethods` and `createAssistantMethods` accepted `FilterQuery<T>`,
putting Mongoose's query language in the package's public surface: every caller
wrote raw Mongo, and no engine other than Mongo could satisfy the signatures.

Both now take domain criteria — `ActionQuery` and `AssistantQuery` — naming
concepts rather than stored fields, with an array meaning "any of these". A
per-domain field map translates them, so `FilterQuery` survives only inside the
two translators.

`buildFilter` throws on a criterion the field map does not cover. Callers in
`api/` are JavaScript and get no compile-time checking, and the server sets
`strictQuery`, under which a silently dropped criterion widens the filter
instead of narrowing it — an unscoped `findOne` returns an arbitrary document
rather than none. Failing closed is the only safe default.

`AssistantQuery.avatarFilepath` covers the avatar-authorization lookup, which
queries a nested path no plain field name reaches.

No behaviour change: every migrated call site produces the same filter as before.

* 🧪 test: Update Avatar Authorization Assertion to Typed Criteria

`validateImages.spec.js` asserted the old `{ 'avatar.filepath': { $in: [...] } }`
call shape for `getAssistant`. The earlier sweep matched on `action_id`,
`agent_id` and `assistant_id`, none of which appear in a dotted avatar path, so
this one assertion was missed.

The `getAgent` assertions in the same file keep the filter shape — that method
still takes a `FilterQuery`.

* 🔒 fix: Reject Unknown Criteria Before Omitting Undefined Ones

`buildFilter` skipped a criterion whose value was `undefined` before checking it
against the field map, so a JavaScript caller misspelling a key that happened to
carry `undefined` — `deleteActions({ agent_id: maybeId })` — produced `{}` and
reached `deleteMany` unscoped. That is the exact failure the guard exists to
prevent, defeated by the order of the two checks.

Validate every key first, then apply the undefined-omission rule. The lookup is
an own-property check so inherited names cannot resolve through the field map's
prototype: `{ toString: 'x' }` previously found `Function.prototype.toString`,
passed the truthiness test, and wrote a garbage filter key instead of throwing.

A recognized criterion left `undefined` is still omitted, so optional parameters
keep working.

* 🔒 fix: Reject Query Fragments as Criteria and Keep the Translator Internal

Three review findings on the criteria translator, all of the same shape: the
guard was narrower than the surface it protects.

Criterion values are now validated as scalars or lists of scalars. `matchAny`
copied any non-array through unchanged, so a JavaScript caller could pass
`{ agentId: { $ne: null } }` and have the operator land verbatim in the filter
— the fail-open case the field map exists to close. `null` is rejected too; it
would have matched documents missing the field entirely.

`matchAny`, `buildFilter` and `FieldMap` are no longer re-exported from the
package barrel. They emit Mongo, and shipping them as public API undercut the
point of the change; they were reachable as `require('@librechat/data-schemas')
.buildFilter`. `OneOrMany` moves to `types/query` because the domain query types
reference it and it names no engine — which also drops the `types` -> `utils`
import.

`loadActionSets` names `ActionQuery` through `import()` so the JSDoc type
actually resolves.
2026-09-04 11:54:21 -04:00

261 lines
8.7 KiB
JavaScript

const express = require('express');
const { nanoid } = require('nanoid');
const { logger } = require('@librechat/data-schemas');
const {
isActionDomainAllowed,
blockFilteredActionProjection,
validateActionOAuthMetadata,
} = require('@librechat/api');
const { actionDelimiter, EModelEndpoint, removeNullishValues } = require('librechat-data-provider');
const {
legacyDomainEncode,
decryptMetadata,
encryptMetadata,
domainParser,
} = require('~/server/services/ActionService');
const { getOpenAIClient } = require('~/server/controllers/assistants/helpers');
const db = require('~/models');
const router = express.Router();
/**
* Adds or updates actions for a specific assistant.
* @route POST /actions/:assistant_id
* @param {string} req.params.assistant_id - The ID of the assistant.
* @param {FunctionTool[]} req.body.functions - The functions to be added or updated.
* @param {string} [req.body.action_id] - Optional ID for the action.
* @param {ActionMetadata} req.body.metadata - Metadata for the action.
* @returns {Object} 200 - success response - application/json
*/
router.post('/:assistant_id', async (req, res) => {
try {
const appConfig = req.config;
const { assistant_id } = req.params;
/** @type {{ functions: FunctionTool[], action_id: string, metadata: ActionMetadata }} */
const { functions, action_id: _action_id, metadata: _metadata } = req.body;
if (!functions.length) {
return res.status(400).json({ message: 'No functions provided' });
}
if (
blockFilteredActionProjection(req.config?.filters, res, {
functions,
metadata: _metadata,
})
) {
return;
}
let metadata = await encryptMetadata(removeNullishValues(_metadata, true));
const isDomainAllowed = await isActionDomainAllowed(
metadata.domain,
appConfig?.actions?.allowedDomains,
appConfig?.actions?.allowedAddresses,
);
if (!isDomainAllowed) {
return res.status(400).json({ message: 'Domain not allowed' });
}
const encodedDomain = await domainParser(metadata.domain, true);
if (!encodedDomain) {
return res.status(400).json({ message: 'No domain provided' });
}
const legacyDomain = legacyDomainEncode(metadata.domain);
const action_id = _action_id ?? nanoid();
const initialPromises = [];
const { openai } = await getOpenAIClient({ req, res });
initialPromises.push(db.getAssistant({ assistantId: assistant_id }));
initialPromises.push(openai.beta.assistants.retrieve(assistant_id));
!!_action_id && initialPromises.push(db.getActions({ actionId: action_id }, true));
/** @type {[AssistantDocument, Assistant, [Action|undefined]]} */
const [assistant_data, assistant, actions_result] = await Promise.all(initialPromises);
if (actions_result && actions_result.length) {
const action = actions_result[0];
if (action.assistant_id !== assistant_id) {
return res.status(403).json({ message: 'Action does not belong to this assistant' });
}
metadata = { ...action.metadata, ...metadata };
}
try {
await validateActionOAuthMetadata(metadata.auth, appConfig?.actions?.allowedAddresses);
} catch (error) {
return res.status(400).json({ message: error.message });
}
if (!assistant) {
return res.status(404).json({ message: 'Assistant not found' });
}
const { actions: _actions = [], user: assistant_user } = assistant_data ?? {};
const actions = [];
for (const action of _actions) {
const [_action_domain, current_action_id] = action.split(actionDelimiter);
if (current_action_id === action_id) {
continue;
}
actions.push(action);
}
actions.push(`${encodedDomain}${actionDelimiter}${action_id}`);
/** @type {{ tools: FunctionTool[] | { type: 'code_interpreter'|'retrieval'}[]}} */
const { tools: _tools = [] } = assistant;
const shouldRemoveAssistantTool = (tool) => {
if (!tool.function) {
return false;
}
const name = tool.function.name;
return (
name.includes(encodedDomain) || name.includes(legacyDomain) || name.includes(action_id)
);
};
const tools = _tools
.filter((tool) => !shouldRemoveAssistantTool(tool))
.concat(
functions.map((tool) => ({
...tool,
function: {
...tool.function,
name: `${tool.function.name}${actionDelimiter}${encodedDomain}`,
},
})),
);
if (
blockFilteredActionProjection(req.config?.filters, res, {
functions: tools,
metadata: await decryptMetadata(metadata),
})
) {
return;
}
let updatedAssistant = await openai.beta.assistants.update(assistant_id, { tools });
const promises = [];
// Only update user field for new assistant documents
const assistantUpdateData = { actions };
if (!assistant_data) {
assistantUpdateData.user = req.user.id;
}
promises.push(db.updateAssistantDoc({ assistantId: assistant_id }, assistantUpdateData));
// Only update user field for new actions
const actionUpdateData = { metadata, assistant_id };
if (!actions_result || !actions_result.length) {
// For new actions, use the assistant owner's user ID
actionUpdateData.user = assistant_user || req.user.id;
}
promises.push(
db.updateAction({ actionId: action_id, assistantId: assistant_id }, actionUpdateData),
);
/** @type {[AssistantDocument, Action]} */
let [assistantDocument, updatedAction] = await Promise.all(promises);
const sensitiveFields = ['api_key', 'oauth_client_id', 'oauth_client_secret'];
for (let field of sensitiveFields) {
if (updatedAction.metadata[field]) {
delete updatedAction.metadata[field];
}
}
/* Map Azure OpenAI model to the assistant as defined by config */
if (appConfig.endpoints?.[EModelEndpoint.azureOpenAI]?.assistants) {
updatedAssistant = {
...updatedAssistant,
model: req.body.model,
};
}
res.json([assistantDocument, updatedAssistant, updatedAction]);
} catch (error) {
const message = 'Trouble updating the Assistant Action';
logger.error(message, error);
res.status(500).json({ message });
}
});
/**
* Deletes an action for a specific assistant.
* @route DELETE /actions/:assistant_id/:action_id
* @param {string} req.params.assistant_id - The ID of the assistant.
* @param {string} req.params.action_id - The ID of the action to delete.
* @returns {Object} 200 - success response - application/json
*/
router.delete('/:assistant_id/:action_id/:model', async (req, res) => {
try {
const { assistant_id, action_id, model } = req.params;
req.body = req.body || {}; // Express 5: ensure req.body exists
req.body.model = model;
const { openai } = await getOpenAIClient({ req, res });
const initialPromises = [];
initialPromises.push(db.getAssistant({ assistantId: assistant_id }));
initialPromises.push(openai.beta.assistants.retrieve(assistant_id));
/** @type {[AssistantDocument, Assistant]} */
const [assistant_data, assistant] = await Promise.all(initialPromises);
const { actions = [] } = assistant_data ?? {};
const { tools = [] } = assistant ?? {};
let storedDomain = '';
const updatedActions = actions.filter((action) => {
if (action.includes(action_id)) {
[storedDomain] = action.split(actionDelimiter);
return false;
}
return true;
});
if (!storedDomain) {
return res.status(400).json({ message: 'No domain provided' });
}
const updatedTools = tools.filter(
(tool) =>
!(
tool.function &&
(tool.function.name.includes(storedDomain) || tool.function.name.includes(action_id))
),
);
await openai.beta.assistants.update(assistant_id, { tools: updatedTools });
const promises = [];
// Only update user field if assistant document doesn't exist
const assistantUpdateData = { actions: updatedActions };
if (!assistant_data) {
assistantUpdateData.user = req.user.id;
}
promises.push(db.updateAssistantDoc({ assistantId: assistant_id }, assistantUpdateData));
promises.push(db.deleteAction({ actionId: action_id, assistantId: assistant_id }));
const [, deletedAction] = await Promise.all(promises);
if (!deletedAction) {
logger.warn('[Assistant Action Delete] No matching action document found', {
action_id,
assistant_id,
});
}
res.status(200).json({ message: 'Action deleted successfully' });
} catch (error) {
const message = 'Trouble deleting the Assistant Action';
logger.error(message, error);
res.status(500).json({ message });
}
});
module.exports = router;