Skip to content

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

🗂️ feat: Audit MCP, Code Worker, Langfuse, Skill Credential, Passkey and Audit Log Access (#17054)

Marco Beretta9adabde72edd
diff --git a/api/server/controllers/auth/PasskeyController.js b/api/server/controllers/auth/PasskeyController.js
index be868be15a..cc086424ae 100644
--- a/api/server/controllers/auth/PasskeyController.js
+++ b/api/server/controllers/auth/PasskeyController.js
@@ -20,4 +20,5 @@ module.exports = createPasskeyHandlers({
findPasskeysByUser: db.findPasskeysByUser,
countPasskeysByUser: db.countPasskeysByUser,
findPasskeyByCredentialId: db.findPasskeyByCredentialId,
+ recordAuditEntry: db.recordAuditEntry,
});
diff --git a/api/server/controllers/mcp.js b/api/server/controllers/mcp.js
index 8e96eafd3b..0acb942f61 100644
--- a/api/server/controllers/mcp.js
+++ b/api/server/controllers/mcp.js
@@ -20,6 +20,8 @@ const {
redactServerSecrets,
sanitizeMcpIconPath,
redactAllServerSecrets,
+ createMCPServerAuditor,
+ settleMCPCommit,
getMCPErrorResponse,
prepareMCPServerOAuthDeletion,
cleanupDeletedMCPServerOAuthUsers,
@@ -52,6 +54,8 @@ const { hasCapability } = require('~/server/middleware/roles/capabilities');
const { getMCPManager, getMCPServersRegistry } = require('~/config');
const db = require('~/models');
+const auditMCPServer = createMCPServerAuditor({ recordAuditEntry: db.recordAuditEntry });
+
/**
* Handles MCP-specific errors and sends appropriate HTTP responses.
* @param {Error} error - The error to handle
@@ -457,18 +461,30 @@ const createMCPServerController = async (req, res) => {
...new Set([...configNames, ...configNames.map(normalizeServerName)]),
];
const inspectionServerName = `temp_server_${randomUUID()}`;
- let result;
+ let settled;
try {
- result = await getMCPServersRegistry().addServer(
- inspectionServerName,
- validation.data,
- 'DB',
- userId,
- reservedServerNames,
+ settled = await settleMCPCommit(() =>
+ getMCPServersRegistry().addServer(
+ inspectionServerName,
+ validation.data,
+ 'DB',
+ userId,
+ reservedServerNames,
+ ),
);
} finally {
MCPConnection.clearCooldown(inspectionServerName);
}
+ const result = settled.committed;
+ await auditMCPServer(req, {
+ action: 'mcp_server.created',
+ serverName: result.serverName,
+ next: result.config,
+ postWriteFailed: settled.postWriteError != null,
+ });
+ if (settled.postWriteError) {
+ throw settled.postWriteError;
+ }
res.status(201).json({
serverName: result.serverName,
...redactServerSecrets(result.config, { canEdit: true }),
@@ -572,8 +588,11 @@ const updateMCPServerController = async (req, res) => {
);
const retainedTools = await getMCPServerTools(userId, serverName, existingConfig);
await invalidateCachedTools({ userId, serverName });
+ let settled;
try {
- await registry.commitServerUpdate(serverName, parsedConfig, 'DB', userId);
+ settled = await settleMCPCommit(() =>
+ registry.commitServerUpdate(serverName, parsedConfig, 'DB', userId),
+ );
} catch (error) {
await restoreRetainedServerCatalog({
userId,
@@ -583,12 +602,28 @@ const updateMCPServerController = async (req, res) => {
});
throw error;
}
+ const committedConfig = settled.committed ?? parsedConfig;
/** Fence connections another replica could have created from the old DB
* config between the pre-commit fence and the committed update. */
- await fenceCommittedMCPMutation({ userId, serverName });
- await disconnectLocalMCPServer(userId, serverName);
+ await auditMCPServer(
+ req,
+ {
+ action: 'mcp_server.updated',
+ serverName,
+ previous: existingConfig,
+ next: committedConfig,
+ postWriteFailed: settled.postWriteError != null,
+ },
+ async () => {
+ await fenceCommittedMCPMutation({ userId, serverName });
+ await disconnectLocalMCPServer(userId, serverName);
+ },
+ );
+ if (settled.postWriteError) {
+ throw settled.postWriteError;
+ }
- res.status(200).json(redactServerSecrets(parsedConfig, { canEdit: true }));
+ res.status(200).json(redactServerSecrets(committedConfig, { canEdit: true }));
} catch (error) {
logger.error('[updateMCPServer]', error);
const mcpErrorResponse = handleMCPError(error, res);
@@ -631,8 +666,9 @@ const deleteMCPServerController = async (req, res, uninstallOAuthMCP) => {
getMCPServerTools(userId, serverName, existingConfig),
]);
await invalidateCachedTools({ userId, serverName });
+ let settled;
try {
- await registry.removeServer(serverName, 'DB', userId);
+ settled = await settleMCPCommit(() => registry.removeServer(serverName, 'DB', userId));
} catch (error) {
await restoreRetainedServerCatalog({
userId,
@@ -642,34 +678,51 @@ const deleteMCPServerController = async (req, res, uninstallOAuthMCP) => {
});
throw error;
}
- /** Fence connections another replica could have created before deletion committed. */
- await fenceCommittedMCPMutation({ userId, serverName });
- await disconnectLocalMCPServer(userId, serverName);
- try {
- await cleanupDeletedMCPServerOAuthUsers({
- ownerUserId: userId,
+ /** Fence connections another replica could have created before deletion committed,
+ * for every user holding a token, before the audit write is awaited. */
+ await auditMCPServer(
+ req,
+ {
+ action: 'mcp_server.deleted',
serverName,
- serverConfig: existingConfig,
- snapshot: oauthDeletionSnapshot,
- getTokenUserIds,
- getUserPrincipals: (candidateUserId) => db.getUserPrincipals({ userId: candidateUserId }),
- resolveAllowlists: (candidateUserId) =>
- registry.resolveAllowlists({ userId: candidateUserId }),
- fenceAndDisconnectUser: async (candidateUserId) => {
- if (candidateUserId === userId) {
- return;
- }
- await fenceCommittedMCPMutation({ userId: candidateUserId, serverName });
- await disconnectLocalMCPServer(candidateUserId, serverName);
- },
- uninstallOAuthMCP,
- });
- } catch (error) {
- logger.warn(
- `[deleteMCPServer] Server ${serverName} was deleted, but OAuth cleanup failed for user ${userId}:`,
- error,
- );
- throw error;
+ previous: existingConfig,
+ postWriteFailed: settled.postWriteError != null,
+ noop: settled.committed === false,
+ },
+ async () => {
+ await fenceCommittedMCPMutation({ userId, serverName });
+ await disconnectLocalMCPServer(userId, serverName);
+ try {
+ await cleanupDeletedMCPServerOAuthUsers({
+ ownerUserId: userId,
+ serverName,
+ serverConfig: existingConfig,
+ snapshot: oauthDeletionSnapshot,
+ getTokenUserIds,
+ getUserPrincipals: (candidateUserId) =>
+ db.getUserPrincipals({ userId: candidateUserId }),
+ resolveAllowlists: (candidateUserId) =>
+ registry.resolveAllowlists({ userId: candidateUserId }),
+ fenceAndDisconnectUser: async (candidateUserId) => {
+ if (candidateUserId === userId) {
+ return;
+ }
+ await fenceCommittedMCPMutation({ userId: candidateUserId, serverName });
+ await disconnectLocalMCPServer(candidateUserId, serverName);
+ },
+ uninstallOAuthMCP,
+ });
+ } catch (error) {
+ logger.warn(
+ `[deleteMCPServer] Server ${serverName} was deleted, but OAuth cleanup failed for user ${userId}:`,
+ error,
+ );
+ throw error;
+ }
+ },
+ );
+ if (settled.postWriteError) {
+ throw settled.postWriteError;
}
res.status(200).json({ message: 'MCP server deleted successfully' });
} catch (error) {
diff --git a/api/server/routes/__tests__/mcp.spec.js b/api/server/routes/__tests__/mcp.spec.js
index 1590813635..a32577b362 100644
--- a/api/server/routes/__tests__/mcp.spec.js
+++ b/api/server/routes/__tests__/mcp.spec.js
@@ -137,6 +137,7 @@ jest.mock('~/models', () => ({
deleteTokens: jest.fn(),
findPluginAuthsByKeys: jest.fn(),
getRoleByName: jest.fn(),
+ recordAuditEntry: jest.fn(),
}));
jest.mock('~/server/services/Config', () => ({
@@ -4063,6 +4064,63 @@ describe('MCP Routes', () => {
expect(MCPConnection.clearCooldown).toHaveBeenCalledWith(inspectionServerName);
});
+ it('records mcp_server.created with field names and no secret values', async () => {
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ const validConfig = {
+ type: 'sse',
+ url: 'https://mcp-server.example.com/sse',
+ title: 'Audited Server',
+ headers: { Authorization: 'Bearer super-secret-token' },
+ };
+ mockRegistryInstance.addServer.mockResolvedValue({
+ serverName: 'audited-server',
+ config: { ...validConfig, source: 'user' },
+ });
+
+ const response = await request(app).post('/api/mcp/servers').send({ config: validConfig });
+
+ expect(response.status).toBe(201);
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ const input = recordAuditEntry.mock.calls[0][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'mcp_server.created',
+ target: { type: 'mcp_server', id: 'audited-server', name: 'Audited Server' },
+ metadata: { source: 'DB', fields: 'headers,title,type,url' },
+ }),
+ );
+ expect(JSON.stringify(input)).not.toContain('super-secret-token');
+ });
+
+ it('audits a create that committed before the cache refresh failed, then returns 500', async () => {
+ const { MCPCommittedWriteError } = require('@librechat/api');
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ const validConfig = {
+ type: 'sse',
+ url: 'https://mcp-server.example.com/sse',
+ title: 'Audited Server',
+ };
+ mockRegistryInstance.addServer.mockRejectedValueOnce(
+ new MCPCommittedWriteError(
+ { serverName: 'audited-server', config: { ...validConfig, source: 'user' } },
+ new Error('redis down'),
+ ),
+ );
+
+ const response = await request(app).post('/api/mcp/servers').send({ config: validConfig });
+
+ expect(response.status).toBe(500);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.created',
+ target: { type: 'mcp_server', id: 'audited-server', name: 'Audited Server' },
+ metadata: expect.objectContaining({ postWrite: 'failed' }),
+ }),
+ );
+ });
+
it('should reserve config-managed server names when creating MCP server', async () => {
const validConfig = {
type: 'sse',
@@ -4585,6 +4643,93 @@ describe('MCP Routes', () => {
);
});
+ it('records mcp_server.updated with only the changed field names', async () => {
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ const existing = {
+ type: 'sse',
+ url: 'https://old.example.com/sse',
+ title: 'Same Title',
+ headers: { Authorization: 'Bearer old-secret' },
+ };
+ const updated = {
+ ...existing,
+ url: 'https://new.example.com/sse',
+ headers: { Authorization: 'Bearer new-secret' },
+ };
+ mockRegistryInstance.getServerConfig.mockResolvedValueOnce(existing);
+ mockRegistryInstance.inspectServerUpdate.mockResolvedValue({ ...updated, source: 'user' });
+ mockRegistryInstance.commitServerUpdate.mockResolvedValue({ ...updated, source: 'user' });
+
+ const response = await request(app)
+ .patch('/api/mcp/servers/test-server')
+ .send({ config: updated });
+
+ expect(response.status).toBe(200);
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ const input = recordAuditEntry.mock.calls[0][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'mcp_server.updated',
+ target: { type: 'mcp_server', id: 'test-server', name: 'Same Title' },
+ metadata: { source: 'DB', fields: 'headers,url' },
+ }),
+ );
+ expect(JSON.stringify(input)).not.toContain('secret');
+ });
+
+ it('audits the config this write persisted, not a later overlapping write', async () => {
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ const existing = { type: 'sse', url: 'https://old.example.com/sse', title: 'Same Title' };
+ const submitted = { ...existing, url: 'https://new.example.com/sse' };
+ mockRegistryInstance.getServerConfig.mockResolvedValue({
+ ...existing,
+ url: 'https://other-writer.example.com/sse',
+ title: 'Other Writer',
+ });
+ mockRegistryInstance.getServerConfig.mockResolvedValueOnce(existing);
+ mockRegistryInstance.inspectServerUpdate.mockResolvedValue({ ...submitted, source: 'user' });
+ mockRegistryInstance.commitServerUpdate.mockResolvedValue({ ...submitted, source: 'user' });
+
+ const response = await request(app)
+ .patch('/api/mcp/servers/test-server')
+ .send({ config: submitted });
+
+ expect(response.status).toBe(200);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ target: { type: 'mcp_server', id: 'test-server', name: 'Same Title' },
+ metadata: { source: 'DB', fields: 'url' },
+ }),
+ );
+ });
+
+ it('audits an update that committed before the cache refresh failed, then returns 500', async () => {
+ const { MCPCommittedWriteError } = require('@librechat/api');
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ const existing = { type: 'sse', url: 'https://old.example.com/sse', title: 'Same Title' };
+ const submitted = { ...existing, url: 'https://new.example.com/sse' };
+ mockRegistryInstance.getServerConfig.mockResolvedValueOnce(existing);
+ mockRegistryInstance.inspectServerUpdate.mockResolvedValue({ ...submitted, source: 'user' });
+ mockRegistryInstance.commitServerUpdate.mockRejectedValueOnce(
+ new MCPCommittedWriteError({ ...submitted, source: 'user' }, new Error('redis down')),
+ );
+
+ const response = await request(app)
+ .patch('/api/mcp/servers/test-server')
+ .send({ config: submitted });
+
+ expect(response.status).toBe(500);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.updated',
+ metadata: { source: 'DB', fields: 'url', postWrite: 'failed' },
+ }),
+ );
+ });
+
it('should redact secrets from update response', async () => {
const validConfig = {
type: 'sse',
@@ -4759,6 +4904,56 @@ describe('MCP Routes', () => {
);
});
+ it('records mcp_server.deleted only after the removal succeeds', async () => {
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ mockRegistryInstance.removeServer.mockRejectedValueOnce(new Error('Deletion failed'));
+ await request(app).delete('/api/mcp/servers/audited-server');
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+
+ mockRegistryInstance.removeServer.mockResolvedValue(undefined);
+ const response = await request(app).delete('/api/mcp/servers/audited-server');
+
+ expect(response.status).toBe(200);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.deleted',
+ target: { type: 'mcp_server', id: 'audited-server' },
+ metadata: { source: 'DB' },
+ }),
+ );
+ });
+
+ it('audits a removal that committed before the cache refresh failed, then returns 500', async () => {
+ const { MCPCommittedWriteError } = require('@librechat/api');
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ mockRegistryInstance.removeServer.mockRejectedValueOnce(
+ new MCPCommittedWriteError(undefined, new Error('redis down')),
+ );
+
+ const response = await request(app).delete('/api/mcp/servers/audited-server');
+
+ expect(response.status).toBe(500);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.deleted',
+ metadata: { source: 'DB', postWrite: 'failed' },
+ }),
+ );
+ });
+
+ it('does not audit a delete that found nothing to remove', async () => {
+ const { recordAuditEntry } = require('~/models');
+ recordAuditEntry.mockClear();
+ mockRegistryInstance.removeServer.mockResolvedValueOnce(false);
+
+ const response = await request(app).delete('/api/mcp/servers/already-gone');
+
+ expect(response.status).toBe(200);
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+ });
+
it('should return 500 when registry throws error', async () => {
mockRegistryInstance.removeServer.mockRejectedValue(new Error('Deletion failed'));
diff --git a/api/server/routes/admin/audit.js b/api/server/routes/admin/audit.js
index 7332f8296a..55bae48a06 100644
--- a/api/server/routes/admin/audit.js
+++ b/api/server/routes/admin/audit.js
@@ -1,5 +1,5 @@
const express = require('express');
-const { createAdminAuditLogHandlers } = require('@librechat/api');
+const { createAdminAuditLogHandlers, isAuditFailClosed } = require('@librechat/api');
const { SystemCapabilities } = require('@librechat/data-schemas');
const { requireCapability } = require('~/server/middleware/roles/capabilities');
const { requireJwtAuth } = require('~/server/middleware');
@@ -15,6 +15,8 @@ const handlers = createAdminAuditLogHandlers({
findAuditLogEntry: db.findAuditLogEntry,
streamAuditLogEntries: db.streamAuditLogEntries,
verifyAuditChain: db.verifyAuditChain,
+ recordAuditEntry: db.recordAuditEntry,
+ auditFailClosed: isAuditFailClosed(),
});
/**
diff --git a/api/server/routes/admin/code.js b/api/server/routes/admin/code.js
index 4888a9a451..0958965625 100644
--- a/api/server/routes/admin/code.js
+++ b/api/server/routes/admin/code.js
@@ -1,9 +1,10 @@
const express = require('express');
-const { createAdminCodeEnvironmentHandlers } = require('@librechat/api');
+const { createAdminCodeEnvironmentHandlers, isAuditFailClosed } = require('@librechat/api');
const { SystemCapabilities } = require('@librechat/data-schemas');
const { requireCapability } = require('~/server/middleware/roles/capabilities');
const { getAppConfig } = require('~/server/services/Config');
const { requireJwtAuth } = require('~/server/middleware');
+const db = require('~/models');
const router = express.Router();
const requireAdminAccess = requireCapability(SystemCapabilities.ACCESS_ADMIN);
@@ -11,7 +12,11 @@ const requireCodeEnvironmentManage = requireCapability(
SystemCapabilities.MANAGE_CODE_ENVIRONMENTS,
{ platformOnly: true },
);
-const handlers = createAdminCodeEnvironmentHandlers({ getAppConfig });
+const handlers = createAdminCodeEnvironmentHandlers({
+ getAppConfig,
+ recordAuditEntry: db.recordAuditEntry,
+ auditFailClosed: isAuditFailClosed(),
+});
router.use(requireJwtAuth, requireAdminAccess, requireCodeEnvironmentManage);
router.post('/:environmentId/pairings', handlers.createPairing);
diff --git a/api/server/routes/admin/code.test.js b/api/server/routes/admin/code.test.js
index f293ed2883..eb0921f45e 100644
--- a/api/server/routes/admin/code.test.js
+++ b/api/server/routes/admin/code.test.js
@@ -30,6 +30,7 @@ jest.mock('@librechat/data-schemas', () => ({
jest.mock('@librechat/api', () => ({
createAdminCodeEnvironmentHandlers: jest.fn(() => mockHandlers),
+ isAuditFailClosed: jest.fn(() => true),
}));
jest.mock('~/server/middleware/roles/capabilities', () => ({
@@ -44,6 +45,10 @@ jest.mock('~/server/services/Config', () => ({
getAppConfig: mockGetAppConfig,
}));
+jest.mock('~/models', () => ({
+ recordAuditEntry: jest.fn(),
+}));
+
function createApp() {
delete require.cache[require.resolve('./code')];
const router = require('./code');
diff --git a/api/server/routes/admin/groups.js b/api/server/routes/admin/groups.js
index 8ee3aefaad..339abf75d8 100644
--- a/api/server/routes/admin/groups.js
+++ b/api/server/routes/admin/groups.js
@@ -24,6 +24,8 @@ const handlers = createAdminGroupsHandlers({
findUsers: db.findUsers,
deleteConfig: db.deleteConfig,
deleteAclEntries: db.deleteAclEntries,
+ restoreConfig: db.restoreConfig,
+ findConfigByPrincipal: db.findConfigByPrincipal,
recordAuditEntry: db.recordAuditEntry,
auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',
});
diff --git a/api/server/routes/admin/langfuse.js b/api/server/routes/admin/langfuse.js
index 515a5893b7..bcfc9bf897 100644
--- a/api/server/routes/admin/langfuse.js
+++ b/api/server/routes/admin/langfuse.js
@@ -41,6 +41,7 @@ const handlers = createAdminLangfuseHandlers({
toggleConfigActive: db.toggleConfigActive,
getMessages: db.getMessages,
invalidateConfigCaches,
+ recordAuditEntry: db.recordAuditEntry,
});
// `configMiddleware` runs last so unauthorized callers are rejected before the
diff --git a/api/server/routes/admin/skills.js b/api/server/routes/admin/skills.js
index 54e54004ff..9a5b0dd15f 100644
--- a/api/server/routes/admin/skills.js
+++ b/api/server/routes/admin/skills.js
@@ -3,7 +3,11 @@ const { createAdminSkillsSyncAccess, createAdminSkillsSyncHandlers } = require('
const { SystemCapabilities } = require('@librechat/data-schemas');
const { hasCapability, requireCapability } = require('~/server/middleware/roles/capabilities');
const { requireJwtAuth } = require('~/server/middleware');
-const { upsertSkillSyncCredential, deleteSkillSyncCredential } = require('~/models');
+const {
+ upsertSkillSyncCredential,
+ deleteSkillSyncCredential,
+ recordAuditEntry,
+} = require('~/models');
const { getGitHubSkillSyncRunnerForRequest } = require('~/server/services/Skills/sync');
const { getAppConfig } = require('~/server/services/Config');
const configMiddleware = require('~/server/middleware/config/app');
@@ -20,6 +24,7 @@ const handlers = createAdminSkillsSyncHandlers({
getRunner: getGitHubSkillSyncRunnerForRequest,
upsertCredential: upsertSkillSyncCredential,
deleteCredential: deleteSkillSyncCredential,
+ recordAuditEntry,
});
router.use(
diff --git a/api/server/routes/admin/skills.test.js b/api/server/routes/admin/skills.test.js
index f452d6ea21..81562b9d8b 100644
--- a/api/server/routes/admin/skills.test.js
+++ b/api/server/routes/admin/skills.test.js
@@ -57,6 +57,7 @@ jest.mock('~/server/services/Config', () => ({
jest.mock('~/models', () => ({
upsertSkillSyncCredential: jest.fn(),
deleteSkillSyncCredential: jest.fn(),
+ recordAuditEntry: jest.fn(),
}));
jest.mock('~/server/services/Skills/sync', () => ({
diff --git a/e2e/specs/mock/scenarios/admin-audit-integrations.spec.ts b/e2e/specs/mock/scenarios/admin-audit-integrations.spec.ts
new file mode 100644
index 0000000000..76ff847cdc
--- /dev/null
+++ b/e2e/specs/mock/scenarios/admin-audit-integrations.spec.ts
@@ -0,0 +1,114 @@
+import { resolve } from 'node:path';
+import { expect, test } from '@playwright/test';
+import { run, repoRoot, inOneProject } from './lint.helpers';
+
+/**
+ * Admin integration changes (MCP servers, Langfuse, audit log reads and
+ * exports, group deletion) leave an audit trail that never carries secrets or
+ * searched-for text, and a group is only removed once its permissions are.
+ * Each probe drives the real handlers from the built @librechat/api with an
+ * in-memory recorder and prints the result as JSON.
+ */
+
+const PREAMBLE = `
+const api = require('@librechat/api');
+const { Types } = require('mongoose');
+const out = (value) => { process.stdout.write('RESULT' + JSON.stringify(value)); process.exit(0); };
+const makeRes = () => {
+ const res = { statusCode: 200, body: undefined, headers: {}, chunks: [] };
+ res.status = (code) => { res.statusCode = code; return res; };
+ res.json = (body) => { res.body = body; return res; };
+ res.setHeader = (key, value) => { res.headers[key] = value; };
+ res.write = (chunk) => { res.chunks.push(String(chunk)); return true; };
+ res.end = () => res;
+ res.once = () => res;
+ res.on = () => res;
+ return res;
+};
+const user = { _id: new Types.ObjectId(), name: 'Admin', email: '[email protected]' };
+`;
+
+function probe(body: string): unknown {
+ const result = run(
+ 'node',
+ [
+ '-e',
+ `${PREAMBLE}\n(async () => {\n${body}\n})().catch((e) => { console.error(e); process.exit(1); });`,
+ ],
+ {
+ cwd: resolve(repoRoot, 'api'),
+ },
+ );
+ expect(result.status, result.output).toBe(0);
+ return JSON.parse(result.stdout.slice(result.stdout.indexOf('RESULT') + 'RESULT'.length));
+}
+
+test.describe('admin integration auditing', () => {
+ test.beforeEach(() => inOneProject());
+
+ test('an MCP server update is audited by field name without the values @scenario:mcp-server-update-audit-lists-field-names-only', () => {
+ const entries = probe(`
+ const entries = [];
+ const audit = api.createMCPServerAuditor({ recordAuditEntry: async (input) => { entries.push(input); } });
+ await audit({ user }, {
+ action: 'mcp_server.updated',
+ serverName: 'srv',
+ previous: { title: 'Docs', url: 'https://old.example.com', headers: { Authorization: 'Bearer old-secret' } },
+ next: { title: 'Docs', url: 'https://old.example.com', headers: { Authorization: 'Bearer new-secret' } },
+ });
+ out(entries);
+ `) as Array<{ action: string; target: { id: string }; metadata: { fields?: string } }>;
+ expect(entries).toHaveLength(1);
+ expect(entries[0].action).toBe('mcp_server.updated');
+ expect(entries[0].target.id).toBe('srv');
+ expect(entries[0].metadata.fields).toBe('headers');
+ expect(JSON.stringify(entries)).not.toContain('secret');
+ });
+
+ test('an MCP server deletion is audited as a warning @scenario:mcp-server-delete-audit-is-a-warning', () => {
+ const entries = probe(`
+ const entries = [];
+ const audit = api.createMCPServerAuditor({ recordAuditEntry: async (input) => { entries.push(input); } });
+ await audit({ user }, { action: 'mcp_server.deleted', serverName: 'gone', previous: { title: 'Gone' } });
+ out(entries);
+ `) as Array<{ action: string; severity: string }>;
+ expect(entries[0].action).toBe('mcp_server.deleted');
+ expect(entries[0].severity).toBe('warning');
+ });
+
+ test('an audit write failure does not turn a deleted MCP server into an error @scenario:audit-write-failure-keeps-the-completed-change', () => {
+ const result = probe(`
+ const audit = api.createMCPServerAuditor({ recordAuditEntry: async () => { throw new Error('db down'); } });
+ let threw = false;
+ try {
+ await audit({ user }, { action: 'mcp_server.created', serverName: 'srv', next: { title: 'Docs' } });
+ } catch { threw = true; }
+ out({ threw });
+ `) as { threw: boolean };
+ expect(result.threw).toBe(false);
+ });
+
+ test('a group whose cleanup fails is kept with its config restored and reports GROUP_CLEANUP_FAILED @scenario:group-delete-keeps-the-group-when-cleanup-fails', () => {
+ const result = probe(`
+ const id = new Types.ObjectId().toString();
+ let deleted = false;
+ const restored = [];
+ const noop = async () => undefined;
+ const handlers = api.createAdminGroupsHandlers({
+ listGroups: noop, countGroups: noop, createGroup: noop, updateGroupById: noop,
+ findGroupById: async () => ({ _id: new Types.ObjectId(id), name: 'G', memberIds: [] }),
+ deleteGroup: async () => { deleted = true; return { _id: id }; },
+ restoreConfig: async () => { restored.push('config'); return true; },
+ deleteConfig: async () => ({ principalType: 'group', principalId: id, overrides: {} }),
+ deleteAclEntries: async () => { throw new Error('acl store down'); },
+ });
+ const res = makeRes();
+ await handlers.deleteGroup({ params: { id }, query: {}, body: {}, user }, res);
+ out({ status: res.statusCode, code: res.body && res.body.code, deleted, restored });
+ `) as { status: number; code?: string; deleted: boolean; restored: string[] };
+ expect(result.status).toBe(500);
+ expect(result.code).toBe('GROUP_CLEANUP_FAILED');
+ expect(result.deleted).toBe(false);
+ expect(result.restored).toEqual(['config']);
+ });
+});
diff --git a/packages/api/src/admin/auditLog.spec.ts b/packages/api/src/admin/auditLog.spec.ts
index 5c5134bf6a..d5395fe233 100644
--- a/packages/api/src/admin/auditLog.spec.ts
+++ b/packages/api/src/admin/auditLog.spec.ts
@@ -114,6 +114,7 @@ function createCsvContext(
}),
end: jest.fn(() => {
ended = true;
+ emitter.emit('finish');
}),
headersSent: false,
status: jest.fn().mockReturnValue({ json: jest.fn() }),
@@ -351,6 +352,24 @@ describe('createAdminAuditLogHandlers', () => {
expect(status).toHaveBeenCalledWith(401);
});
+ it('records audit.read for an integrity verification', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createAdminAuditLogHandlers(createDeps({ recordAuditEntry }));
+ const { req, res } = createReqRes({
+ user: { _id: new Types.ObjectId(), role: 'admin' },
+ });
+
+ await handlers.verifyAuditLog(req, res);
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'audit.read',
+ target: { type: 'audit_log' },
+ metadata: { operation: 'verify' },
+ }),
+ );
+ });
+
it('returns the verification result scoped to the caller tenant', async () => {
const verification = mockVerification({ ok: false, brokenAt: 2, reason: 'hash mismatch' });
const deps = createDeps({ verifyAuditChain: jest.fn().mockResolvedValue(verification) });
@@ -488,4 +507,189 @@ describe('createAdminAuditLogHandlers', () => {
expect(ctx.endCalled()).toBe(true);
});
});
+
+ describe('audit entries', () => {
+ const user = { _id: new Types.ObjectId(), role: 'admin' };
+
+ it('records audit.read for a list with filters but not free-text values', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createAdminAuditLogHandlers(createDeps({ recordAuditEntry }));
+ const { req, res, status } = createReqRes({
+ user,
+ query: {
+ action: ['role.created', 'group.created'],
+ outcome: 'success',
+ from: '2025-01-01',
+ actorQuery: '[email protected]',
+ search: 'secret-term',
+ capability: '[email protected]',
+ targetType: 'user-typed-text',
+ },
+ });
+
+ await handlers.listAuditLog(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ const input = recordAuditEntry.mock.calls[0][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'audit.read',
+ target: { type: 'audit_log' },
+ metadata: {
+ action: 'group.created,role.created',
+ outcome: 'success',
+ from: '2025-01-01T00:00:00.000Z',
+ freeTextFilters: 'search,actorQuery,targetType,capability',
+ },
+ }),
+ );
+ expect(JSON.stringify(input)).not.toContain('[email protected]');
+ expect(JSON.stringify(input)).not.toContain('secret-term');
+ expect(JSON.stringify(input)).not.toContain('[email protected]');
+ expect(JSON.stringify(input)).not.toContain('user-typed-text');
+ });
+
+ it('withholds the rows and answers 500 when a fail-closed audit write fails', async () => {
+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));
+ const listAuditLogPage = jest
+ .fn()
+ .mockResolvedValue({ entries: [mockEntry()], nextCursor: null });
+ const handlers = createAdminAuditLogHandlers(
+ createDeps({ recordAuditEntry, auditFailClosed: true, listAuditLogPage }),
+ );
+ const { req, res, status, json } = createReqRes({ user });
+
+ await handlers.listAuditLog(req, res);
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(expect.anything(), { failClosed: true });
+ expect(status).toHaveBeenCalledWith(500);
+ expect(JSON.stringify(json.mock.calls)).not.toContain('entries');
+ });
+
+ it('records audit.read for a single entry only when it exists', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const found = createAdminAuditLogHandlers(
+ createDeps({
+ recordAuditEntry,
+ findAuditLogEntry: jest.fn().mockResolvedValue(mockEntry()),
+ }),
+ );
+ const missing = createAdminAuditLogHandlers(createDeps({ recordAuditEntry }));
+
+ const a = createReqRes({ user, params: { id: validObjectId } });
+ await missing.getAuditLogEntry(a.req, a.res);
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+
+ const b = createReqRes({ user, params: { id: validObjectId } });
+ await found.getAuditLogEntry(b.req, b.res);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'audit.read',
+ target: { type: 'audit_log', id: validObjectId },
+ }),
+ );
+ });
+
+ it('records audit.exported before the first row is written', async () => {
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async () => {
+ order.push('audit');
+ });
+ const deps = createDeps({
+ recordAuditEntry,
+ streamAuditLogEntries: jest.fn().mockImplementation(async () => {
+ order.push('stream');
+ return { count: 0, truncated: false };
+ }),
+ });
+ const handlers = createAdminAuditLogHandlers(deps);
+ const ctx = createCsvContext({ user, query: { severity: 'critical' } });
+
+ await handlers.exportAuditLogCsv(ctx.req, ctx.res);
+
+ expect(order).toEqual(['audit', 'stream', 'audit']);
+ expect(recordAuditEntry).toHaveBeenNthCalledWith(
+ 1,
+ expect.objectContaining({
+ action: 'audit.exported',
+ outcome: 'pending',
+ metadata: { format: 'csv', severity: 'critical' },
+ }),
+ );
+ const terminal = recordAuditEntry.mock.calls[recordAuditEntry.mock.calls.length - 1][0];
+ expect(terminal).toEqual(
+ expect.objectContaining({
+ action: 'audit.exported',
+ metadata: { format: 'csv', severity: 'critical', rows: 0, truncated: false },
+ }),
+ );
+ expect(terminal.outcome).toBeUndefined();
+ });
+
+ it('records a client that disconnects during the final flush as a failed export', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const deps = createDeps({
+ recordAuditEntry,
+ streamAuditLogEntries: jest.fn().mockResolvedValue({ count: 0, truncated: false }),
+ });
+ const handlers = createAdminAuditLogHandlers(deps);
+ const ctx = createCsvContext({ user, query: { severity: 'critical' } });
+ (ctx.res.end as jest.Mock).mockImplementation(() => {
+ (ctx.res as unknown as EventEmitter).emit('close');
+ });
+
+ await handlers.exportAuditLogCsv(ctx.req, ctx.res);
+
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ outcome: 'failure',
+ metadata: expect.objectContaining({ code: 'client_aborted' }),
+ }),
+ );
+ });
+
+ it('appends a failure entry when the export fails after it was recorded', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const deps = createDeps({
+ recordAuditEntry,
+ streamAuditLogEntries: jest.fn().mockRejectedValue(new Error('cursor failed')),
+ });
+ const handlers = createAdminAuditLogHandlers(deps);
+ const ctx = createCsvContext({ user, query: { severity: 'critical' } });
+
+ await handlers.exportAuditLogCsv(ctx.req, ctx.res);
+
+ expect(recordAuditEntry).toHaveBeenCalledTimes(2);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ action: 'audit.exported',
+ outcome: 'failure',
+ metadata: { format: 'csv', severity: 'critical', code: 'export_failed' },
+ }),
+ );
+ });
+
+ it('does not record an export that fails filter validation', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createAdminAuditLogHandlers(createDeps({ recordAuditEntry }));
+ const ctx = createCsvContext({ user, query: { action: 'nope.nope' } });
+
+ await handlers.exportAuditLogCsv(ctx.req, ctx.res);
+
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+ });
+
+ it('blocks the export when failClosed and the audit write fails', async () => {
+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));
+ const deps = createDeps({ recordAuditEntry, auditFailClosed: true });
+ const handlers = createAdminAuditLogHandlers(deps);
+ const ctx = createCsvContext({ user });
+
+ await handlers.exportAuditLogCsv(ctx.req, ctx.res);
+
+ expect(deps.streamAuditLogEntries).not.toHaveBeenCalled();
+ expect(ctx.chunks).toHaveLength(0);
+ });
+ });
});
diff --git a/packages/api/src/admin/auditLog.ts b/packages/api/src/admin/auditLog.ts
index 570e70ddf0..0bc5addae5 100644
--- a/packages/api/src/admin/auditLog.ts
+++ b/packages/api/src/admin/auditLog.ts
@@ -20,8 +20,12 @@ import type {
AuditOutcome,
AuditSeverity,
} from '@librechat/data-schemas';
+import type { AuditMetadata } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { ServerRequest } from '~/types/http';
+import type { RecordAuditEntry } from './audit';
+import { getSafeErrorMetadata } from '~/utils/errors';
+import { createAdminAuditEmitter } from './audit';
const FORMULA_PREFIX = /^[=+\-@\t\r]/;
/** UTF-8 BOM, written first so Excel recognizes the encoding on import. Spelled
@@ -64,6 +68,9 @@ export interface AdminAuditLogDeps {
tenantId: string | undefined,
options?: { isCancelled?: () => boolean; maxRows?: number },
) => Promise<AuditChainVerification>;
+ /** Optional audit emission for reads and exports; fail-open unless `auditFailClosed`. */
+ recordAuditEntry?: RecordAuditEntry;
+ auditFailClosed?: boolean;
}
interface CallerContext {
@@ -270,6 +277,32 @@ function parseFilters(query: AuditLogQuery): ParseResult<ParsedFilters> {
};
}
+/**
+ * Describes a filter set for the audit trail without storing what was searched
+ * for: enum and date filters are recorded as given, free-text filters (which can
+ * carry names or email addresses) only by name.
+ */
+function describeFilters(filters: ParsedFilters): AuditMetadata {
+ const metadata: AuditMetadata = {};
+ const lists: Array<[string, string[] | undefined]> = [
+ ['category', filters.category],
+ ['action', filters.action],
+ ['outcome', filters.outcome],
+ ['severity', filters.severity],
+ ];
+ for (const [key, values] of lists) {
+ if (values?.length) metadata[key] = [...values].sort().join(',');
+ }
+ if (filters.actorType) metadata.actorType = filters.actorType;
+ if (filters.from) metadata.from = filters.from.toISOString();
+ if (filters.to) metadata.to = filters.to.toISOString();
+ const freeText = (
+ ['search', 'actorQuery', 'targetQuery', 'targetType', 'capability'] as const
+ ).filter((key) => filters[key] != null);
+ if (freeText.length > 0) metadata.freeTextFilters = freeText.join(',');
+ return metadata;
+}
+
export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
listAuditLog: (req: ServerRequest, res: Response) => Promise<Response>;
getAuditLogEntry: (req: ServerRequest, res: Response) => Promise<Response>;
@@ -277,6 +310,17 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
exportAuditLogCsv: (req: ServerRequest, res: Response) => Promise<Response | void>;
} {
const { listAuditLogPage, findAuditLogEntry, streamAuditLogEntries, verifyAuditChain } = deps;
+ const emitAudit = createAdminAuditEmitter({
+ recordAuditEntry: deps.recordAuditEntry,
+ failClosed: deps.auditFailClosed,
+ logPrefix: '[adminAuditLog]',
+ });
+
+ /** Follow-up entries describe an attempt that already happened, so they never fail the caller. */
+ const emitFollowUp = createAdminAuditEmitter({
+ recordAuditEntry: deps.recordAuditEntry,
+ logPrefix: '[adminAuditLog]',
+ });
async function listAuditLogHandler(req: ServerRequest, res: Response) {
try {
@@ -301,9 +345,14 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
cursor: cursor.value,
});
+ await emitAudit(req, {
+ action: 'audit.read',
+ target: { type: 'audit_log' },
+ metadata: describeFilters(filters.value),
+ });
return res.status(200).json(page);
} catch (err) {
- logger.error('[adminAuditLog] list error:', err);
+ logger.error('[adminAuditLog] list error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to fetch audit log' });
}
}
@@ -320,9 +369,13 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
const entry = await findAuditLogEntry(caller.tenantId, id);
if (!entry) return res.status(404).json({ error: 'Not found' });
+ await emitAudit(req, {
+ action: 'audit.read',
+ target: { type: 'audit_log', id },
+ });
return res.status(200).json({ entry });
} catch (err) {
- logger.error('[adminAuditLog] get error:', err);
+ logger.error('[adminAuditLog] get error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to fetch audit log entry' });
}
}
@@ -346,18 +399,25 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
});
if (clientAborted) return res;
+ await emitAudit(req, {
+ action: 'audit.read',
+ target: { type: 'audit_log' },
+ metadata: { operation: 'verify' },
+ });
return res.status(200).json(result);
} finally {
res.removeListener('close', markAborted);
req.removeListener('aborted', markAborted);
}
} catch (err) {
- logger.error('[adminAuditLog] verify error:', err);
+ logger.error('[adminAuditLog] verify error:', getSafeErrorMetadata(err));
return res.status(500).json({ error: 'Failed to verify audit log integrity' });
}
}
async function exportAuditLogCsvHandler(req: ServerRequest, res: Response) {
+ let exportRecorded = false;
+ let exportFailed: ((code: string) => Promise<void>) | undefined;
try {
const caller = resolveCaller(req);
if (!caller) return res.status(401).json({ error: 'Authentication required' });
@@ -365,11 +425,6 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
const filters = parseFilters(req.query as AuditLogQuery);
if (!filters.ok) return res.status(400).json({ error: filters.error });
- const filenameStamp = new Date().toISOString().slice(0, 10);
- res.setHeader('Content-Type', 'text/csv; charset=utf-8');
- res.setHeader('Content-Disposition', `attachment; filename="audit-log-${filenameStamp}.csv"`);
- res.setHeader('Cache-Control', 'no-store');
-
/**
* The socket-`close` listener is the canonical signal — it fires on client
* TCP RST as well as on graceful end. `req.aborted` (deprecated) is kept as
@@ -384,6 +439,27 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
req.once('aborted', markAborted);
const isCancelled = () => clientAborted;
+ /** Recorded as pending before any row is streamed, so an export is never unaudited; `success` follows once the stream ends. */
+ const exportEvent = {
+ action: 'audit.exported' as const,
+ severity: 'warning' as const,
+ target: { type: 'audit_log' },
+ metadata: { format: 'csv', ...describeFilters(filters.value) },
+ };
+ await emitAudit(req, { ...exportEvent, outcome: 'pending' });
+ exportRecorded = true;
+ exportFailed = (code: string) =>
+ emitFollowUp(req, {
+ ...exportEvent,
+ outcome: 'failure',
+ metadata: { ...exportEvent.metadata, code },
+ });
+
+ const filenameStamp = new Date().toISOString().slice(0, 10);
+ res.setHeader('Content-Type', 'text/csv; charset=utf-8');
+ res.setHeader('Content-Disposition', `attachment; filename="audit-log-${filenameStamp}.csv"`);
+ res.setHeader('Cache-Control', 'no-store');
+
/**
* Wait for `drain` when the socket buffer is full so we never queue an
* unbounded amount of CSV in Node memory for slow consumers. Race against
@@ -411,7 +487,7 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
await writeChunk(formatCsvHeader());
await writeChunk('\r\n');
- const { truncated } = await streamAuditLogEntries(
+ const { truncated, count } = await streamAuditLogEntries(
caller.tenantId,
filters.value,
async (entry) => {
@@ -424,7 +500,19 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
res.removeListener('close', markAborted);
req.removeListener('aborted', markAborted);
+ if (clientAborted) {
+ await exportFailed('client_aborted');
+ }
if (!clientAborted) {
+ /** `end()` only queues the last bytes, so success waits for the response to finish. */
+ const settled = new Promise<boolean>((resolve) => {
+ if (res.destroyed) {
+ resolve(false);
+ return;
+ }
+ res.once('finish', () => resolve(true));
+ res.once('close', () => resolve(res.writableFinished === true));
+ });
/**
* `truncated` is true only when rows existed beyond the cap (an exact-cap
* match is reported as complete). Surfacing this is a compliance
@@ -441,9 +529,20 @@ export function createAdminAuditLogHandlers(deps: AdminAuditLogDeps): {
);
}
res.end();
+ if (await settled) {
+ await emitFollowUp(req, {
+ ...exportEvent,
+ metadata: { ...exportEvent.metadata, rows: count, truncated },
+ });
+ } else {
+ await exportFailed('client_aborted');
+ }
}
} catch (err) {
- logger.error('[adminAuditLog] export error:', err);
+ logger.error('[adminAuditLog] export error:', getSafeErrorMetadata(err));
+ if (exportRecorded) {
+ await exportFailed?.('export_failed');
+ }
if (!res.headersSent) {
return res.status(500).json({ error: 'Failed to export audit log' });
}
diff --git a/packages/api/src/admin/code.spec.ts b/packages/api/src/admin/code.spec.ts
index 894c8c36b0..d8065ba358 100644
--- a/packages/api/src/admin/code.spec.ts
+++ b/packages/api/src/admin/code.spec.ts
@@ -339,4 +339,194 @@ describe('createAdminCodeEnvironmentHandlers', () => {
expect(response.statusCode).toBe(502);
expect(response.body).toEqual({ error: 'Code API returned an invalid revocation response' });
});
+
+ describe('audit entries', () => {
+ function build(fetchImpl: jest.Mock, recordAuditEntry: jest.Mock) {
+ return createAdminCodeEnvironmentHandlers({
+ getAppConfig: jest.fn().mockResolvedValue(config()),
+ readSecret: jest.fn().mockReturnValue('administrator-bootstrap-token'),
+ fetchImpl,
+ recordAuditEntry,
+ });
+ }
+
+ it('records code_worker.paired without the pairing code', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const fetchImpl = jest.fn().mockResolvedValue(
+ Response.json({
+ protocolVersion: 1,
+ workerId: 'vm-1',
+ code: 'one-time-code-value-that-is-long',
+ expiresAt: '2099-08-30T12:00:00.000Z',
+ }),
+ );
+
+ await build(fetchImpl, recordAuditEntry).createPairing(request(), mockResponse());
+
+ expect(recordAuditEntry.mock.calls.map(([entry]) => entry.outcome ?? 'success')).toEqual([
+ 'pending',
+ 'success',
+ ]);
+ const input = recordAuditEntry.mock.calls[1][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'code_worker.paired',
+ target: { type: 'code_worker', id: 'vm-1', name: 'attached-vm' },
+ }),
+ );
+ expect(input.tenantId).toBeUndefined();
+ expect(input.metadata.boundTenantId).toEqual(expect.any(String));
+ expect(JSON.stringify(recordAuditEntry.mock.calls)).not.toContain(
+ 'one-time-code-value-that-is-long',
+ );
+ expect(JSON.stringify(recordAuditEntry.mock.calls)).not.toContain(
+ 'administrator-bootstrap-token',
+ );
+ });
+
+ it('records code_worker.revoked as pending, then success or a failure entry when it is not confirmed', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const ok = jest.fn().mockResolvedValue(Response.json({ protocolVersion: 1, revoked: true }));
+ const bad = jest
+ .fn()
+ .mockResolvedValue(Response.json({ protocolVersion: 1, revoked: false }));
+
+ await build(ok, recordAuditEntry).revokeWorker(request(), mockResponse());
+ expect(recordAuditEntry).toHaveBeenCalledTimes(2);
+ expect(recordAuditEntry).toHaveBeenNthCalledWith(
+ 1,
+ expect.objectContaining({
+ action: 'code_worker.revoked',
+ outcome: 'pending',
+ target: { type: 'code_worker', id: 'vm-1', name: 'attached-vm' },
+ }),
+ );
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({ action: 'code_worker.revoked', outcome: 'success' }),
+ );
+
+ recordAuditEntry.mockClear();
+ await build(bad, recordAuditEntry).revokeWorker(request(), mockResponse());
+ expect(recordAuditEntry).toHaveBeenCalledTimes(2);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ outcome: 'failure',
+ metadata: { environmentId: 'attached-vm', code: 'invalid_response' },
+ }),
+ );
+ });
+
+ it('records the pairing before the bridge call and a failure entry when no code is minted', async () => {
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ order.push(`audit:${input.outcome ?? 'success'}`);
+ });
+ const fetchImpl = jest.fn().mockImplementation(async () => {
+ order.push('bridge');
+ return new Response('nope', { status: 500 });
+ });
+
+ await build(fetchImpl, recordAuditEntry).createPairing(request(), mockResponse());
+
+ expect(order).toEqual(['audit:pending', 'bridge', 'audit:failure']);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({ metadata: expect.objectContaining({ code: 'bridge_rejected' }) }),
+ );
+ });
+
+ it('sends the revocation without waiting for a slow pending audit write', async () => {
+ const order: string[] = [];
+ let release: () => void = () => undefined;
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ if (input.outcome === 'pending') {
+ await new Promise<void>((resolve) => (release = resolve));
+ }
+ order.push(`audit:${input.outcome ?? 'success'}`);
+ });
+ const fetchImpl = jest.fn().mockImplementation(async () => {
+ order.push('bridge');
+ release();
+ return Response.json({ protocolVersion: 1, revoked: true });
+ });
+
+ await build(fetchImpl, recordAuditEntry).revokeWorker(request(), mockResponse());
+
+ expect(order).toEqual(['bridge', 'audit:pending', 'audit:success']);
+ });
+
+ it('delivers the pairing code before the terminal audit write settles', async () => {
+ let release: () => void = () => undefined;
+ let deliveredAtTerminalWrite: unknown;
+ const response = mockResponse();
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ if (input.outcome === undefined || input.outcome === 'success') {
+ deliveredAtTerminalWrite = response.body;
+ await new Promise<void>((resolve) => (release = resolve));
+ }
+ });
+ const fetchImpl = jest.fn().mockResolvedValue(
+ Response.json({
+ protocolVersion: 1,
+ workerId: 'vm-1',
+ code: 'one-time-code-value-that-is-long',
+ expiresAt: '2099-08-30T12:00:00.000Z',
+ }),
+ );
+
+ const pending = build(fetchImpl, recordAuditEntry).createPairing(request(), response);
+ await new Promise((resolve) => setImmediate(resolve));
+ release();
+ await pending;
+ expect(deliveredAtTerminalWrite).toEqual(expect.objectContaining({ workerId: 'vm-1' }));
+ });
+
+ it('does not pair a worker when the pending audit write fails under fail-closed', async () => {
+ const fetchImpl = jest.fn();
+ const response = mockResponse();
+
+ await createAdminCodeEnvironmentHandlers({
+ getAppConfig: jest.fn().mockResolvedValue(config()),
+ readSecret: jest.fn().mockReturnValue('administrator-bootstrap-token'),
+ fetchImpl,
+ recordAuditEntry: jest.fn().mockRejectedValue(new Error('audit down')),
+ auditFailClosed: true,
+ })
+ .createPairing(request(), response)
+ .catch(() => undefined);
+
+ expect(fetchImpl).not.toHaveBeenCalled();
+ });
+
+ it('never blocks a revocation on an audit outage, even when fail-closed', async () => {
+ const ok = jest.fn().mockResolvedValue(Response.json({ protocolVersion: 1, revoked: true }));
+ const response = mockResponse();
+
+ await createAdminCodeEnvironmentHandlers({
+ getAppConfig: jest.fn().mockResolvedValue(config()),
+ readSecret: jest.fn().mockReturnValue('administrator-bootstrap-token'),
+ fetchImpl: ok,
+ recordAuditEntry: jest.fn().mockRejectedValue(new Error('audit down')),
+ auditFailClosed: true,
+ }).revokeWorker(request(), response);
+
+ expect(response.statusCode).toBe(200);
+ });
+
+ it('does not fail the pairing when the audit write fails (fail-open)', async () => {
+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));
+ const fetchImpl = jest.fn().mockResolvedValue(
+ Response.json({
+ protocolVersion: 1,
+ workerId: 'vm-1',
+ code: 'one-time-code-value-that-is-long',
+ expiresAt: '2099-08-30T12:00:00.000Z',
+ }),
+ );
+ const response = mockResponse();
+
+ await build(fetchImpl, recordAuditEntry).createPairing(request(), response);
+
+ expect(response.statusCode).toBe(200);
+ });
+ });
});
diff --git a/packages/api/src/admin/code.ts b/packages/api/src/admin/code.ts
index a71ac4668a..8ff2577587 100644
--- a/packages/api/src/admin/code.ts
+++ b/packages/api/src/admin/code.ts
@@ -4,8 +4,10 @@ import type { AppConfig } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { GetAppConfigOptions } from '~/app/service';
import type { ServerRequest } from '~/types/http';
+import type { RecordAuditEntry } from './audit';
import { getCodeApiTenantId } from '~/auth/codeapi';
+import { createAdminAuditEmitter } from './audit';
const CODE_BRIDGE_REQUEST_TIMEOUT_MS = 10_000;
@@ -36,6 +38,9 @@ export interface AdminCodeEnvironmentDeps {
resolveTenantId?: (req: ServerRequest) => string;
readSecret?: (name: string) => string | undefined;
fetchImpl?: FetchImpl;
+ /** Optional audit emission for pairing and revocation; fail-open unless `auditFailClosed`. */
+ recordAuditEntry?: RecordAuditEntry;
+ auditFailClosed?: boolean;
}
function environmentId(req: ServerRequest): string {
@@ -95,6 +100,17 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
} {
const fetchImpl = deps.fetchImpl ?? fetch;
const resolveTenantId = deps.resolveTenantId ?? getCodeApiTenantId;
+ const emitAudit = createAdminAuditEmitter({
+ recordAuditEntry: deps.recordAuditEntry,
+ failClosed: deps.auditFailClosed,
+ logPrefix: '[adminCode]',
+ });
+ /** Revoking a worker removes access, and terminal entries record an outcome that already
+ * happened, so an audit outage blocks neither. */
+ const emitRevocationAudit = createAdminAuditEmitter({
+ recordAuditEntry: deps.recordAuditEntry,
+ logPrefix: '[adminCode]',
+ });
const readSecret =
deps.readSecret ??
((name: string) =>
@@ -144,6 +160,28 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
} catch {
return res.status(503).json({ error: 'Code environment tenant context is unavailable' });
}
+ /**
+ * Recorded as `pending` before the bridge mints the one-time code, so no audit latency
+ * sits between minting and delivering it and a rejected pairing is never counted as
+ * granted; `success` is appended once the bridge response validates and `failure`
+ * otherwise. Workers belong to the deployment's YAML environments, so entries go to
+ * the platform chain.
+ */
+ const pairingEvent = {
+ action: 'code_worker.paired' as const,
+ severity: 'warning' as const,
+ target: { type: 'code_worker', id: resolved.pairing.workerId, name: resolved.id },
+ tenantId: undefined,
+ };
+ const pairingMetadata = { environmentId: resolved.id, boundTenantId: tenantId };
+ await emitAudit(req, { ...pairingEvent, outcome: 'pending', metadata: pairingMetadata });
+ const pairingFailed = async (code: string) => {
+ await emitRevocationAudit(req, {
+ ...pairingEvent,
+ outcome: 'failure',
+ metadata: { ...pairingMetadata, code },
+ });
+ };
try {
const response = await fetchImpl(bridgeUrl(resolved.environment, '/bridge/pairings'), {
method: 'POST',
@@ -162,6 +200,7 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
signal: AbortSignal.timeout(CODE_BRIDGE_REQUEST_TIMEOUT_MS),
});
if (!response.ok) {
+ await pairingFailed('bridge_rejected');
return res.status(502).json({
error: 'Code API rejected the pairing request',
upstreamStatus: response.status,
@@ -169,16 +208,21 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
}
const payload = (await response.json()) as unknown;
if (!validPairingResponse(payload, resolved.pairing.workerId)) {
+ await pairingFailed('invalid_response');
return res.status(502).json({ error: 'Code API returned an invalid pairing response' });
}
- return res.status(200).json({
+ /** The code is delivered first: it expires, so audit latency must not sit in front of it. */
+ res.status(200).json({
environmentId: resolved.id,
workerId: payload.workerId,
code: payload.code,
expiresAt: payload.expiresAt,
});
+ await emitRevocationAudit(req, { ...pairingEvent, metadata: pairingMetadata });
+ return res;
} catch (error) {
const timedOut = error instanceof Error && error.name === 'TimeoutError';
+ await pairingFailed(timedOut ? 'timeout' : 'request_failed');
return res.status(timedOut ? 504 : 502).json({
error: timedOut ? 'Code API pairing request timed out' : 'Code API pairing request failed',
});
@@ -188,6 +232,32 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
async function revokeWorker(req: ServerRequest, res: Response): Promise<Response> {
const resolved = await resolve(req, res);
if ('statusCode' in resolved) return resolved;
+ /**
+ * Recorded as `pending` without being awaited, so audit latency never delays the
+ * revocation; later entries wait for it to keep the chain ordered. `success` is
+ * appended once the bridge acknowledges and `failure` otherwise.
+ */
+ const revokeEvent = {
+ action: 'code_worker.revoked' as const,
+ severity: 'warning' as const,
+ target: { type: 'code_worker', id: resolved.pairing.workerId, name: resolved.id },
+ tenantId: undefined,
+ };
+ const revokeMetadata = { environmentId: resolved.id };
+ const attempt = emitRevocationAudit(req, {
+ ...revokeEvent,
+ outcome: 'pending',
+ metadata: revokeMetadata,
+ });
+ const revokeSettled = async (outcome: 'success' | 'failure', code?: string) => {
+ await attempt;
+ await emitRevocationAudit(req, {
+ ...revokeEvent,
+ outcome,
+ metadata: code ? { ...revokeMetadata, code } : revokeMetadata,
+ });
+ };
+ const revokeFailed = (code: string) => revokeSettled('failure', code);
try {
const workerId = encodeURIComponent(resolved.pairing.workerId);
const response = await fetchImpl(
@@ -204,6 +274,7 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
},
);
if (!response.ok) {
+ await revokeFailed('bridge_rejected');
return res.status(502).json({
error: 'Code API rejected the revocation request',
upstreamStatus: response.status,
@@ -211,15 +282,19 @@ export function createAdminCodeEnvironmentHandlers(deps: AdminCodeEnvironmentDep
}
const payload = (await response.json()) as unknown;
if (!validRevocationResponse(payload)) {
+ await revokeFailed('invalid_response');
return res.status(502).json({ error: 'Code API returned an invalid revocation response' });
}
- return res.status(200).json({
+ res.status(200).json({
environmentId: resolved.id,
workerId: resolved.pairing.workerId,
revoked: true,
});
+ await revokeSettled('success');
+ return res;
} catch (error) {
const timedOut = error instanceof Error && error.name === 'TimeoutError';
+ await revokeFailed(timedOut ? 'timeout' : 'request_failed');
return res.status(timedOut ? 504 : 502).json({
error: timedOut
? 'Code API revocation request timed out'
diff --git a/packages/api/src/admin/context.spec.ts b/packages/api/src/admin/context.spec.ts
new file mode 100644
index 0000000000..5da3586057
--- /dev/null
+++ b/packages/api/src/admin/context.spec.ts
@@ -0,0 +1,19 @@
+import type { ServerRequest } from '~/types/http';
+import { buildAuditContext } from './context';
+
+describe('buildAuditContext', () => {
+ it('prefers the server-assigned request id over client headers', () => {
+ const req = {
+ requestId: 'server-id',
+ headers: { 'x-request-id': 'client-id' },
+ } as unknown as ServerRequest;
+
+ expect(buildAuditContext(req).requestId).toBe('server-id');
+ });
+
+ it('falls back to the correlation headers', () => {
+ const req = { headers: { 'x-correlation-id': 'client-id' } } as unknown as ServerRequest;
+
+ expect(buildAuditContext(req).requestId).toBe('client-id');
+ });
+});
diff --git a/packages/api/src/admin/context.ts b/packages/api/src/admin/context.ts
index 2ab6710753..0dfe33ffb9 100644
--- a/packages/api/src/admin/context.ts
+++ b/packages/api/src/admin/context.ts
@@ -8,7 +8,7 @@ function firstHeaderValue(value: string | string[] | undefined): string | undefi
}
/** Extracts forensic request context (IP, user agent, correlation id) for an
- * audit record. Fields are undefined when the data isn't available. */
+ * audit record. The server-assigned request id wins over client-supplied headers. Fields are undefined when the data isn't available. */
export function buildAuditContext(req: ServerRequest): AuditContext {
const headers = req.headers ?? {};
const forwarded = firstHeaderValue(headers['x-forwarded-for']);
@@ -16,6 +16,8 @@ export function buildAuditContext(req: ServerRequest): AuditContext {
return {
ip: req.ip || forwardedIp || req.socket?.remoteAddress || undefined,
userAgent: firstHeaderValue(headers['user-agent']),
- requestId: firstHeaderValue(headers['x-request-id'] ?? headers['x-correlation-id']),
+ requestId:
+ (req as { requestId?: string }).requestId ??
+ firstHeaderValue(headers['x-request-id'] ?? headers['x-correlation-id']),
};
}
diff --git a/packages/api/src/admin/groups.spec.ts b/packages/api/src/admin/groups.spec.ts
index cb395b1a7d..c004e9f4f2 100644
--- a/packages/api/src/admin/groups.spec.ts
+++ b/packages/api/src/admin/groups.spec.ts
@@ -812,7 +812,10 @@ describe('createAdminGroupsHandlers', () => {
describe('deleteGroup', () => {
it('deletes group and returns 200 with id', async () => {
- const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(mockGroup()) });
+ const deps = createDeps({
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
+ deleteGroup: jest.fn().mockResolvedValue(mockGroup()),
+ });
const handlers = createAdminGroupsHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { id: validId } });
@@ -834,8 +837,8 @@ describe('createAdminGroupsHandlers', () => {
expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });
});
- it('returns 404 when deleteGroup returns null', async () => {
- const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(null) });
+ it('returns 404 and cleans nothing when the group is missing', async () => {
+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(null) });
const handlers = createAdminGroupsHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { id: validId } });
@@ -844,10 +847,12 @@ describe('createAdminGroupsHandlers', () => {
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Group not found' });
expect(deps.deleteConfig).not.toHaveBeenCalled();
+ expect(deps.deleteGroup).not.toHaveBeenCalled();
});
it('returns 500 on error', async () => {
const deps = createDeps({
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
deleteGroup: jest.fn().mockRejectedValue(new Error('db down')),
});
const handlers = createAdminGroupsHandlers(deps);
@@ -859,9 +864,9 @@ describe('createAdminGroupsHandlers', () => {
expect(json).toHaveBeenCalledWith({ error: 'Failed to delete group' });
});
- it('returns 200 even when cascade cleanup partially fails', async () => {
+ it('returns 500 and keeps the group when cascade cleanup fails', async () => {
const deps = createDeps({
- deleteGroup: jest.fn().mockResolvedValue(mockGroup()),
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
deleteAclEntries: jest.fn().mockRejectedValue(new Error('cleanup failed')),
});
const handlers = createAdminGroupsHandlers(deps);
@@ -869,17 +874,358 @@ describe('createAdminGroupsHandlers', () => {
await handlers.deleteGroup(req, res);
- expect(status).toHaveBeenCalledWith(200);
- expect(json).toHaveBeenCalledWith({ success: true, id: validId });
- expect(deps.deleteConfig).toHaveBeenCalledWith(PrincipalType.GROUP, validId);
- expect(deps.deleteAclEntries).toHaveBeenCalledWith({
- principalType: PrincipalType.GROUP,
- principalId: new Types.ObjectId(validId),
+ expect(status).toHaveBeenCalledWith(500);
+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'GROUP_CLEANUP_FAILED' }));
+ expect(deps.deleteGroup).not.toHaveBeenCalled();
+ });
+
+ describe('compensation and audit', () => {
+ const withUser = <T extends { req: ServerRequest }>(reqRes: T): T => {
+ (reqRes.req as unknown as { user: Partial<IUser> }).user = {
+ _id: new Types.ObjectId(),
+ name: 'Admin',
+ };
+ return reqRes;
+ };
+ const config = { principalType: 'group', principalId: 'p', overrides: {} };
+
+ function compensationDeps(overrides: Partial<AdminGroupsDeps> = {}) {
+ return createDeps({
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
+ deleteConfig: jest.fn().mockResolvedValue(config),
+ restoreConfig: jest.fn().mockResolvedValue(true),
+ ...overrides,
+ });
+ }
+
+ it('restores the config when the ACL removal fails after it', async () => {
+ const deps = compensationDeps({
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status, json } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(json).toHaveBeenCalledWith(
+ expect.objectContaining({ code: 'GROUP_CLEANUP_FAILED' }),
+ );
+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);
+ expect(deps.deleteGroup).not.toHaveBeenCalled();
+ });
+
+ it('does not restore the config when a concurrent delete already removed the group', async () => {
+ const deps = compensationDeps({
+ findGroupById: jest.fn().mockResolvedValueOnce(mockGroup()).mockResolvedValueOnce(null),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.restoreConfig).not.toHaveBeenCalled();
+ });
+
+ it('restores the config when the group state recheck fails', async () => {
+ const deps = compensationDeps({
+ findGroupById: jest
+ .fn()
+ .mockResolvedValueOnce(mockGroup())
+ .mockRejectedValueOnce(new Error('db down')),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);
+ });
+
+ it('restores the config when the delete fails and the group state cannot be read', async () => {
+ const deps = compensationDeps({
+ findGroupById: jest
+ .fn()
+ .mockResolvedValueOnce(mockGroup())
+ .mockRejectedValueOnce(new Error('db down')),
+ deleteGroup: jest.fn().mockRejectedValue(new Error('delete failed')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);
+ });
+
+ it('restores the config from a pre-delete snapshot when the removal rejects after committing', async () => {
+ const deps = compensationDeps({
+ findConfigByPrincipal: jest.fn().mockResolvedValue(config),
+ deleteConfig: jest.fn().mockRejectedValue(new Error('ack lost')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.findConfigByPrincipal).toHaveBeenCalledWith('group', validId, {
+ includeInactive: true,
+ });
+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);
+ expect(deps.deleteGroup).not.toHaveBeenCalled();
+ });
+
+ it('completes the deletion when the config restore itself fails', async () => {
+ const deps = compensationDeps({
+ restoreConfig: jest.fn().mockRejectedValue(new Error('restore down')),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(deps.deleteGroup).toHaveBeenCalledWith(validId);
+ expect(deps.deleteAclEntries).toHaveBeenCalledTimes(2);
+ expect(status).toHaveBeenCalledWith(200);
+ });
+
+ it('treats a compensating deletion that throws after committing as completed', async () => {
+ const group = mockGroup();
+ const deps = compensationDeps({
+ restoreConfig: jest.fn().mockRejectedValue(new Error('restore down')),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ findGroupById: jest
+ .fn()
+ .mockResolvedValueOnce(group)
+ .mockResolvedValueOnce(group)
+ .mockResolvedValue(null),
+ deleteGroup: jest.fn().mockRejectedValue(new Error('cache invalidation failed')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ });
+
+ it('reports not found when a concurrent delete won the race during the compensating deletion', async () => {
+ const deps = compensationDeps({
+ restoreConfig: jest.fn().mockRejectedValue(new Error('restore down')),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ deleteGroup: jest.fn().mockResolvedValue(null),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(404);
+ });
+
+ it('reports GROUP_RESTORE_FAILED when neither the restore nor the deletion succeeds', async () => {
+ const deps = compensationDeps({
+ restoreConfig: jest.fn().mockRejectedValue(new Error('restore down')),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ deleteGroup: jest.fn().mockRejectedValue(new Error('delete down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status, json } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(json).toHaveBeenCalledWith(
+ expect.objectContaining({ code: 'GROUP_RESTORE_FAILED' }),
+ );
+ });
+
+ it('restores the config but never the ACL entries when the group delete fails', async () => {
+ const deps = compensationDeps({
+ deleteGroup: jest.fn().mockRejectedValue(new Error('db down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.deleteAclEntries).toHaveBeenCalled();
+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);
+ });
+
+ it('leaves the removed ACL entries removed when the config removal fails', async () => {
+ const deps = compensationDeps({
+ deleteConfig: jest.fn().mockRejectedValue(new Error('config down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(500);
+ expect(deps.restoreConfig).not.toHaveBeenCalled();
+ expect(deps.deleteGroup).not.toHaveBeenCalled();
+ });
+
+ it('does not restore dependents of a group that is already gone', async () => {
+ const deps = compensationDeps({
+ findGroupById: jest.fn().mockResolvedValueOnce(mockGroup()).mockResolvedValue(null),
+ deleteGroup: jest.fn().mockRejectedValue(new Error('db down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(deps.restoreConfig).not.toHaveBeenCalled();
+ });
+
+ it('records a pending group.deleted before any removal and a failure entry after a failed cleanup', async () => {
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ order.push(`audit:${input.outcome ?? 'success'}`);
+ });
+ const deps = compensationDeps({
+ recordAuditEntry,
+ deleteConfig: jest.fn().mockImplementation(async () => {
+ order.push('config');
+ return config;
+ }),
+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl down')),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res } = withUser(createReqRes({ params: { id: validId } }));
+
+ await handlers.deleteGroup(req, res);
+
+ expect(order).toEqual(['audit:pending', 'config', 'audit:failure']);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ action: 'group.deleted',
+ outcome: 'failure',
+ metadata: { code: 'GROUP_CLEANUP_FAILED' },
+ }),
+ );
+ });
+
+ it('appends a not_found failure entry when the request loses the race', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const deps = compensationDeps({
+ recordAuditEntry,
+ deleteGroup: jest.fn().mockResolvedValue(null),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(404);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({ outcome: 'failure', metadata: { code: 'not_found' } }),
+ );
+ expect(deps.restoreConfig).not.toHaveBeenCalled();
+ });
+
+ it('does not wait for a slow pending audit write before removing dependents', async () => {
+ let releaseAudit: () => void = () => undefined;
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ if (input.outcome === 'pending') {
+ await new Promise<void>((resolve) => (releaseAudit = resolve));
+ }
+ order.push(`audit:${input.outcome ?? 'success'}`);
+ });
+ const deps = compensationDeps({
+ recordAuditEntry,
+ deleteGroup: jest.fn().mockImplementation(async () => {
+ order.push('group');
+ releaseAudit();
+ return mockGroup();
+ }),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(order).toEqual(['group', 'audit:pending', 'audit:success']);
+ });
+
+ it('still appends the terminal outcome when member-removal audits fail under fail-closed', async () => {
+ const recordAuditEntry = jest.fn().mockImplementation(async (input) => {
+ if (input.action === 'group.member_removed') {
+ throw new Error('audit down');
+ }
+ });
+ const group = mockGroup({ memberIds: ['m1'] });
+ const deps = compensationDeps({
+ recordAuditEntry,
+ auditFailClosed: true,
+ findGroupById: jest.fn().mockResolvedValue(group),
+ deleteGroup: jest.fn().mockResolvedValue(group),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
+ expect.objectContaining({ action: 'group.deleted', outcome: 'success' }),
+ );
+ });
+
+ it('never blocks the delete on an audit outage, even when fail-closed', async () => {
+ const deps = compensationDeps({
+ recordAuditEntry: jest.fn().mockRejectedValue(new Error('audit down')),
+ auditFailClosed: true,
+ deleteGroup: jest.fn().mockResolvedValue(mockGroup()),
+ });
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));
+
+ await handlers.deleteGroup(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(deps.deleteGroup).toHaveBeenCalled();
+ });
+ });
+
+ it('removes dependents before the group', async () => {
+ const order: string[] = [];
+ const deps = createDeps({
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
+ deleteConfig: jest.fn().mockImplementation(async () => void order.push('config')),
+ deleteAclEntries: jest.fn().mockImplementation(async () => void order.push('acl')),
+ deleteGroup: jest.fn().mockImplementation(async () => {
+ order.push('group');
+ return mockGroup();
+ }),
});
+ const handlers = createAdminGroupsHandlers(deps);
+ const { req, res } = createReqRes({ params: { id: validId } });
+
+ await handlers.deleteGroup(req, res);
+
+ expect(order[order.length - 1]).toBe('group');
+ expect(order).toHaveLength(3);
});
it('cleans up Config and AclEntry on group delete', async () => {
- const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(mockGroup()) });
+ const deps = createDeps({
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
+ deleteGroup: jest.fn().mockResolvedValue(mockGroup()),
+ });
const handlers = createAdminGroupsHandlers(deps);
const { req, res, status } = createReqRes({ params: { id: validId } });
@@ -1521,16 +1867,20 @@ describe('createAdminGroupsHandlers', () => {
it('records group.deleted', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
- const deps = createDeps({ recordAuditEntry });
+ const deps = createDeps({
+ recordAuditEntry,
+ findGroupById: jest.fn().mockResolvedValue(mockGroup()),
+ });
const handlers = createAdminGroupsHandlers(deps);
const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));
await handlers.deleteGroup(req, res);
expect(status).toHaveBeenCalledWith(200);
- expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect(recordAuditEntry).toHaveBeenLastCalledWith(
expect.objectContaining({
action: 'group.deleted',
+ outcome: 'success',
target: { type: 'group', id: validId, name: 'Test Group' },
}),
);
@@ -1540,6 +1890,7 @@ describe('createAdminGroupsHandlers', () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const deps = createDeps({
recordAuditEntry,
+ findGroupById: jest.fn().mockResolvedValue(mockGroup({ memberIds: ['m1', 'm2'] })),
deleteGroup: jest.fn().mockResolvedValue(mockGroup({ memberIds: ['m1', 'm2'] })),
});
const handlers = createAdminGroupsHandlers(deps);
@@ -1629,7 +1980,7 @@ describe('createAdminGroupsHandlers', () => {
it('does not record when the group is missing', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const deps = createDeps({
- deleteGroup: jest.fn().mockResolvedValue(null),
+ findGroupById: jest.fn().mockResolvedValue(null),
recordAuditEntry,
});
const handlers = createAdminGroupsHandlers(deps);
diff --git a/packages/api/src/admin/groups.ts b/packages/api/src/admin/groups.ts
index 80a0bcf115..0697594079 100644
--- a/packages/api/src/admin/groups.ts
+++ b/packages/api/src/admin/groups.ts
@@ -15,6 +15,7 @@ import type { ValidationError } from '~/types/error';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import { getSafeErrorMetadata } from '~/utils/errors';
+import { cascadeStep, runCascade } from './cascade';
import { createAdminAuditEmitter } from './audit';
import { parsePagination } from './pagination';
@@ -88,6 +89,16 @@ export interface AdminGroupsDeps {
principalType: PrincipalType;
principalId: string | Types.ObjectId;
}) => Promise<DeleteResult>;
+ /** Re-creates a removed config override in full, only if none exists, when the group
+ * deletion cannot finish. ACL entries are never restored. Resolves to whether it inserted. */
+ restoreConfig?: (snapshot: Record<string, unknown>) => Promise<boolean>;
+ /** Reads the override before it is removed, so a rejected removal whose commit was
+ * lost in transit can still be put back. */
+ findConfigByPrincipal?: (
+ principalType: PrincipalType,
+ principalId: string,
+ options?: { includeInactive?: boolean },
+ ) => Promise<object | null>;
/** Optional audit emission for group mutations; fail-open unless `auditFailClosed`. */
recordAuditEntry?: RecordAuditEntry;
/** When true, a failed audit write surfaces as a 5xx after the mutation has
@@ -122,10 +133,16 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {
findUsers,
deleteConfig,
deleteAclEntries,
+ restoreConfig,
+ findConfigByPrincipal,
recordAuditEntry,
auditFailClosed,
} = deps;
+ const emitRevocationAudit = createAdminAuditEmitter({
+ recordAuditEntry,
+ logPrefix: '[adminGroups]',
+ });
const emitAudit = createAdminAuditEmitter({
recordAuditEntry,
failClosed: auditFailClosed,
@@ -355,44 +372,231 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {
if (!isValidObjectIdString(id)) {
return res.status(400).json({ error: 'Invalid group ID format' });
}
- const deleted = await deleteGroup(id);
- if (!deleted) {
+ const existing = await findGroupById(id);
+ if (!existing) {
return res.status(404).json({ error: 'Group not found' });
}
+ const target = groupTarget(existing, id);
/**
+ * The attempt is recorded as `pending` before any removal so a crash mid-cascade
+ * still leaves a trail, but the write is started without being awaited: deleting a
+ * group revokes access, so audit latency must not delay the cleanup. Every
+ * later entry waits for it to settle to keep the chain ordered.
+ * A `success` or `failure` entry is appended once the outcome is known.
+ */
+ const attempt = emitRevocationAudit(req, {
+ action: 'group.deleted',
+ outcome: 'pending',
+ severity: 'warning',
+ target,
+ });
+ const record = async (outcome: 'success' | 'failure', code?: string) => {
+ await attempt;
+ return emitRevocationAudit(req, {
+ action: 'group.deleted',
+ outcome,
+ severity: 'warning',
+ target,
+ ...(code ? { metadata: { code } } : {}),
+ });
+ };
+ const recordFailure = (code: string) => record('failure', code);
+ /**
+ * Config overrides and ACL entries are keyed by group id, so they are
+ * removed before the group itself: if any removal fails the group stays
+ * and the admin can retry, instead of leaving orphaned entries that a later
+ * principal could inherit. Only the config override is put back (insert-only,
+ * so one written since is kept): removing it can widen what members may do,
+ * while ACL entries stay removed because that only narrows access and
+ * re-inserting them could resurrect a grant revoked in the meantime.
* deleteAclEntries is a raw deleteMany wrapper with no type casting.
* grantPermission stores group principalId as ObjectId, so we must
* cast here. deleteConfig normalizes internally.
*/
- const cleanupResults = await Promise.allSettled([
- deleteConfig(PrincipalType.GROUP, id),
- deleteAclEntries({
+ let restoreFailed = false;
+ const cascade = await runCascade(
+ [
+ cascadeStep(
+ 'config',
+ () => deleteConfig(PrincipalType.GROUP, id),
+ restoreConfig
+ ? async (config) => {
+ if (!config) {
+ return;
+ }
+ const snapshot = (config as { toObject?: () => unknown }).toObject?.() ?? config;
+ let restored: boolean;
+ try {
+ restored = await restoreConfig(snapshot as Record<string, unknown>);
+ restoreFailed = false;
+ } catch (error) {
+ restoreFailed = true;
+ throw error;
+ }
+ if (!restored) {
+ logger.warn('[adminGroups] config restore skipped, override exists:', id);
+ }
+ }
+ : undefined,
+ findConfigByPrincipal
+ ? () => findConfigByPrincipal(PrincipalType.GROUP, id, { includeInactive: true })
+ : undefined,
+ ),
+ cascadeStep('acl', () =>
+ deleteAclEntries({
+ principalType: PrincipalType.GROUP,
+ principalId: new Types.ObjectId(id),
+ }),
+ ),
+ ],
+ '[adminGroups]',
+ );
+ /**
+ * Puts the config override back. When that restore itself fails the group would live on
+ * without its restriction, so the deletion is completed instead of retaining it.
+ */
+ const compensate = async (): Promise<'restored' | 'stuck' | 'missing' | IGroup> => {
+ await cascade.compensate();
+ if (!restoreFailed) {
+ return 'restored';
+ }
+ logger.error('[adminGroups] config restore failed, completing the deletion:', id);
+ let removed: IGroup | null = null;
+ try {
+ removed = await deleteGroup(id);
+ if (!removed) {
+ /** Another request deleted the group first; this one removed nothing. */
+ return 'missing';
+ }
+ } catch (error) {
+ /** The delete may have committed before it threw (post-delete cache work); a confirmed
+ * absence is a completed deletion. */
+ const absent = await findGroupById(id).then(
+ (group) => group == null,
+ () => false,
+ );
+ if (!absent) {
+ logger.error(
+ '[adminGroups] group left without its config override:',
+ id,
+ getSafeErrorMetadata(error),
+ );
+ return 'stuck';
+ }
+ removed = existing;
+ }
+ /** The group is gone for good, so a leftover ACL entry is orphaned: retry its removal once. */
+ await deleteAclEntries({
principalType: PrincipalType.GROUP,
principalId: new Types.ObjectId(id),
- }),
- ]);
- for (const result of cleanupResults) {
- if (result.status === 'rejected') {
- logger.error('[adminGroups] cascade cleanup step failed for group:', id, result.reason);
- }
- }
+ }).catch((aclError) =>
+ logger.error(
+ '[adminGroups] acl cleanup retry failed after group deletion:',
+ getSafeErrorMetadata(aclError),
+ ),
+ );
+ return removed;
+ };
/** Every member loses group-scoped access, so the affected accounts are recorded (chunked). */
- const revoked = [...new Set(deleted.memberIds ?? [])];
- for (let i = 0; i < revoked.length; i += AUDIT_MEMBER_CHUNK) {
- const chunk = revoked.slice(i, i + AUDIT_MEMBER_CHUNK);
- await emitAudit(req, {
- action: 'group.member_removed',
- severity: 'warning',
- target: groupTarget(deleted, id),
- metadata: { userIds: chunk.join(','), count: chunk.length, cause: 'group_deleted' },
+ const recordMemberRemovals = async (group: IGroup) => {
+ /** Keeps the chain causal: the pending attempt precedes the member entries. */
+ await attempt;
+ const revoked = [...new Set(group.memberIds ?? [])];
+ for (let i = 0; i < revoked.length; i += AUDIT_MEMBER_CHUNK) {
+ const chunk = revoked.slice(i, i + AUDIT_MEMBER_CHUNK);
+ await emitRevocationAudit(req, {
+ action: 'group.member_removed',
+ severity: 'warning',
+ target: groupTarget(group, id),
+ metadata: { userIds: chunk.join(','), count: chunk.length, cause: 'group_deleted' },
+ });
+ }
+ };
+ const compensatedResponse = async (outcome: 'stuck' | 'missing' | IGroup) => {
+ if (outcome === 'missing') {
+ await recordFailure('not_found');
+ return res.status(404).json({ error: 'Group not found' });
+ }
+ if (outcome !== 'stuck') {
+ await recordMemberRemovals(outcome);
+ res.status(200).json({ success: true, id });
+ await record('success');
+ return res;
+ }
+ await recordFailure('GROUP_RESTORE_FAILED');
+ return res.status(500).json({
+ error: 'Failed to delete group and its config override could not be restored',
+ code: 'GROUP_RESTORE_FAILED',
});
+ };
+ const cleanupFailedResponse = async () => {
+ await recordFailure('GROUP_CLEANUP_FAILED');
+ return res.status(500).json({
+ error: 'Failed to remove the group permissions and config; the group was not deleted',
+ code: 'GROUP_CLEANUP_FAILED',
+ });
+ };
+
+ if (cascade.failed.length > 0) {
+ /** A concurrent delete may have removed the group meanwhile; restoring its config would
+ * orphan it. When the lookup itself fails the group state is unknown, and putting the
+ * override back is the safe side: a leftover override only restricts, a lost one widens. */
+ const gone = await findGroupById(id).then(
+ (group) => group == null,
+ () => false,
+ );
+ if (!gone) {
+ const outcome = await compensate();
+ if (outcome !== 'restored') {
+ return compensatedResponse(outcome);
+ }
+ }
+ return cleanupFailedResponse();
+ }
+
+ let deleted: IGroup | null;
+ try {
+ deleted = await deleteGroup(id);
+ } catch (error) {
+ logger.error(
+ '[adminGroups] deleteGroup failed after cascade cleanup:',
+ getSafeErrorMetadata(error),
+ );
+ /** The delete may have committed before it threw. Restoring dependents for a
+ * group that is gone would orphan them. */
+ const lookup = await findGroupById(id).then(
+ (group) => ({ known: true, group }),
+ () => ({ known: false, group: null }),
+ );
+ if (lookup.known && lookup.group) {
+ const outcome = await compensate();
+ if (outcome !== 'restored') {
+ return compensatedResponse(outcome);
+ }
+ await recordFailure('GROUP_CLEANUP_FAILED');
+ return res.status(500).json({ error: 'Failed to delete group' });
+ }
+ if (!lookup.known) {
+ /** Unknown state favors the restriction: a leftover override narrows access, a lost one widens it. */
+ const outcome = await compensate();
+ if (outcome !== 'restored') {
+ return compensatedResponse(outcome);
+ }
+ logger.error('[adminGroups] group state unverifiable after delete failure:', id);
+ await recordFailure('GROUP_STATE_UNVERIFIABLE');
+ return res.status(500).json({ error: 'Failed to delete group' });
+ }
+ /** Confirmed absent: the deletion did commit. */
+ deleted = existing;
}
- await emitAudit(req, {
- action: 'group.deleted',
- severity: 'warning',
- target: groupTarget(deleted, id),
- });
- return res.status(200).json({ success: true, id });
+ if (!deleted) {
+ await recordFailure('not_found');
+ return res.status(404).json({ error: 'Group not found' });
+ }
+ await recordMemberRemovals(deleted);
+ res.status(200).json({ success: true, id });
+ await record('success');
+ return res;
} catch (error) {
logger.error('[adminGroups] deleteGroup error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to delete group' });
diff --git a/packages/api/src/admin/langfuse.handler.spec.ts b/packages/api/src/admin/langfuse.handler.spec.ts
index f74df7907b..9327121fbc 100644
--- a/packages/api/src/admin/langfuse.handler.spec.ts
+++ b/packages/api/src/admin/langfuse.handler.spec.ts
@@ -547,6 +547,69 @@ describe('createAdminLangfuseHandlers', () => {
expect(JSON.stringify(deps.recordConnectionUpdate.mock.calls)).not.toContain('pk-lf-1');
});
+ it('records langfuse.updated with the changes and never the keys', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const { handlers } = createHandlers({ recordAuditEntry });
+ const res = mockRes();
+
+ await handlers.updateConnection(
+ mockReq({
+ body: {
+ enabled: true,
+ destination: 'eu',
+ publicKey: 'pk-lf-1',
+ secretKey: 'sk-lf-secret',
+ },
+ }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ const input = recordAuditEntry.mock.calls[0][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'langfuse.updated',
+ target: { type: 'langfuse', id: 'connection' },
+ metadata: { changes: 'created', enabled: true, destination: 'eu' },
+ }),
+ );
+ expect(JSON.stringify(input)).not.toContain('sk-lf-secret');
+ expect(JSON.stringify(input)).not.toContain('pk-lf-1');
+ });
+
+ it('starts cache invalidation before waiting on the audit write', async () => {
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async () => {
+ order.push('audit');
+ });
+ const invalidateConfigCaches = jest.fn().mockImplementation(async () => {
+ order.push('invalidate');
+ });
+ const { handlers } = createHandlers({ recordAuditEntry, invalidateConfigCaches });
+
+ await handlers.updateConnection(
+ mockReq({
+ body: { enabled: true, destination: 'eu', publicKey: 'pk-lf-1', secretKey: 'sk-lf-2' },
+ }),
+ mockRes(),
+ );
+
+ expect(order[0]).toBe('invalidate');
+ expect(order).toContain('audit');
+ });
+
+ it('records nothing when the update is rejected', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const { handlers } = createHandlers({ recordAuditEntry });
+ const res = mockRes();
+
+ await handlers.updateConnection(mockReq({ body: { enabled: true } }), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+ });
+
it('requires a new secret when connection fields change', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest
@@ -771,6 +834,92 @@ describe('createAdminLangfuseHandlers', () => {
});
});
+ describe('updateConnection activation failure', () => {
+ it('still audits and invalidates caches when activation fails after the patch committed', async () => {
+ const inactive = {
+ ...baseConfigDoc({
+ enabled: true,
+ destination: 'eu',
+ publicKey: 'pk-lf-1',
+ secretKey: encryptV3('sk-lf-secret'),
+ }),
+ isActive: false,
+ };
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);
+ const { handlers } = createHandlers({
+ findConfigByPrincipal: jest.fn().mockResolvedValue(inactive),
+ patchConfigFields: jest.fn().mockResolvedValue(inactive),
+ toggleConfigActive: jest.fn().mockRejectedValue(new Error('toggle failed')),
+ recordAuditEntry,
+ invalidateConfigCaches,
+ });
+ const res = mockRes();
+
+ await handlers.updateConnection(
+ mockReq({
+ body: {
+ enabled: true,
+ destination: 'eu',
+ publicKey: 'pk-lf-1',
+ secretKey: 'sk-lf-secret',
+ },
+ }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(500);
+ expect(invalidateConfigCaches).toHaveBeenCalled();
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'langfuse.updated',
+ metadata: expect.objectContaining({ enabled: false, activation: 'failed' }),
+ }),
+ );
+ });
+ });
+
+ describe('updateConnection activation returning null', () => {
+ it('treats a vanished config as a failed activation', async () => {
+ const inactive = {
+ ...baseConfigDoc({
+ enabled: true,
+ destination: 'eu',
+ publicKey: 'pk-lf-1',
+ secretKey: encryptV3('sk-lf-secret'),
+ }),
+ isActive: false,
+ };
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const { handlers } = createHandlers({
+ findConfigByPrincipal: jest.fn().mockResolvedValue(inactive),
+ patchConfigFields: jest.fn().mockResolvedValue(inactive),
+ toggleConfigActive: jest.fn().mockResolvedValue(null),
+ recordAuditEntry,
+ });
+ const res = mockRes();
+
+ await handlers.updateConnection(
+ mockReq({
+ body: {
+ enabled: true,
+ destination: 'eu',
+ publicKey: 'pk-lf-1',
+ secretKey: 'sk-lf-secret',
+ },
+ }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(500);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({ enabled: false, activation: 'failed' }),
+ }),
+ );
+ });
+ });
+
describe('testConnection', () => {
it('requires destination and publicKey', async () => {
const { handlers } = createHandlers();
diff --git a/packages/api/src/admin/langfuse.ts b/packages/api/src/admin/langfuse.ts
index 351343ea9f..ea6721cb1f 100644
--- a/packages/api/src/admin/langfuse.ts
+++ b/packages/api/src/admin/langfuse.ts
@@ -14,6 +14,7 @@ import type { Types, ClientSession } from 'mongoose';
import type { Response } from 'express';
import type { LangfuseTenantDestination } from '~/langfuse/tenantDestinations';
import type { ServerRequest } from '~/types/http';
+import type { RecordAuditEntry } from './audit';
import {
getLangfuseTenantDestinations,
resolveLangfuseTenantDestination,
@@ -23,6 +24,7 @@ import { decryptConfigSecret, encryptConfigSecretFields } from './secrets';
import { scopeHeadersToDestination } from '~/langfuse/destinations';
import { isLangfuseConnectionAvailable } from '~/langfuse/policy';
import { resolveLangfuseSession } from '~/langfuse/session';
+import { createAdminAuditEmitter } from './audit';
import { mergeHeaders } from '~/utils/headers';
const DEFAULT_PRIORITY = 10;
@@ -46,7 +48,7 @@ export interface LangfuseConnectionEvent {
destination?: string;
change: LangfuseConnectionChange;
changes: LangfuseConnectionChange[];
- verification_result: 'skipped' | 'success';
+ verification_result: 'skipped' | 'success' | 'failed';
}
export interface AdminLangfuseDeps {
@@ -73,6 +75,9 @@ export interface AdminLangfuseDeps {
getMessages: MessageMethods['getMessages'];
invalidateConfigCaches?: (tenantId?: string) => Promise<void>;
recordConnectionUpdate?: (event: LangfuseConnectionEvent) => void;
+ /** Optional audit emission for connection updates; fail-open unless `auditFailClosed`. */
+ recordAuditEntry?: RecordAuditEntry;
+ auditFailClosed?: boolean;
}
function getTenantId(req: ServerRequest): string | undefined {
@@ -294,7 +299,14 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {
invalidateConfigCaches,
recordConnectionUpdate = (event) =>
logger.info({ message: '[adminLangfuse] Connection updated', ...event }),
+ recordAuditEntry,
+ auditFailClosed,
} = deps;
+ const emitAudit = createAdminAuditEmitter({
+ recordAuditEntry,
+ failClosed: auditFailClosed,
+ logPrefix: '[adminLangfuse]',
+ });
function findBaseConfig(options?: { includeInactive?: boolean }): Promise<IConfig | null> {
return options
@@ -443,8 +455,25 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {
encryptConfigSecretFields(fields),
existing?.priority ?? DEFAULT_PRIORITY,
);
+ /** The patch has committed by now, so a failed activation must not skip the cache
+ * invalidation or the audit entry; it is rethrown once both have started. */
+ let activationError: unknown;
if (updated?.isActive === false) {
- updated = await toggleConfigActive(PrincipalType.ROLE, BASE_CONFIG_PRINCIPAL_ID, true);
+ try {
+ const activated = await toggleConfigActive(
+ PrincipalType.ROLE,
+ BASE_CONFIG_PRINCIPAL_ID,
+ true,
+ );
+ if (activated) {
+ updated = activated;
+ } else {
+ /** A null result means the config vanished meanwhile (a concurrent delete). */
+ activationError = new Error('Langfuse base config no longer exists');
+ }
+ } catch (error) {
+ activationError = error;
+ }
}
const status = buildStatus(updated ?? existing);
@@ -455,21 +484,42 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {
publicKey,
secretKey,
);
+ let verificationResult: LangfuseConnectionEvent['verification_result'] = 'skipped';
+ if (activationError) {
+ verificationResult = 'failed';
+ } else if (connectionChanged) {
+ verificationResult = 'success';
+ }
recordConnectionUpdate({
event_name: 'librechat.langfuse.connection.changed',
tenant_id: getTenantId(req),
configured: status.configured,
- enabled: status.enabled,
+ enabled: activationError ? false : status.enabled,
destination: status.destination,
change: changes[0],
changes,
- verification_result: connectionChanged ? 'success' : 'skipped',
+ verification_result: verificationResult,
});
-
invalidateConfigCaches?.(getTenantId(req))?.catch((err) =>
logger.error('[adminLangfuse] Cache invalidation failed after update:', err),
);
+ /** Recorded after the cache invalidation starts so audit latency never delays it. Records which parts changed, never the keys themselves. */
+ await emitAudit(req, {
+ action: 'langfuse.updated',
+ severity: 'warning',
+ target: { type: 'langfuse', id: 'connection' },
+ metadata: {
+ changes: [...changes].sort().join(','),
+ enabled: activationError ? false : status.enabled,
+ ...(activationError ? { activation: 'failed' } : {}),
+ ...(status.destination ? { destination: status.destination } : {}),
+ },
+ });
+
+ if (activationError) {
+ throw activationError;
+ }
return res.status(200).json(status);
} catch (error) {
logger.error('[adminLangfuse] updateConnection error:', error);
diff --git a/packages/api/src/admin/skills.spec.ts b/packages/api/src/admin/skills.spec.ts
index 381dcd983e..be70bc8484 100644
--- a/packages/api/src/admin/skills.spec.ts
+++ b/packages/api/src/admin/skills.spec.ts
@@ -576,3 +576,67 @@ describe('createAdminSkillsSyncAccess', () => {
expect(next).toHaveBeenCalledTimes(1);
});
});
+
+describe('skill sync credential audit entries', () => {
+ function build(overrides: Record<string, jest.Mock> = {}) {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createAdminSkillsSyncHandlers({
+ runner: { getStatus: jest.fn(), runOnce: jest.fn() } as never,
+ upsertCredential: jest.fn().mockResolvedValue({
+ provider: 'github',
+ credentialKey: 'github-skills-prod',
+ credentialPresent: true,
+ tokenFingerprint: 'abcd',
+ }),
+ deleteCredential: jest.fn().mockResolvedValue({ deleted: true }),
+ recordAuditEntry,
+ ...overrides,
+ });
+ return { handlers, recordAuditEntry };
+ }
+ const req = (extra: Record<string, unknown> = {}) =>
+ ({
+ user: { id: 'admin-1', name: 'Admin', tenantId: 'tenant-a' },
+ params: { credentialKey: 'github-skills-prod' },
+ body: { token: 'ghp_supersecrettoken' },
+ headers: {},
+ ...extra,
+ }) as never;
+
+ it('records skill_credential.set on the platform chain without the token', async () => {
+ const { handlers, recordAuditEntry } = build();
+
+ await handlers.setCredential(req(), createResponse());
+
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ const input = recordAuditEntry.mock.calls[0][0];
+ expect(input).toEqual(
+ expect.objectContaining({
+ action: 'skill_credential.set',
+ target: { type: 'skill_credential', id: 'github-skills-prod', name: 'github' },
+ tenantId: undefined,
+ }),
+ );
+ expect(JSON.stringify(input)).not.toContain('ghp_supersecrettoken');
+ });
+
+ it('records skill_credential.deleted only when something was deleted', async () => {
+ const missing = build({ deleteCredential: jest.fn().mockResolvedValue({ deleted: false }) });
+ await missing.handlers.deleteCredential(req(), createResponse());
+ expect(missing.recordAuditEntry).not.toHaveBeenCalled();
+
+ const { handlers, recordAuditEntry } = build();
+ await handlers.deleteCredential(req(), createResponse());
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({ action: 'skill_credential.deleted' }),
+ );
+ });
+
+ it('records nothing for an invalid credential key', async () => {
+ const { handlers, recordAuditEntry } = build();
+
+ await handlers.setCredential(req({ params: { credentialKey: 'bad key!' } }), createResponse());
+
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/api/src/admin/skills.ts b/packages/api/src/admin/skills.ts
index ecd4029774..2534613a26 100644
--- a/packages/api/src/admin/skills.ts
+++ b/packages/api/src/admin/skills.ts
@@ -17,6 +17,9 @@ import type {
import type { NextFunction, Request, RequestHandler, Response } from 'express';
import type { Types } from 'mongoose';
import type { GitHubSkillSyncRunner } from '~/skills/sync';
+import type { ServerRequest } from '~/types/http';
+import type { RecordAuditEntry } from './audit';
+import { createAdminAuditEmitter } from './audit';
export type AdminSkillsRequest = Request & {
user?: {
@@ -61,6 +64,9 @@ export type AdminSkillSyncDeps = {
provider: SkillSyncProvider,
credentialKey: string,
) => Promise<{ deleted: boolean }>;
+ /** Optional audit emission for credential changes; fail-open unless `auditFailClosed`. */
+ recordAuditEntry?: RecordAuditEntry;
+ auditFailClosed?: boolean;
};
export type AdminSkillSyncAccessDeps = {
@@ -359,6 +365,12 @@ export function createAdminSkillsSyncAccess(deps: AdminSkillSyncAccessDeps): Adm
}
export function createAdminSkillsSyncHandlers(deps: AdminSkillSyncDeps): AdminSkillsSyncHandlers {
+ const emitAudit = createAdminAuditEmitter({
+ recordAuditEntry: deps.recordAuditEntry,
+ failClosed: deps.auditFailClosed,
+ logPrefix: '[adminSkills]',
+ });
+
function getRunner(req: Request): GitHubSkillSyncRunner {
const runner = deps.getRunner?.(req) ?? deps.runner;
if (!runner) {
@@ -411,6 +423,13 @@ export function createAdminSkillsSyncHandlers(deps: AdminSkillSyncDeps): AdminSk
token: token.trim(),
userId: getUserObjectId(req),
});
+ /** Credentials are platform-level, so entries go to the platform chain. */
+ await emitAudit(req as unknown as ServerRequest, {
+ action: 'skill_credential.set',
+ severity: 'warning',
+ target: { type: 'skill_credential', id: credentialKey, name: 'github' },
+ tenantId: undefined,
+ });
return res.status(200).json(serializeCredential(credential));
}
@@ -420,6 +439,14 @@ export function createAdminSkillsSyncHandlers(deps: AdminSkillSyncDeps): AdminSk
return res.status(400).json({ error: 'Invalid credential key' });
}
const result = await deps.deleteCredential('github', credentialKey);
+ if (result.deleted) {
+ await emitAudit(req as unknown as ServerRequest, {
+ action: 'skill_credential.deleted',
+ severity: 'warning',
+ target: { type: 'skill_credential', id: credentialKey, name: 'github' },
+ tenantId: undefined,
+ });
+ }
return res.status(200).json({ credentialKey, deleted: result.deleted });
}
diff --git a/packages/api/src/auth/passkey/handlers.spec.ts b/packages/api/src/auth/passkey/handlers.spec.ts
index d16a9ae8a2..f244636ec4 100644
--- a/packages/api/src/auth/passkey/handlers.spec.ts
+++ b/packages/api/src/auth/passkey/handlers.spec.ts
@@ -397,6 +397,33 @@ describe('passkey registration provider enforcement', () => {
expect(await methods.countPasskeysByUser(user._id.toString())).toBe(0);
});
+ it('audits a credential that survives a failed rollback', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const countPasskeysByUser = jest
+ .fn(methods.countPasskeysByUser)
+ .mockResolvedValueOnce(0)
+ .mockRejectedValueOnce(new Error('Count unavailable'));
+ const deletePasskey = jest.fn().mockRejectedValue(new Error('Delete unavailable'));
+ const handlers = createPasskeyHandlers(
+ buildDeps({ countPasskeysByUser, deletePasskey, recordAuditEntry }),
+ );
+ const user = await createUser();
+ const res = buildRes();
+
+ await handlers.registerPasskeyVerify(
+ authedReq(user, { credential: attestation, password: PASSWORD }),
+ res,
+ );
+
+ expect(res.status).toHaveBeenCalledWith(500);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'passkey.registered',
+ metadata: expect.objectContaining({ rollback: 'failed' }),
+ }),
+ );
+ });
+
it('rolls back a credential that wins the enrollment race past the cap', async () => {
/** Both verifies observe the pre-enrollment count, as two concurrent
* ceremonies for the same account do, so both pass the early check. */
@@ -474,6 +501,45 @@ describe('passkey registration provider enforcement', () => {
});
});
+ it('records passkey.registered with the user as actor', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createPasskeyHandlers(buildDeps({ recordAuditEntry }));
+ const user = await createUser();
+ const res = buildRes();
+
+ await handlers.registerPasskeyVerify(
+ authedReq(user, { credential: attestation, name: 'Work laptop', password: PASSWORD }),
+ res,
+ );
+
+ expect(res.status).toHaveBeenCalledWith(201);
+ const [stored] = await methods.findPasskeysByUser(user._id.toString());
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'passkey.registered',
+ actor: expect.objectContaining({ type: 'user', id: user._id.toString() }),
+ target: { type: 'passkey', id: stored.id, name: 'Work laptop' },
+ metadata: { deviceType: 'singleDevice', backedUp: false },
+ }),
+ );
+ });
+
+ it('does not record passkey.registered when registration is rejected', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createPasskeyHandlers(buildDeps({ recordAuditEntry }));
+ const user = await createUser();
+ const res = buildRes();
+
+ await handlers.registerPasskeyVerify(
+ authedReq(user, { credential: attestation, name: 'Key', password: 'wrong' }),
+ res,
+ );
+
+ expect(res.status).toHaveBeenCalledWith(403);
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+ });
+
it('names an unnamed credential after its transports', async () => {
const handlers = createPasskeyHandlers(buildDeps());
const user = await createUser();
@@ -710,6 +776,33 @@ describe('passkey rename', () => {
expect(res.json).toHaveBeenCalledWith({ message: 'Name is required' });
});
+ it('records passkey.removed only when a credential was deleted', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const handlers = createPasskeyHandlers(buildDeps({ recordAuditEntry }));
+ const owner = await createUser();
+ const other = await createUser();
+ const passkey = await createStoredPasskey(owner);
+
+ await handlers.removePasskey(
+ authedReq(other, { password: PASSWORD }, { passkeyId: passkey.id }),
+ buildRes(),
+ );
+ expect(recordAuditEntry).not.toHaveBeenCalled();
+
+ await handlers.removePasskey(
+ authedReq(owner, { password: PASSWORD }, { passkeyId: passkey.id }),
+ buildRes(),
+ );
+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'passkey.removed',
+ actor: expect.objectContaining({ type: 'user', id: owner._id.toString() }),
+ target: { type: 'passkey', id: passkey.id },
+ }),
+ );
+ });
+
it('answers 404 for a credential the caller does not own', async () => {
const handlers = createPasskeyHandlers(buildDeps());
const owner = await createUser();
diff --git a/packages/api/src/auth/passkey/handlers.ts b/packages/api/src/auth/passkey/handlers.ts
index e1d57a7ed9..0727cc448f 100644
--- a/packages/api/src/auth/passkey/handlers.ts
+++ b/packages/api/src/auth/passkey/handlers.ts
@@ -7,6 +7,8 @@ import type { AppConfigUserLike, GetAppConfigOptions } from '~/app/service';
import type { PasskeyConfig, PasskeyChallengeStore } from '~/auth/passkey';
import type { ComparePasswordDeps } from '~/auth/password';
import type { UserDocumentId } from '~/auth/verification';
+import type { RecordAuditEntry } from '~/admin/audit';
+import type { ServerRequest } from '~/types/http';
import {
getPasskeyConfig,
isPasskeyEnabled,
@@ -18,6 +20,7 @@ import {
createPasskeyAuthenticationOptions,
} from '~/auth/passkey';
import { grandfatherLegacyEmailVerification } from '~/auth/verification';
+import { createAdminAuditEmitter } from '~/admin/audit';
import { resolveStrictAppConfig } from '~/app/service';
import { comparePassword } from '~/auth/password';
import { isEnabled } from '~/utils';
@@ -121,6 +124,9 @@ export interface PasskeyHandlersDeps {
/** Resolves effective configuration for the authenticated principal. */
getAppConfig?: (options: GetAppConfigOptions) => Promise<AppConfig | undefined>;
compare: ComparePasswordDeps['compare'];
+ /** Optional audit emission for enrolment and removal; fail-open unless `auditFailClosed`. */
+ recordAuditEntry?: RecordAuditEntry;
+ auditFailClosed?: boolean;
/** The login ban middleware; reports an internal failure through `next(err)`. */
checkBan: (
req: PasskeyRequest<AuthenticationBody>,
@@ -250,8 +256,16 @@ export function createPasskeyHandlers(deps: PasskeyHandlersDeps): PasskeyHandler
getAppConfig,
countPasskeysByUser,
findPasskeyByCredentialId,
+ recordAuditEntry,
+ auditFailClosed,
} = deps;
+ const emitAudit = createAdminAuditEmitter({
+ recordAuditEntry,
+ failClosed: auditFailClosed,
+ logPrefix: '[passkey]',
+ });
+
const getChallengeStore = (): PasskeyChallengeStore =>
createPasskeyChallengeStore(getChallengeCache());
@@ -446,18 +460,35 @@ export function createPasskeyHandlers(deps: PasskeyHandlersDeps): PasskeyHandler
* the write and rolling this credential back keeps the stored set within
* the cap without a transaction, at the cost of rejecting the whole race.
*/
+ const auditRegistered = (metadata: Record<string, unknown> = {}) =>
+ emitAudit(req as unknown as ServerRequest, {
+ action: 'passkey.registered',
+ severity: 'warning',
+ target: { type: 'passkey', id: passkey.id, name: passkey.name },
+ metadata: { deviceType: verified.deviceType, backedUp: verified.backedUp, ...metadata },
+ });
+ /** A credential that survives a failed rollback is a usable factor, so it is audited. */
+ const rollBack = async () => {
+ try {
+ await deletePasskey(passkey.id, req.user.id);
+ } catch (rollbackError) {
+ await auditRegistered({ rollback: 'failed' });
+ throw rollbackError;
+ }
+ };
let countAfterWrite: number;
try {
countAfterWrite = await countPasskeysByUser(req.user.id);
} catch (error) {
- await deletePasskey(passkey.id, req.user.id);
+ await rollBack();
throw error;
}
if (countAfterWrite > maxPasskeys) {
- await deletePasskey(passkey.id, req.user.id);
+ await rollBack();
return res.status(409).json({ message: 'Passkey limit reached' });
}
+ await auditRegistered();
return res.status(201).json({ passkey: serializePasskey(passkey) });
} catch (err) {
if (isDuplicateKeyError(err as MongoWriteError)) {
@@ -529,6 +560,11 @@ export function createPasskeyHandlers(deps: PasskeyHandlersDeps): PasskeyHandler
if (!result?.deletedCount) {
return res.status(404).json({ message: 'Passkey not found' });
}
+ await emitAudit(req as unknown as ServerRequest, {
+ action: 'passkey.removed',
+ severity: 'warning',
+ target: { type: 'passkey', id: req.params.passkeyId },
+ });
return res.status(200).json({ message: 'Passkey deleted' });
} catch (err) {
logger.error('[removePasskey]', err);
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index f501999978..b3d9bd8dbf 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -29,6 +29,7 @@ export * from './mcp/oauth';
export * from './mcp/auth';
export * from './mcp/zod';
export * from './mcp/errors';
+export * from './mcp/audit';
export * from './mcp/loading';
export * from './mcp/openid';
export * from './mcp/cache';
diff --git a/packages/api/src/mcp/audit.spec.ts b/packages/api/src/mcp/audit.spec.ts
new file mode 100644
index 0000000000..ca2aa474cc
--- /dev/null
+++ b/packages/api/src/mcp/audit.spec.ts
@@ -0,0 +1,193 @@
+import type { ServerRequest } from '~/types/http';
+import { createMCPServerAuditor, settleMCPCommit, diffMCPServerFields } from './audit';
+import { MCPCommittedWriteError } from '~/mcp/errors';
+
+const req = { user: { id: 'user-1', name: 'Alice' }, headers: {} } as unknown as ServerRequest;
+
+describe('diffMCPServerFields', () => {
+ it('returns sorted names of changed user-input fields only', () => {
+ expect(
+ diffMCPServerFields(
+ { url: 'https://a', title: 'T', headers: { A: '1' }, dbId: 'x' },
+ { url: 'https://b', title: 'T', headers: { A: '2' }, dbId: 'y' },
+ ),
+ ).toEqual(['headers', 'url']);
+ });
+
+ it('ignores key order inside record fields', () => {
+ expect(
+ diffMCPServerFields({ headers: { A: '1', B: '2' } }, { headers: { B: '2', A: '1' } }),
+ ).toEqual([]);
+ });
+
+ it('treats a missing side as all-new', () => {
+ expect(diffMCPServerFields(undefined, { type: 'sse', url: 'https://a' })).toEqual([
+ 'type',
+ 'url',
+ ]);
+ });
+});
+
+describe('createMCPServerAuditor', () => {
+ it('lists no fields for a delete', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+
+ await audit(req, {
+ action: 'mcp_server.deleted',
+ serverName: 'srv',
+ previous: { url: 'https://a', title: 'Srv' },
+ });
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.deleted',
+ severity: 'warning',
+ target: { type: 'mcp_server', id: 'srv', name: 'Srv' },
+ metadata: { source: 'DB' },
+ }),
+ );
+ });
+
+ it('does not record a preserved OAuth secret as a change', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+
+ await audit(req, {
+ action: 'mcp_server.updated',
+ serverName: 'srv',
+ previous: { title: 'Old', oauth: { client_id: 'id', client_secret: 'stored' } },
+ next: { title: 'New', oauth: { client_id: 'id' } },
+ });
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({ metadata: { source: 'DB', fields: 'title' } }),
+ );
+ });
+
+ it('does not record omitted optional OAuth binding fields as a change', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+
+ await audit(req, {
+ action: 'mcp_server.updated',
+ serverName: 'srv',
+ previous: {
+ title: 'Old',
+ oauth: {
+ client_id: 'id',
+ client_secret: 'stored',
+ revocation_endpoint: 'https://idp.example/revoke',
+ token_endpoint_auth_methods_supported: ['client_secret_basic'],
+ },
+ },
+ next: { title: 'New', oauth: { client_id: 'id' } },
+ });
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({ metadata: { source: 'DB', fields: 'title' } }),
+ );
+ });
+
+ it('diffs against the persisted config, not the submission', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+ const headers = { Authorization: 'Bearer {{MCP_API_KEY_srv}}' };
+
+ await audit(req, {
+ action: 'mcp_server.updated',
+ serverName: 'srv',
+ previous: { title: 'Old', headers },
+ next: { title: 'New', headers },
+ });
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({ metadata: { source: 'DB', fields: 'title' } }),
+ );
+ });
+
+ it('marks the entry when the cache refresh failed after the commit', async () => {
+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+
+ await audit(req, {
+ action: 'mcp_server.deleted',
+ serverName: 'srv',
+ previous: { title: 'Old' },
+ postWriteFailed: true,
+ });
+
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ action: 'mcp_server.deleted',
+ metadata: { source: 'DB', postWrite: 'failed' },
+ }),
+ );
+ });
+
+ describe('MCPCommittedWriteError', () => {
+ it('keeps the persisted config out of serialized and logged errors', () => {
+ const error = new MCPCommittedWriteError(
+ { oauth: { client_secret: 'super-secret' } },
+ new Error('redis down'),
+ );
+
+ expect(error.committed).toEqual({ oauth: { client_secret: 'super-secret' } });
+ expect(JSON.stringify(error)).not.toContain('super-secret');
+ expect(Object.keys(error)).not.toContain('committed');
+ expect(Object.keys(error)).not.toContain('cause');
+ expect(error.cause).toBeInstanceOf(Error);
+ });
+ });
+
+ describe('settleMCPCommit', () => {
+ it('returns the committed result when the write succeeds', async () => {
+ await expect(settleMCPCommit(async () => ({ title: 'x' }))).resolves.toEqual({
+ committed: { title: 'x' },
+ });
+ });
+
+ it('returns the committed result together with an invalidation failure', async () => {
+ const failure = new MCPCommittedWriteError({ title: 'x' }, new Error('redis down'));
+
+ const settled = await settleMCPCommit(async () => {
+ throw failure;
+ });
+
+ expect(settled.committed).toEqual({ title: 'x' });
+ expect(settled.postWriteError).toBe(failure);
+ });
+
+ it('rethrows any other failure as an uncommitted write', async () => {
+ await expect(
+ settleMCPCommit(async () => {
+ throw new Error('write failed');
+ }),
+ ).rejects.toThrow('write failed');
+ });
+ });
+
+ it('runs the post-commit steps before the audit write and still audits when they throw', async () => {
+ const order: string[] = [];
+ const recordAuditEntry = jest.fn().mockImplementation(async () => void order.push('audit'));
+ const audit = createMCPServerAuditor({ recordAuditEntry });
+
+ await expect(
+ audit(req, { action: 'mcp_server.deleted', serverName: 'srv' }, async () => {
+ order.push('fence');
+ throw new Error('fence failed');
+ }),
+ ).rejects.toThrow('fence failed');
+
+ expect(order).toEqual(['fence', 'audit']);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({ metadata: { source: 'DB', postWrite: 'failed' } }),
+ );
+ });
+
+ it('is a no-op without a recorder', async () => {
+ await expect(
+ createMCPServerAuditor({})(req, { action: 'mcp_server.created', serverName: 'srv' }),
+ ).resolves.toBeUndefined();
+ });
+});
diff --git a/packages/api/src/mcp/audit.ts b/packages/api/src/mcp/audit.ts
new file mode 100644
index 0000000000..ad1d0aa258
--- /dev/null
+++ b/packages/api/src/mcp/audit.ts
@@ -0,0 +1,165 @@
+import { MCP_USER_INPUT_FIELDS } from 'librechat-data-provider';
+import type { AdminAuditEmitter, RecordAuditEntry } from '~/admin/audit';
+import { createAdminAuditEmitter } from '~/admin/audit';
+import { MCPCommittedWriteError } from '~/mcp/errors';
+
+type MCPServerAction = 'mcp_server.created' | 'mcp_server.updated' | 'mcp_server.deleted';
+type ServerConfigLike = Record<string, unknown> | null | undefined;
+
+export interface MCPServerAuditEvent {
+ action: MCPServerAction;
+ serverName: string;
+ /** Config before the change; omitted on create. */
+ previous?: ServerConfigLike;
+ /** Config after the change; omitted on delete. */
+ next?: ServerConfigLike;
+ /** The write committed but refreshing the read caches failed afterwards. */
+ postWriteFailed?: boolean;
+ /** The write found nothing to change (for example a delete that lost a race), so no entry is recorded. */
+ noop?: boolean;
+}
+
+/** JSON with object keys sorted, so entry order never reads as a change. */
+function stableStringify(value: unknown): string {
+ return JSON.stringify(value, (_key, val) =>
+ val && typeof val === 'object' && !Array.isArray(val)
+ ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b)))
+ : val,
+ );
+}
+
+/**
+ * Lists the user-input fields that differ between two server configs. Only
+ * field names are returned, so headers, env values and credentials never reach
+ * the audit trail.
+ */
+export function diffMCPServerFields(previous: ServerConfigLike, next: ServerConfigLike): string[] {
+ const changed: string[] = [];
+ for (const field of MCP_USER_INPUT_FIELDS) {
+ const before = previous?.[field];
+ const after = next?.[field];
+ if (before === undefined && after === undefined) {
+ continue;
+ }
+ if (stableStringify(before) !== stableStringify(after)) {
+ changed.push(field);
+ }
+ }
+ return changed.sort();
+}
+
+/** Optional OAuth fields the data layer also keeps when an update omits them alongside the secret. */
+const OMITTED_OAUTH_BINDING_FIELDS = [
+ 'token_endpoint_auth_methods_supported',
+ 'revocation_endpoint',
+ 'revocation_endpoint_auth_methods_supported',
+] as const;
+
+/**
+ * An update that omits `oauth.client_secret` keeps the stored one, so the secret
+ * is carried onto the incoming config before comparing; otherwise a title-only
+ * edit would be recorded as an oauth change.
+ */
+function withPreservedOAuthSecret(
+ previous: ServerConfigLike,
+ next: ServerConfigLike,
+): ServerConfigLike {
+ const before = previous?.oauth as Record<string, unknown> | undefined;
+ const after = next?.oauth as Record<string, unknown> | undefined;
+ if (!next || !before?.client_secret || !after || after.client_secret) {
+ return next;
+ }
+ const carried = { ...after, client_secret: before.client_secret } as Record<string, unknown>;
+ for (const field of OMITTED_OAUTH_BINDING_FIELDS) {
+ if (carried[field] === undefined && before[field] !== undefined) {
+ carried[field] = before[field];
+ }
+ }
+ return { ...next, oauth: carried };
+}
+
+function serverTitle(config: ServerConfigLike): string | undefined {
+ const title = config?.title;
+ return typeof title === 'string' && title.length > 0 ? title : undefined;
+}
+
+/**
+ * Builds the MCP server audit writer. Fail-open unless `failClosed` is set,
+ * matching the admin handler factories.
+ */
+export function createMCPServerAuditor(options: {
+ recordAuditEntry?: RecordAuditEntry;
+ failClosed?: boolean;
+}): (
+ req: Parameters<AdminAuditEmitter>[0],
+ event: MCPServerAuditEvent,
+ afterCommit?: () => Promise<void>,
+) => Promise<void> {
+ const emit = createAdminAuditEmitter({ ...options, logPrefix: '[mcpServers]' });
+ async function record(
+ req: Parameters<AdminAuditEmitter>[0],
+ event: MCPServerAuditEvent,
+ ): Promise<void> {
+ const { action, serverName, previous, next, postWriteFailed } = event;
+ const name = serverTitle(next) ?? serverTitle(previous);
+ const before = action === 'mcp_server.created' ? undefined : previous;
+ const changed =
+ action === 'mcp_server.deleted'
+ ? []
+ : diffMCPServerFields(before, withPreservedOAuthSecret(before, next));
+ await emit(req, {
+ action,
+ severity: action === 'mcp_server.deleted' ? 'warning' : 'info',
+ target: { type: 'mcp_server', id: serverName, ...(name ? { name } : {}) },
+ metadata: {
+ source: 'DB',
+ ...(changed.length > 0 ? { fields: changed.join(',') } : {}),
+ ...(postWriteFailed ? { postWrite: 'failed' } : {}),
+ },
+ });
+ }
+
+ /**
+ * `afterCommit` carries the security-critical steps that follow a committed
+ * change (connection fences); they run first, and the audit write follows even
+ * when they throw, so audit latency never delays them and a failure never
+ * drops the entry.
+ */
+ return async function auditMCPServer(req, event, afterCommit) {
+ let afterCommitFailed = false;
+ try {
+ await afterCommit?.();
+ } catch (error) {
+ afterCommitFailed = true;
+ throw error;
+ } finally {
+ if (!event.noop) {
+ await record(req, {
+ ...event,
+ postWriteFailed: event.postWriteFailed || afterCommitFailed,
+ });
+ }
+ }
+ };
+}
+
+/**
+ * Runs a registry write and reports what it persisted. When the write committed but the
+ * cache refresh after it failed, the committed result is still returned together with that
+ * failure, so the caller can audit the change and then surface the error.
+ */
+export async function settleMCPCommit<T>(
+ write: () => Promise<T>,
+): Promise<{ committed: T | undefined; postWriteError?: MCPCommittedWriteError<T> }> {
+ try {
+ return { committed: await write() };
+ } catch (error) {
+ if (error instanceof MCPCommittedWriteError) {
+ return {
+ committed: error.committed as T | undefined,
+ postWriteError: error as MCPCommittedWriteError<T>,
+ };
+ }
+ throw error;
+ }
+}
diff --git a/packages/api/src/mcp/errors.ts b/packages/api/src/mcp/errors.ts
index 51c3fc27cd..ec936948f5 100644
--- a/packages/api/src/mcp/errors.ts
+++ b/packages/api/src/mcp/errors.ts
@@ -527,3 +527,24 @@ export function createScheduledMCPTransportError(
agentId,
);
}
+
+/**
+ * Thrown when a registry write committed but a step after it failed (permission
+ * bookkeeping, cache invalidation). The write stands; `committed` carries what was
+ * persisted (undefined for a removal) so a caller can still record it before surfacing
+ * the failure. The persisted config can hold decrypted secrets, so the property is
+ * non-enumerable and never reaches a serialized or logged error.
+ */
+export class MCPCommittedWriteError<T = unknown> extends Error {
+ public readonly committed!: T | undefined;
+
+ constructor(committed: T | undefined, cause: unknown) {
+ /** Fixed text: this message reaches API responses, and the cause may carry driver or cache details. */
+ super('MCP server change was saved but a step after it failed');
+ this.name = 'MCPCommittedWriteError';
+ Object.defineProperty(this, 'committed', { value: committed, enumerable: false });
+ /** Non-enumerable, so structured loggers never serialize driver or cache details. */
+ Object.defineProperty(this, 'cause', { value: cause, enumerable: false, configurable: true });
+ Object.setPrototypeOf(this, MCPCommittedWriteError.prototype);
+ }
+}
diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.ts
index 9893f5cafe..7b62ad31e8 100644
--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts
+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts
@@ -14,7 +14,11 @@ import {
APP_CACHE_NAMESPACE,
CONFIG_CACHE_NAMESPACE,
} from './cache/ServerConfigsCacheFactory';
-import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';
+import {
+ MCPCommittedWriteError,
+ MCPInspectionFailedError,
+ isMCPDomainNotAllowedError,
+} from '~/mcp/errors';
import { normalizeLegacyHeaderMaps, normalizeLegacyHeaderMapsIn } from './compat';
import { canBackfillSharedServerInstructions, isUserSourced } from '~/mcp/utils';
import { ReadThroughAllCache } from './cache/ReadThroughAllCache';
@@ -23,6 +27,7 @@ import { requireApiKeyReentryForRebinding } from './binding';
import { ReadThroughCache } from './cache/ReadThroughCache';
import { MCPServerInspector } from './MCPServerInspector';
import { ServerConfigsDB } from './db/ServerConfigsDB';
+import { getSafeErrorMetadata } from '~/utils/errors';
import { cacheConfig } from '~/cache';
import { withTimeout } from '~/utils';
@@ -672,22 +677,73 @@ export class MCPServersRegistry {
...parsedConfig,
source,
};
- const result =
- storageLocation === 'DB'
- ? await this.dbConfigsRepo.add(
- serverName,
- tagged,
- userId,
- await this.getOperatorManagedServerNames(reservedServerNames),
- )
- : await configRepo.add(serverName, tagged, userId);
- await this.invalidateServerReadCaches(result.serverName, userId, storageLocation);
+ let result: t.AddServerResult;
+ try {
+ result =
+ storageLocation === 'DB'
+ ? await this.dbConfigsRepo.add(
+ serverName,
+ tagged,
+ userId,
+ await this.getOperatorManagedServerNames(reservedServerNames),
+ )
+ : await configRepo.add(serverName, tagged, userId);
+ } catch (error) {
+ await this.invalidateAfterCommittedFailure(error, serverName, userId, storageLocation);
+ throw error;
+ }
+ await this.invalidateCommitted(result, () =>
+ this.invalidateServerReadCaches(result.serverName, userId, storageLocation),
+ );
if (storageLocation === 'CACHE') {
this.resetYamlServerNamesMemo();
}
return result;
}
+ /**
+ * A repository step after a committed write failed (for example permission bookkeeping),
+ * so the stored config changed even though the call rejects: refresh the read caches
+ * best-effort before the failure propagates, or they would keep serving the old state.
+ */
+ private async invalidateAfterCommittedFailure(
+ error: unknown,
+ serverName: string,
+ userId: string | undefined,
+ storageLocation: 'CACHE' | 'DB',
+ ): Promise<void> {
+ if (!(error instanceof MCPCommittedWriteError)) {
+ return;
+ }
+ const committed = error.committed as t.AddServerResult | undefined;
+ await this.invalidateServerReadCaches(
+ committed?.serverName ?? serverName,
+ userId,
+ storageLocation,
+ ).catch((invalidationError) =>
+ logger.error(
+ '[MCPServersRegistry] cache invalidation failed after a committed write error:',
+ getSafeErrorMetadata(invalidationError),
+ ),
+ );
+ }
+
+ /**
+ * Runs the cache invalidation that follows a committed write. A failure is rethrown as
+ * `MCPCommittedWriteError` carrying what was persisted, so the caller can record
+ * the committed change instead of mistaking it for a write that never happened.
+ */
+ private async invalidateCommitted<T>(
+ committed: T | undefined,
+ invalidate: () => Promise<void>,
+ ): Promise<void> {
+ try {
+ await invalidate();
+ } catch (error) {
+ throw new MCPCommittedWriteError(committed, error);
+ }
+ }
+
/**
* Backfills the inspector-derived `resolvedInstructions` for a server whose
* operator explicitly deferred startup inspection. An enabled
@@ -1059,9 +1115,11 @@ export class MCPServersRegistry {
userId?: string,
): Promise<t.ParsedServerConfig> {
const configRepo = this.getConfigRepository(storageLocation);
- await configRepo.update(serverName, parsedConfig, userId);
- await this.invalidateServerReadCaches(serverName, userId, storageLocation);
- return parsedConfig;
+ const persisted = (await configRepo.update(serverName, parsedConfig, userId)) ?? parsedConfig;
+ await this.invalidateCommitted(persisted, () =>
+ this.invalidateServerReadCaches(serverName, userId, storageLocation),
+ );
+ return persisted;
}
public async updateServer(
@@ -1323,13 +1381,22 @@ export class MCPServersRegistry {
serverName: string,
storageLocation: 'CACHE' | 'DB',
userId?: string,
- ): Promise<void> {
+ ): Promise<boolean> {
const configRepo = this.getConfigRepository(storageLocation);
- await configRepo.remove(serverName, userId);
- await this.invalidateServerReadCaches(serverName, userId, storageLocation);
+ let removed: boolean | void;
+ try {
+ removed = await configRepo.remove(serverName, userId);
+ } catch (error) {
+ await this.invalidateAfterCommittedFailure(error, serverName, userId, storageLocation);
+ throw error;
+ }
+ await this.invalidateCommitted(removed !== false, () =>
+ this.invalidateServerReadCaches(serverName, userId, storageLocation),
+ );
if (storageLocation === 'CACHE') {
this.resetYamlServerNamesMemo();
}
+ return removed !== false;
}
private getConfigRepository(storageLocation: 'CACHE' | 'DB'): IServerConfigsRepositoryInterface {
diff --git a/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts b/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts
index 42d78c8fed..8eddbdd20e 100644
--- a/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts
+++ b/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts
@@ -7,7 +7,12 @@ export interface IServerConfigsRepositoryInterface {
add(serverName: string, config: ParsedServerConfig, userId?: string): Promise<AddServerResult>;
//ACL Entry check if update is possible
- update(serverName: string, config: ParsedServerConfig, userId?: string): Promise<void>;
+ /** Resolves to the config as persisted when the store can report it. */
+ update(
+ serverName: string,
+ config: ParsedServerConfig,
+ userId?: string,
+ ): Promise<ParsedServerConfig | void>;
/** Atomic add-or-update without requiring callers to inspect error messages. */
upsert(serverName: string, config: ParsedServerConfig, userId?: string): Promise<void>;
@@ -45,7 +50,8 @@ export interface IServerConfigsRepositoryInterface {
): Promise<ParsedServerConfig | undefined>;
//ACL Entry check if remove is possible
- remove(serverName: string, userId?: string): Promise<void>;
+ /** Resolves to false when the store knew no such server, so a no-op is distinguishable. */
+ remove(serverName: string, userId?: string): Promise<boolean | void>;
//ACL Entry check if read is possible
get(serverName: string, userId?: string): Promise<ParsedServerConfig | undefined>;
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
index 1bc16b2b63..38c0867bd4 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
@@ -14,9 +14,9 @@ import {
MCPConfigInitializationCanceledError,
} from '~/mcp/registry/MCPServersRegistry';
import { ServerConfigsCacheInMemory } from '~/mcp/registry/cache/ServerConfigsCacheInMemory';
+import { MCPCommittedWriteError, MCPInspectionFailedError } from '~/mcp/errors';
import { getMCPAppToolsPublicationGeneration } from '~/mcp/toolsChanged';
import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';
-import { MCPInspectionFailedError } from '~/mcp/errors';
import { processMCPEnv } from '~/utils/env';
// Mock MCPServerInspector to avoid actual server connections
@@ -843,6 +843,67 @@ describe('MCPServersRegistry', () => {
});
});
+ describe('cache invalidation failure after a committed write', () => {
+ const failInvalidation = () =>
+ jest
+ .spyOn(
+ registry as unknown as { invalidateServerReadCaches: () => Promise<void> },
+ 'invalidateServerReadCaches',
+ )
+ .mockRejectedValue(new Error('redis down'));
+
+ it('reports what addServer persisted', async () => {
+ failInvalidation();
+
+ const failure = await registry
+ .addServer('cache_server', testParsedConfig, 'CACHE')
+ .catch((error) => error);
+
+ expect(failure).toBeInstanceOf(MCPCommittedWriteError);
+ expect(failure.committed.serverName).toBe('cache_server');
+ expect(await registry['cacheConfigsRepo'].get('cache_server')).toBeDefined();
+ });
+
+ it('reports what commitServerUpdate persisted', async () => {
+ await registry.addServer('cache_server', testParsedConfig, 'CACHE');
+ failInvalidation();
+ const updated = { ...testParsedConfig, command: 'python' } as t.ParsedServerConfig;
+
+ const failure = await registry
+ .commitServerUpdate('cache_server', updated, 'CACHE')
+ .catch((error) => error);
+
+ expect(failure).toBeInstanceOf(MCPCommittedWriteError);
+ expect(failure.committed.command).toBe('python');
+ });
+
+ it('refreshes the read caches when a repository step after the write fails', async () => {
+ await registry.addServer('cache_server', testParsedConfig, 'CACHE');
+ const invalidate = jest.spyOn(
+ registry as unknown as { invalidateServerReadCaches: () => Promise<void> },
+ 'invalidateServerReadCaches',
+ );
+ jest
+ .spyOn(registry['cacheConfigsRepo'], 'remove')
+ .mockRejectedValueOnce(new MCPCommittedWriteError(undefined, new Error('acl down')));
+
+ await expect(registry.removeServer('cache_server', 'CACHE')).rejects.toBeInstanceOf(
+ MCPCommittedWriteError,
+ );
+ expect(invalidate).toHaveBeenCalledWith('cache_server', undefined, 'CACHE');
+ });
+
+ it('still reports a removal that committed', async () => {
+ await registry.addServer('cache_server', testParsedConfig, 'CACHE');
+ failInvalidation();
+
+ await expect(registry.removeServer('cache_server', 'CACHE')).rejects.toBeInstanceOf(
+ MCPCommittedWriteError,
+ );
+ expect(await registry['cacheConfigsRepo'].get('cache_server')).toBeUndefined();
+ });
+ });
+
describe('Invalid storage location', () => {
it('should throw error for unsupported storage location in addServer', async () => {
await expect(
diff --git a/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts b/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
index 291ae55da1..64aca9af07 100644
--- a/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
@@ -204,6 +204,37 @@ describe('ServerConfigsDB', () => {
expect(retrieved?.description).toBe('Updated description');
});
+ it('returns the config as persisted, so an overlapping update is not mistaken for this one', async () => {
+ const created = await serverConfigsDB.add(
+ 'temp-name',
+ createSSEConfig('Title', 'First'),
+ userId,
+ );
+
+ const firstWrite = await serverConfigsDB.update(
+ created.serverName,
+ createSSEConfig('Title', 'Second'),
+ userId,
+ );
+ await serverConfigsDB.update(created.serverName, createSSEConfig('Title', 'Third'), userId);
+
+ expect(firstWrite?.description).toBe('Second');
+ expect((await serverConfigsDB.get(created.serverName, userId))?.description).toBe('Third');
+ });
+
+ it('rejects an update when the server was deleted after the lookup', async () => {
+ const created = await serverConfigsDB.add(
+ 'temp-name',
+ createSSEConfig('Title', 'First'),
+ userId,
+ );
+ await serverConfigsDB.remove(created.serverName, userId);
+
+ await expect(
+ serverConfigsDB.update(created.serverName, createSSEConfig('Title', 'Second'), userId),
+ ).rejects.toThrow('no longer exists');
+ });
+
it('should preserve oauth.client_secret when not provided in update', async () => {
const config: ParsedServerConfig = {
type: 'sse',
@@ -1427,12 +1458,40 @@ describe('ServerConfigsDB', () => {
});
});
+ describe('post-write failures', () => {
+ it('reports the created server when granting its owner access fails', async () => {
+ jest
+ .spyOn(serverConfigsDB['_aclService'], 'grantPermission')
+ .mockRejectedValueOnce(new Error('acl down'));
+
+ const failure = await serverConfigsDB
+ .add('temp-name', createSSEConfig('Orphan Risk'), userId)
+ .catch((error) => error);
+
+ expect(failure.name).toBe('MCPCommittedWriteError');
+ expect(failure.committed.config.title).toBe('Orphan Risk');
+ expect(await mongoose.models.MCPServer.countDocuments({})).toBe(1);
+ });
+
+ it('reports the removal when cleaning up its permissions fails', async () => {
+ const created = await serverConfigsDB.add('temp-name', createSSEConfig('Remove Me'), userId);
+ jest
+ .spyOn(serverConfigsDB['_aclService'], 'removeAllPermissions')
+ .mockRejectedValueOnce(new Error('acl down'));
+
+ await expect(serverConfigsDB.remove(created.serverName, userId)).rejects.toMatchObject({
+ name: 'MCPCommittedWriteError',
+ });
+ expect(await mongoose.models.MCPServer.countDocuments({})).toBe(0);
+ });
+ });
+
describe('remove()', () => {
it('should delete server from database', async () => {
const config = createSSEConfig('Delete Test');
const created = await serverConfigsDB.add('temp-name', config, userId);
- await serverConfigsDB.remove(created.serverName, userId);
+ await expect(serverConfigsDB.remove(created.serverName, userId)).resolves.toBe(true);
const MCPServer = mongoose.models.MCPServer;
const server = await MCPServer.findOne({ serverName: created.serverName });
@@ -1461,8 +1520,8 @@ describe('ServerConfigsDB', () => {
});
it('should handle non-existent server gracefully', async () => {
- // Should not throw
- await expect(serverConfigsDB.remove('non-existent-server', userId)).resolves.toBeUndefined();
+ // Should not throw, and reports that nothing was removed
+ await expect(serverConfigsDB.remove('non-existent-server', userId)).resolves.toBe(false);
});
});
diff --git a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
index 86327229b3..6e063a64a7 100644
--- a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
+++ b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
@@ -11,8 +11,8 @@ import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerCon
import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';
import type { ResolvedPrincipal } from '~/types/principal';
import { getUserApiKeyVariable, requireApiKeyReentryForRebinding } from '~/mcp/registry/binding';
+import { MCPCommittedWriteError, MCPOAuthSecretReentryRequiredError } from '~/mcp/errors';
import { normalizeLegacyHeaderMaps } from '~/mcp/registry/compat';
-import { MCPOAuthSecretReentryRequiredError } from '~/mcp/errors';
import { AccessControlService } from '~/acl/accessControlService';
import { isGeneratedUserApiKeyVariable } from '~/mcp/headers';
@@ -316,18 +316,24 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
author: userId,
reservedServerNames,
});
- await this._aclService.grantPermission({
- principalType: PrincipalType.USER,
- principalId: userId,
- resourceType: ResourceType.MCPSERVER,
- resourceId: createdServer._id,
- accessRoleId: AccessRoleIds.MCPSERVER_OWNER,
- grantedBy: userId,
- });
- return {
+ const created = {
serverName: createdServer.serverName,
config: await this.mapDBServerToParsedConfig(createdServer),
};
+ try {
+ await this._aclService.grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: userId,
+ resourceType: ResourceType.MCPSERVER,
+ resourceId: createdServer._id,
+ accessRoleId: AccessRoleIds.MCPSERVER_OWNER,
+ grantedBy: userId,
+ });
+ } catch (error) {
+ /** The server exists already, so the failure must not read as a create that never happened. */
+ throw new MCPCommittedWriteError(created, error);
+ }
+ return created;
}
/**
@@ -340,7 +346,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
serverName: string,
config: ParsedServerConfig,
userId?: string,
- ): Promise<void> {
+ ): Promise<ParsedServerConfig> {
if (!userId) {
throw new Error(
'[ServerConfigsDB.update] User ID is required to update a database-stored MCP server.',
@@ -405,7 +411,11 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
};
}
- await this._dbMethods.updateMCPServer(serverName, { config: configToSave });
+ const saved = await this._dbMethods.updateMCPServer(serverName, { config: configToSave });
+ if (!saved) {
+ throw new Error(`[ServerConfigsDB.update] MCP server "${serverName}" no longer exists.`);
+ }
+ return await this.mapDBServerToParsedConfig(saved);
}
/**
@@ -424,7 +434,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
'Config-source servers should use configCacheRepo, not dbConfigsRepo.',
);
}
- return this.update(serverName, config, userId);
+ await this.update(serverName, config, userId);
}
/**
@@ -432,18 +442,23 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
* @param serverName - The serverName of the server to remove
* @param userId - User performing the deletion (for logging)
*/
- public async remove(serverName: string, userId?: string): Promise<void> {
+ public async remove(serverName: string, userId?: string): Promise<boolean> {
logger.debug(`[ServerConfigsDB.remove] removing ${serverName}. UserId: ${userId}`);
const deletedServer = await this._dbMethods.deleteMCPServer(serverName);
if (deletedServer && deletedServer._id) {
logger.debug(`[ServerConfigsDB.remove] removing all permissions entries of ${serverName}.`);
- await this._aclService.removeAllPermissions({
- resourceType: ResourceType.MCPSERVER,
- resourceId: deletedServer._id!,
- });
- return;
+ try {
+ await this._aclService.removeAllPermissions({
+ resourceType: ResourceType.MCPSERVER,
+ resourceId: deletedServer._id!,
+ });
+ } catch (error) {
+ throw new MCPCommittedWriteError(true, error);
+ }
+ return true;
}
logger.warn(`[ServerConfigsDB.remove] server with serverName ${serverName} does not exist`);
+ return false;
}
/**
diff --git a/packages/data-schemas/src/methods/auditLog.spec.ts b/packages/data-schemas/src/methods/auditLog.spec.ts
index da7b52312e..b5609e770c 100644
--- a/packages/data-schemas/src/methods/auditLog.spec.ts
+++ b/packages/data-schemas/src/methods/auditLog.spec.ts
@@ -523,6 +523,59 @@ describe('auditLog methods', () => {
expect(remaining.map((r) => r.seq)).toEqual([1, 2, 3, 4]);
});
+ it('records audit.purged after a purge that removed rows, and not after a no-op', async () => {
+ for (let i = 0; i < 4; i++) {
+ await methods.recordAuditEntry(baseInput());
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+ const third = await AuditLog.findOne({ chainKey: CK_A, seq: 3 }).lean();
+
+ await methods.purgeAuditLogEntries('tenant-a', {
+ before: new Date(Date.now() - 60_000),
+ confirm: true,
+ });
+ expect(await AuditLog.countDocuments({ chainKey: CK_A, action: 'audit.purged' })).toBe(0);
+
+ const result = await methods.purgeAuditLogEntries('tenant-a', {
+ before: third!.createdAt,
+ confirm: true,
+ });
+
+ const entry = await AuditLog.findOne({ chainKey: CK_A, action: 'audit.purged' }).lean();
+ expect(entry).toMatchObject({
+ category: 'audit',
+ severity: 'critical',
+ actor: { type: 'system', name: 'audit-retention' },
+ target: { type: 'audit_log' },
+ metadata: { deletedCount: result.deletedCount, throughSeq: result.checkpoint?.throughSeq },
+ });
+ const verified = await methods.verifyAuditChain('tenant-a', {
+ trustedCheckpoint: result.checkpoint,
+ });
+ expect(verified.ok).toBe(true);
+ });
+
+ it('still returns the purge result when the audit write rejects', async () => {
+ for (let i = 0; i < 4; i++) {
+ await methods.recordAuditEntry(baseInput());
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+ const third = await AuditLog.findOne({ chainKey: CK_A, seq: 3 }).lean();
+ const spy = jest.spyOn(AuditLog, 'create').mockRejectedValue(new Error('audit store down'));
+
+ try {
+ const result = await methods.purgeAuditLogEntries('tenant-a', {
+ before: third!.createdAt,
+ confirm: true,
+ });
+ expect(result.deletedCount).toBeGreaterThanOrEqual(1);
+ expect(result.checkpoint).toBeDefined();
+ } finally {
+ spy.mockRestore();
+ }
+ expect(await AuditLog.countDocuments({ chainKey: CK_A, action: 'audit.purged' })).toBe(0);
+ });
+
it('does not mint a checkpoint when a confirmed purge removed nothing', async () => {
await seed(2);
const result = await methods.purgeAuditLogEntries('tenant-a', {
diff --git a/packages/data-schemas/src/methods/auditLog.ts b/packages/data-schemas/src/methods/auditLog.ts
index dc8077dbdf..2856cb25c0 100644
--- a/packages/data-schemas/src/methods/auditLog.ts
+++ b/packages/data-schemas/src/methods/auditLog.ts
@@ -710,6 +710,29 @@ export function createAuditLogMethods(
.select('seq prevHash')
.lean<{ seq: number; prevHash: string }>();
+ /** The purge itself is audited after the checkpoint is read, so the new
+ * entry cannot shift the boundary; a failed write is logged, not thrown. */
+ try {
+ await recordAuditEntry({
+ action: 'audit.purged',
+ severity: 'critical',
+ actor: { type: 'system', name: 'audit-retention' },
+ target: { type: 'audit_log' },
+ metadata: {
+ deletedCount,
+ before: options.before.toISOString(),
+ ...(newFirst ? { throughSeq: newFirst.seq - 1 } : {}),
+ },
+ tenantId,
+ });
+ } catch (err) {
+ logger.error('[auditLog] failed to record retention purge', {
+ chainKey,
+ deletedCount,
+ error: err instanceof Error ? err.name : 'unknown error',
+ });
+ }
+
return {
deletedCount,
/** Boundary for `verifyAuditChain`: the new earliest entry resumes the