Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📜 feat: Audit Admin Role, Group, Config and IdP Role Mutations (#17052)
Marco Berettaccae5b988def
diff --git a/api/server/experimental.js b/api/server/experimental.jsindex 1e168f404d..ee6cf8c8b7 100644--- a/api/server/experimental.js+++ b/api/server/experimental.js@@ -78,6 +78,7 @@ const {getRoleByName,updateAccessPermissions,seedDatabase,+ recordAuditEntry,sweepOrphanedPreviews,} = require('~/models');const { checkMigrations } = require('./services/start/migration');@@ -517,7 +518,12 @@ if (cluster.isMaster) {expiredFileSweep.configure({ appConfig, loadAppConfig: getAppConfig });await runAsSystem(async () => {await performStartupChecks(appConfig);- await updateInterfacePerms({ appConfig, getRoleByName, updateAccessPermissions });+ await updateInterfacePerms({+ appConfig,+ getRoleByName,+ updateAccessPermissions,+ recordAuditEntry,+ });});/* Route modules build their rate limiters as they load, so they load only after thediff --git a/api/server/index.js b/api/server/index.jsindex f98c09dfd2..535e7a46c5 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -72,6 +72,7 @@ const {sweepOrphanedPreviews,getRoleByName,seedDatabase,+ recordAuditEntry,} = require('~/models');const initializeOAuthReconnectManager = require('./services/initializeOAuthReconnectManager');const { capabilityContextMiddleware } = require('./middleware/roles/capabilities');@@ -274,7 +275,12 @@ const startServer = async () => {});await runAsSystem(async () => {await performStartupChecks(appConfig);- await updateInterfacePermissions({ appConfig, getRoleByName, updateAccessPermissions });+ await updateInterfacePermissions({+ appConfig,+ getRoleByName,+ updateAccessPermissions,+ recordAuditEntry,+ });});/* Route modules build their rate limiters as they load, so they load only after thediff --git a/api/server/routes/__tests__/roles.spec.js b/api/server/routes/__tests__/roles.spec.jsindex 0235c44a8d..a792e1c836 100644--- a/api/server/routes/__tests__/roles.spec.js+++ b/api/server/routes/__tests__/roles.spec.js@@ -3,6 +3,8 @@ const request = require('supertest');const { SystemRoles, roleDefaults } = require('librechat-data-provider');const mockGetRoleByName = jest.fn();+const mockUpdateRoleByName = jest.fn();+const mockRecordAuditEntry = jest.fn();const mockHasCapability = jest.fn();jest.mock('~/server/middleware', () => ({@@ -16,7 +18,8 @@ jest.mock('~/server/middleware/roles/capabilities', () => ({jest.mock('~/models', () => ({getRoleByName: (...args) => mockGetRoleByName(...args),- updateRoleByName: jest.fn(),+ updateRoleByName: (...args) => mockUpdateRoleByName(...args),+ recordAuditEntry: (...args) => mockRecordAuditEntry(...args),}));const rolesRouter = require('../roles');@@ -192,3 +195,36 @@ describe('GET /api/roles/:roleName — isOwnRole authorization', () => {expect(mockGetRoleByName).not.toHaveBeenCalled();});});++describe('PUT /api/roles/:roleName/prompts', () => {+ it('merges the update and records the permission change', async () => {+ mockGetRoleByName.mockResolvedValue(staffRole);+ mockUpdateRoleByName.mockImplementation(async (name, updates) => ({ name, ...updates }));+ mockRecordAuditEntry.mockResolvedValue(null);+ const app = createApp({ id: 'u1', _id: 'u1', role: SystemRoles.ADMIN, name: 'Admin' });++ const res = await request(app).put('/api/roles/STAFF/prompts').send({ CREATE: true });++ expect(res.status).toBe(200);+ expect(mockUpdateRoleByName).toHaveBeenCalledWith('STAFF', {+ permissions: { PROMPTS: { USE: true, CREATE: true } },+ });+ expect(mockRecordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.permissions_updated',+ target: { type: 'role', id: 'STAFF', name: 'STAFF' },+ metadata: { changes: 'PROMPTS.CREATE=true', changeCount: 1 },+ }),+ );+ });++ it('returns 400 for an invalid body without writing', async () => {+ const app = createApp({ id: 'u1', role: SystemRoles.ADMIN });++ const res = await request(app).put('/api/roles/STAFF/prompts').send({ CREATE: 'yes' });++ expect(res.status).toBe(400);+ expect(res.body.message).toBe('Invalid prompt permissions.');+ expect(mockUpdateRoleByName).not.toHaveBeenCalled();+ });+});diff --git a/api/server/routes/admin/config.js b/api/server/routes/admin/config.jsindex 9333495280..eafcbffdaf 100644--- a/api/server/routes/admin/config.js+++ b/api/server/routes/admin/config.js@@ -24,13 +24,15 @@ const handlers = createAdminConfigHandlers({tombstoneConfigField: db.tombstoneConfigField,unsetConfigField: db.unsetConfigField,deleteConfig: db.deleteConfig,- toggleConfigActive: db.toggleConfigActive,+ toggleConfigActiveTracked: db.toggleConfigActiveTracked,hasAnyConfigReadAccess,getReadableConfigSections,hasConfigCapability,hasCapability,getAppConfig,invalidateConfigCaches,+ recordAuditEntry: db.recordAuditEntry,+ auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',});router.use(requireJwtAuth, requireAdminAccess);diff --git a/api/server/routes/admin/groups.js b/api/server/routes/admin/groups.jsindex 11ed59737e..8ee3aefaad 100644--- a/api/server/routes/admin/groups.js+++ b/api/server/routes/admin/groups.js@@ -16,14 +16,16 @@ const handlers = createAdminGroupsHandlers({countGroups: db.countGroups,findGroupById: db.findGroupById,createGroup: db.createGroup,- updateGroupById: db.updateGroupById,+ updateGroupFieldsTracked: db.updateGroupFieldsTracked,deleteGroup: db.deleteGroup,addUserToGroup: db.addUserToGroup,removeUserFromGroup: db.removeUserFromGroup,- removeMemberById: db.removeMemberById,+ removeMemberByIdTracked: db.removeMemberByIdTracked,findUsers: db.findUsers,deleteConfig: db.deleteConfig,deleteAclEntries: db.deleteAclEntries,+ recordAuditEntry: db.recordAuditEntry,+ auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',});router.use(requireJwtAuth, requireAdminAccess);diff --git a/api/server/routes/admin/roles.js b/api/server/routes/admin/roles.jsindex de15f3d89a..47eae598b4 100644--- a/api/server/routes/admin/roles.js+++ b/api/server/routes/admin/roles.js@@ -29,7 +29,11 @@ const handlers = createAdminRolesHandlers({deleteConfig: db.deleteConfig,deleteAclEntries: db.deleteAclEntries,deleteGrantsForPrincipal: db.deleteGrantsForPrincipal,+ restoreConfig: db.restoreConfig,+ findConfigByPrincipal: db.findConfigByPrincipal,+ findGrantsForPrincipal: db.findGrantsForPrincipal,recordAuditEntry: db.recordAuditEntry,+ auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',invalidatePromptGroupAccessContext: db.invalidatePromptGroupAccessContext,});diff --git a/api/server/routes/agents/middleware.js b/api/server/routes/agents/middleware.jsindex 44f9befb1d..535de171af 100644--- a/api/server/routes/agents/middleware.js+++ b/api/server/routes/agents/middleware.js@@ -25,6 +25,7 @@ const requireRemoteAgentAuth = createRemoteAgentAuth({updateUser: db.updateUser,isPrincipalActive: db.isAgentTriggerPrincipalActive,getAppConfig,+ recordAuditEntry: db.recordAuditEntry,});const requireAgentManagementAuth = createAgentManagementAuth({diff --git a/api/server/routes/roles.js b/api/server/routes/roles.jsindex ec4c4fea11..f0ae848dac 100644--- a/api/server/routes/roles.js+++ b/api/server/routes/roles.js@@ -13,8 +13,9 @@ const {remoteAgentsPermissionsSchema,skillPermissionsSchema,} = require('librechat-data-provider');+const { createRolePermissionsUpdateHandler } = require('@librechat/api');const { hasCapability, requireCapability } = require('~/server/middleware/roles/capabilities');-const { updateRoleByName, getRoleByName } = require('~/models');+const { updateRoleByName, getRoleByName, recordAuditEntry } = require('~/models');const { requireJwtAuth } = require('~/server/middleware');const router = express.Router();@@ -73,41 +74,16 @@ const permissionConfigs = {* @param {string} permissionKey - The key from permissionConfigs* @returns {Function} Express route handler*/-const createPermissionUpdateHandler = (permissionKey) => {- const config = permissionConfigs[permissionKey];-- return async (req, res) => {- const { roleName } = req.params;- const updates = req.body;-- try {- const parsedUpdates = config.schema.partial().parse(updates);-- const role = await getRoleByName(roleName);- if (!role) {- return res.status(404).send({ message: 'Role not found' });- }-- const currentPermissions =- role.permissions?.[config.permissionType] || role[config.permissionType] || {};-- const mergedUpdates = {- permissions: {- ...role.permissions,- [config.permissionType]: {- ...currentPermissions,- ...parsedUpdates,- },- },- };-- const updatedRole = await updateRoleByName(roleName, mergedUpdates);- res.status(200).send(updatedRole);- } catch (error) {- return res.status(400).send({ message: config.errorMessage, error: error.errors });- }- };-};+const createPermissionUpdateHandler = (permissionKey) =>+ createRolePermissionsUpdateHandler(+ {+ getRoleByName,+ updateRoleByName,+ recordAuditEntry,+ auditFailClosed: process.env.AUDIT_LOG_FAIL_CLOSED === 'true',+ },+ permissionConfigs[permissionKey],+ );/*** GET /api/roles/:roleNamediff --git a/api/strategies/openidStrategy.js b/api/strategies/openidStrategy.jsindex 99ad2b0c89..02c09f11b0 100644--- a/api/strategies/openidStrategy.js+++ b/api/strategies/openidStrategy.js@@ -17,6 +17,7 @@ const {getBalanceConfig,selectOpenIdRole,getTokenCacheTtlMs,+ recordIdpRoleChange,applyOpenIDProfile,getAvatarSaveParams,isEmailDomainAllowed,@@ -35,6 +36,7 @@ const {updateUser,findRolesByNames,findBalanceByUser,+ recordAuditEntry,createUserIfAbsent,} = require('~/models');const { getAppConfig } = require('~/server/services/Config');@@ -709,6 +711,7 @@ async function processOpenIDAuth(tokenset, existingUsersOnly = false) {user = applyOpenIDProfile(user, profile);}+ const roleBeforeClaims = user.role;const adminRole = process.env.OPENID_ADMIN_ROLE;const adminRoleParameterPath = process.env.OPENID_ADMIN_ROLE_PARAMETER_PATH;const adminRoleTokenKind = process.env.OPENID_ADMIN_ROLE_TOKEN_KIND;@@ -817,6 +820,14 @@ async function processOpenIDAuth(tokenset, existingUsersOnly = false) {}user = await updateUser(user._id, user);+ await recordIdpRoleChange({+ recordAuditEntry,+ userId: String(user._id),+ previousRole: roleBeforeClaims,+ role: user.role,+ source: 'openid_login',+ tenantId: user.tenantId,+ });logger.info(`[openidStrategy] login success openidId: ${user.openidId} | email: ${user.email} | username: ${user.username} `,diff --git a/e2e/specs/mock/scenarios/admin-role-audit.spec.ts b/e2e/specs/mock/scenarios/admin-role-audit.spec.tsnew file mode 100644index 0000000000..b6b13e3317--- /dev/null+++ b/e2e/specs/mock/scenarios/admin-role-audit.spec.ts@@ -0,0 +1,127 @@+import { expect, test } from '@playwright/test';+import type { APIRequestContext } from '@playwright/test';+import { getPrimaryE2EUser } from '../../../setup/users.mock';+import cleanupUser from '../../../setup/cleanupUser';++/**+ * Admin role mutations leave audit entries an operator can read back. The primary user+ * (first registered, ADMIN) creates, edits and deletes a role this file owns, then reads+ * the audit log filtered by the role name.+ */++type AuditEntry = { action: string; outcome: string; target?: { id?: string; name?: string } };++async function adminHeaders(request: APIRequestContext): Promise<Record<string, string>> {+ const user = getPrimaryE2EUser();+ const res = await request.post('/api/auth/login', {+ data: { email: user.email, password: user.password },+ });+ expect(res.ok()).toBeTruthy();+ const { token } = (await res.json()) as { token: string };+ expect(token).toBeTruthy();+ return { Authorization: `Bearer ${token}` };+}++async function auditActions(+ request: APIRequestContext,+ headers: Record<string, string>,+ roleName: string,+): Promise<string[]> {+ const res = await request.get('/api/admin/audit-log', {+ headers,+ params: { search: roleName, limit: 50 },+ });+ expect(res.ok()).toBeTruthy();+ const { entries } = (await res.json()) as { entries: AuditEntry[] };+ return entries.filter((e) => JSON.stringify(e).includes(roleName)).map((e) => e.action);+}++test.describe('admin role audit trail', () => {+ test('creating, editing and deleting a role is recorded in the audit log @scenario:role-lifecycle-is-audited', async ({+ playwright,+ baseURL,+ }) => {+ const request = await playwright.request.newContext({ baseURL });+ const roleName = `audit-role-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;+ try {+ const headers = await adminHeaders(request);++ const created = await request.post('/api/admin/roles', { headers, data: { name: roleName } });+ expect(created.status()).toBe(201);++ const updated = await request.patch(`/api/admin/roles/${roleName}`, {+ headers,+ data: { description: 'audited role' },+ });+ expect(updated.ok()).toBeTruthy();++ const deleted = await request.delete(`/api/admin/roles/${roleName}`, { headers });+ expect(deleted.ok()).toBeTruthy();++ const actions = await auditActions(request, headers, roleName);+ expect(actions).toEqual(+ expect.arrayContaining(['role.created', 'role.updated', 'role.deleted']),+ );+ } finally {+ await request.dispose();+ }+ });++ test('a rejected role mutation leaves no created entry @scenario:rejected-role-create-is-not-audited', async ({+ playwright,+ baseURL,+ }) => {+ const request = await playwright.request.newContext({ baseURL });+ const roleName = `audit-dup-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;+ try {+ const headers = await adminHeaders(request);+ const first = await request.post('/api/admin/roles', { headers, data: { name: roleName } });+ expect(first.status()).toBe(201);+ const duplicate = await request.post('/api/admin/roles', {+ headers,+ data: { name: roleName },+ });+ expect(duplicate.status()).toBe(409);++ const actions = await auditActions(request, headers, roleName);+ expect(actions.filter((a) => a === 'role.created')).toHaveLength(1);++ await request.delete(`/api/admin/roles/${roleName}`, { headers });+ } finally {+ await request.dispose();+ }+ });++ test('a non-admin user cannot read the audit log or manage roles @scenario:non-admin-denied-role-and-audit-endpoints', async ({+ playwright,+ baseURL,+ }) => {+ const request = await playwright.request.newContext({ baseURL });+ const user = {+ email: `audit-nonadmin-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`,+ name: 'Audit Non Admin',+ password: 'securepassword789',+ };+ try {+ const register = await request.post('/api/auth/register', {+ data: { ...user, confirm_password: user.password },+ });+ expect(register.ok()).toBeTruthy();+ const login = await request.post('/api/auth/login', {+ data: { email: user.email, password: user.password },+ });+ const { token } = (await login.json()) as { token: string };+ const headers = { Authorization: `Bearer ${token}` };++ expect((await request.get('/api/admin/audit-log', { headers })).status()).toBe(403);+ const create = await request.post('/api/admin/roles', {+ headers,+ data: { name: 'audit-denied' },+ });+ expect(create.status()).toBe(403);+ } finally {+ await request.dispose();+ await cleanupUser(user);+ }+ });+});diff --git a/packages/api/src/admin/audit.spec.ts b/packages/api/src/admin/audit.spec.tsnew file mode 100644index 0000000000..b565bf488b--- /dev/null+++ b/packages/api/src/admin/audit.spec.ts@@ -0,0 +1,29 @@+import type { RecordAuditEntryInput } from '@librechat/data-schemas';+import { recordSystemAuditEntry } from './audit';++const input = { action: 'role.synced' } as unknown as RecordAuditEntryInput;++describe('recordSystemAuditEntry', () => {+ it('returns without waiting for the audit store', async () => {+ const record = jest.fn(() => new Promise<never>(() => undefined));++ await recordSystemAuditEntry(record, input, '[test]');++ expect(record).toHaveBeenCalledWith(input);+ });++ it('swallows a rejected or throwing write', async () => {+ await expect(+ recordSystemAuditEntry(jest.fn().mockRejectedValue(new Error('down')), input, '[test]'),+ ).resolves.toBeUndefined();+ await expect(+ recordSystemAuditEntry(+ jest.fn(() => {+ throw new Error('sync');+ }),+ input,+ '[test]',+ ),+ ).resolves.toBeUndefined();+ });+});diff --git a/packages/api/src/admin/audit.ts b/packages/api/src/admin/audit.tsnew file mode 100644index 0000000000..e3df2b7d68--- /dev/null+++ b/packages/api/src/admin/audit.ts@@ -0,0 +1,124 @@+import { logger } from '@librechat/data-schemas';+import type {+ AuditActorInput,+ RecordAuditEntryInput,+ RecordAuditEntryOptions,+} from '@librechat/data-schemas';+import type { ServerRequest } from '~/types/http';+import { getSafeErrorMetadata } from '~/utils/errors';+import { buildAuditContext } from './context';++/** The `recordAuditEntry` data-schemas method, as handler factories receive it. */+export type RecordAuditEntry = (+ input: RecordAuditEntryInput,+ options?: RecordAuditEntryOptions,+) => Promise<unknown>;++/** An audit entry minus the parts derived from the request (actor, context). */+export type AdminAuditEvent = Omit<RecordAuditEntryInput, 'actor' | 'context'>;++export type AdminAuditEmitter = (req: ServerRequest, event: AdminAuditEvent) => Promise<void>;++/** Resolves the authenticated caller as an audit actor; null when unauthenticated. */+export function getAuditActor(req: ServerRequest): AuditActorInput | null {+ const user = req.user;+ const userId = user?._id?.toString() ?? user?.id;+ if (!user || !userId) {+ return null;+ }+ return { type: 'user', id: userId, name: user.name || user.username || user.email || userId };+}++/**+ * Builds the audit writer shared by the admin handler factories. The caller is+ * the actor and the request supplies forensic context; `tenantId` defaults to+ * the caller's tenant unless the event sets the key (even to `undefined`, which+ * routes the entry to the platform chain).+ *+ * Fail-open by default: a failed write is logged and the already-persisted+ * mutation stands. With `failClosed`, the write error propagates so the+ * handler's catch turns it into a 5xx.+ */+export function createAdminAuditEmitter(options: {+ recordAuditEntry?: RecordAuditEntry;+ failClosed?: boolean;+ logPrefix: string;+}): AdminAuditEmitter {+ const { recordAuditEntry, failClosed, logPrefix } = options;+ return async function emitAdminAudit(req, event) {+ if (!recordAuditEntry) {+ return;+ }+ const actor = getAuditActor(req);+ if (!actor) {+ return;+ }+ const input: RecordAuditEntryInput = {+ ...event,+ actor,+ context: buildAuditContext(req),+ tenantId: 'tenantId' in event ? event.tenantId : req.user?.tenantId,+ };+ if (failClosed) {+ await recordAuditEntry(input, { failClosed: true });+ return;+ }+ try {+ await recordAuditEntry(input);+ } catch (err) {+ logger.error(+ `${logPrefix} audit write failed for ${event.action}`,+ getSafeErrorMetadata(err),+ );+ }+ };+}++/**+ * Writes an entry for a change no request initiated (startup sync, IdP sync).+ * Always fail-open: these paths run during startup or login and must not be+ * blocked by the audit store.+ */+export async function recordSystemAuditEntry(+ recordAuditEntry: RecordAuditEntry | undefined,+ input: RecordAuditEntryInput,+ logPrefix: string,+): Promise<void> {+ if (!recordAuditEntry) {+ return;+ }+ const logFailure = (err: unknown) =>+ logger.error(`${logPrefix} audit write failed for ${input.action}`, getSafeErrorMetadata(err));+ /** Dispatched without being awaited: login and startup must not wait on the audit store. */+ try {+ Promise.resolve(recordAuditEntry(input)).catch(logFailure);+ } catch (err) {+ logFailure(err);+ }+}++type PermissionMap = Record<string, Record<string, boolean | undefined> | undefined>;++/**+ * Lists the permission flags that differ between two role permission maps as+ * sorted `TYPE.FIELD=value` strings, so an audit entry records what changed+ * without storing the whole role document.+ */+export function diffRolePermissions(+ before: PermissionMap | undefined,+ after: PermissionMap | undefined,+): string[] {+ const changes: string[] = [];+ const types = new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);+ for (const type of types) {+ const prev = before?.[type] ?? {};+ const next = after?.[type] ?? {};+ const fields = new Set([...Object.keys(prev), ...Object.keys(next)]);+ for (const field of fields) {+ if (prev[field] !== next[field]) {+ changes.push(`${type}.${field}=${String(next[field])}`);+ }+ }+ }+ return changes.sort();+}diff --git a/packages/api/src/admin/cascade.spec.ts b/packages/api/src/admin/cascade.spec.tsnew file mode 100644index 0000000000..933b56133a--- /dev/null+++ b/packages/api/src/admin/cascade.spec.ts@@ -0,0 +1,105 @@+import { cascadeStep, runCascade } from './cascade';++describe('runCascade', () => {+ it('reports failed steps and restores only the steps that were removed', async () => {+ const restoreA = jest.fn().mockResolvedValue(undefined);+ const restoreB = jest.fn().mockResolvedValue(undefined);+ const outcome = await runCascade(+ [+ cascadeStep('a', async () => ['x'], restoreA),+ cascadeStep('b', async () => Promise.reject(new Error('boom')), restoreB),+ ],+ '[test]',+ );++ expect(outcome.failed).toEqual(['b']);+ await outcome.compensate();+ expect(restoreA).toHaveBeenCalledWith(['x']);+ expect(restoreB).not.toHaveBeenCalled();+ });++ it('keeps restoring when one restore throws', async () => {+ const restoreB = jest.fn().mockResolvedValue(undefined);+ const outcome = await runCascade(+ [+ cascadeStep(+ 'a',+ async () => 1,+ async () => Promise.reject(new Error('restore failed')),+ ),+ cascadeStep('b', async () => 2, restoreB),+ ],+ '[test]',+ );++ await expect(outcome.compensate()).resolves.toBeUndefined();+ expect(restoreB).toHaveBeenCalledWith(2);+ });++ it('restores a snapshot immediately when a removal rejects after committing', async () => {+ const restore = jest.fn().mockResolvedValue(undefined);+ const outcome = await runCascade(+ [+ cascadeStep(+ 'a',+ async () => Promise.reject(new Error('response lost')),+ restore,+ async () => ['before'],+ ),+ ],+ '[test]',+ );++ expect(outcome.failed).toEqual(['a']);+ expect(restore).toHaveBeenCalledWith(['before']);+ });++ it('retries a snapshot restore that failed transiently when compensating', async () => {+ const restore = jest+ .fn()+ .mockRejectedValueOnce(new Error('transient'))+ .mockResolvedValue(undefined);+ const outcome = await runCascade(+ [+ cascadeStep(+ 'a',+ async () => Promise.reject(new Error('response lost')),+ restore,+ async () => 'snap',+ ),+ ],+ '[test]',+ );++ expect(restore).toHaveBeenCalledTimes(1);+ await outcome.compensate();+ expect(restore).toHaveBeenCalledTimes(2);+ expect(restore).toHaveBeenLastCalledWith('snap');+ });++ it('compensates from what the removal returned, falling back to the snapshot', async () => {+ const restoreReturned = jest.fn().mockResolvedValue(undefined);+ const restoreVoid = jest.fn().mockResolvedValue(undefined);+ const outcome = await runCascade(+ [+ cascadeStep(+ 'a',+ async () => 'removed',+ restoreReturned,+ async () => 'snapshot',+ ),+ cascadeStep(+ 'b',+ async (): Promise<void> => undefined,+ restoreVoid,+ async () => 'snapshot',+ ),+ ],+ '[test]',+ );++ await outcome.compensate();+ expect(restoreReturned).toHaveBeenCalledWith('removed');+ expect(restoreVoid).toHaveBeenCalledWith('snapshot');+ });+});diff --git a/packages/api/src/admin/cascade.ts b/packages/api/src/admin/cascade.tsnew file mode 100644index 0000000000..00155c3843--- /dev/null+++ b/packages/api/src/admin/cascade.ts@@ -0,0 +1,115 @@+import { logger } from '@librechat/data-schemas';+import { getSafeErrorMetadata } from '~/utils/errors';++/** One removal in a delete cascade, with the way to put back what it removed. */+export interface CascadeStep {+ name: string;+ /** Reads the dependents before they are removed. When supplied, a removal that+ * rejects (it may still have committed) is restored from it immediately. It is also+ * what `restore` receives later when the removal returned nothing. */+ snapshot?: () => Promise<unknown>;+ /** Removes the dependents and returns whatever is needed to restore them. */+ remove: () => Promise<unknown>;+ /** Re-creates the removed dependents; omitted when the step cannot be undone. */+ restore?: (removed: unknown) => Promise<void>;+}++export interface CascadeOutcome {+ /** Names of the steps whose removal threw. */+ failed: string[];+ /** Each fulfilled step's `remove` result, by step name. */+ removed: Record<string, unknown>;+ /** Best-effort restore of every fulfilled step; failures are logged, never thrown. */+ compensate: () => Promise<void>;+}++/** Builds a typed step; `restore` receives the snapshot when one is given, else what `remove` returned. */+export function cascadeStep<T, S = T>(+ name: string,+ remove: () => Promise<T>,+ restore?: (restoreFrom: S) => Promise<void>,+ snapshot?: () => Promise<S>,+): CascadeStep {+ return {+ name,+ snapshot,+ remove,+ restore: restore ? (restoreFrom) => restore(restoreFrom as S) : undefined,+ };+}++/**+ * Runs the removals concurrently and reports which failed. When the caller cannot+ * finish the delete (a step failed, or the parent record could not be deleted), it+ * calls `compensate` so the dependents are put back instead of orphaning a parent+ * that still exists.+ */+export async function runCascade(steps: CascadeStep[], logPrefix: string): Promise<CascadeOutcome> {+ const restoreArgs: Record<string, unknown> = {};++ /** Steps whose immediate restore failed; `compensate` tries them again. */+ const unrestored: Array<{ step: CascadeStep; arg: unknown }> = [];++ async function restoreStep(step: CascadeStep, arg: unknown): Promise<boolean> {+ if (!step.restore) {+ return true;+ }+ try {+ await step.restore(arg);+ return true;+ } catch (error) {+ logger.error(+ `${logPrefix} cascade restore failed: ${step.name}`,+ getSafeErrorMetadata(error),+ );+ return false;+ }+ }++ async function run(step: CascadeStep): Promise<unknown> {+ const snapshot = step.snapshot ? await step.snapshot() : undefined;+ let value: unknown;+ try {+ value = await step.remove();+ } catch (error) {+ /** The removal may have committed before it rejected; put the snapshot back. */+ if (step.snapshot && !(await restoreStep(step, snapshot))) {+ unrestored.push({ step, arg: snapshot });+ }+ throw error;+ }+ /** What the removal actually returned beats the earlier snapshot, which may predate a+ * concurrent write; the snapshot covers steps that return nothing. */+ restoreArgs[step.name] = value !== undefined ? value : snapshot;+ return value;+ }++ const settled = await Promise.allSettled(steps.map(run));+ const failed: string[] = [];+ const removed: Record<string, unknown> = {};+ settled.forEach((result, index) => {+ const { name } = steps[index];+ if (result.status === 'rejected') {+ failed.push(name);+ logger.error(+ `${logPrefix} cascade step failed: ${name}`,+ getSafeErrorMetadata(result.reason),+ );+ return;+ }+ removed[name] = result.value;+ });++ async function compensate(): Promise<void> {+ for (const { step, arg } of unrestored) {+ await restoreStep(step, arg);+ }+ for (const step of steps) {+ if (step.name in removed) {+ await restoreStep(step, restoreArgs[step.name]);+ }+ }+ }++ return { failed, removed, compensate };+}diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.tsindex 88cbcd0cbe..b19aa8edd1 100644--- a/packages/api/src/admin/config.handler.spec.ts+++ b/packages/api/src/admin/config.handler.spec.ts@@ -68,7 +68,9 @@ function createHandlers(overrides = {}) {.mockResolvedValue({ _id: 'c1', tombstones: ['mcpServers.github'] }),unsetConfigField: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {} }),deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1' }),- toggleConfigActive: jest.fn().mockResolvedValue({ _id: 'c1', isActive: false }),+ toggleConfigActiveTracked: jest+ .fn()+ .mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: true }),hasConfigCapability: jest.fn().mockResolvedValue(true),hasAnyConfigReadAccess: jest.fn().mockResolvedValue(true),hasCapability: jest.fn().mockResolvedValue(true),@@ -1860,7 +1862,7 @@ describe('createAdminConfigHandlers', () => {await handlers.toggleConfig(req, res);expect(res.statusCode).toBe(200);- expect(deps.toggleConfigActive).toHaveBeenCalled();+ expect(deps.toggleConfigActiveTracked).toHaveBeenCalled();});it('rejects toggle when caller has neither broad manage nor ASSIGN_CONFIGS', async () => {@@ -1877,7 +1879,7 @@ describe('createAdminConfigHandlers', () => {await handlers.toggleConfig(req, res);expect(res.statusCode).toBe(403);- expect(deps.toggleConfigActive).not.toHaveBeenCalled();+ expect(deps.toggleConfigActiveTracked).not.toHaveBeenCalled();});});@@ -1991,7 +1993,7 @@ describe('createAdminConfigHandlers', () => {await handlers.toggleConfig(req, res);expect(res.statusCode).toBe(403);- expect(deps.toggleConfigActive).not.toHaveBeenCalled();+ expect(deps.toggleConfigActiveTracked).not.toHaveBeenCalled();});it('upsert against __base__ succeeds for broad-manage caller', async () => {@@ -2134,8 +2136,10 @@ describe('createAdminConfigHandlers', () => {const { handlers, deps } = createHandlers({hasConfigCapability: jest.fn().mockResolvedValue(false),hasCapability: jest.fn().mockResolvedValue(true),- toggleConfigActive: jest.fn(async (_pt, _pi, _isActive, _session, opts) => {- return opts?.expectEmpty ? null : { _id: 'c1', isActive: false };+ toggleConfigActiveTracked: jest.fn(async (_pt, _pi, _isActive, opts) => {+ return opts?.expectEmpty+ ? null+ : { config: { _id: 'c1', isActive: false }, changed: true };}),findConfigByPrincipal: jest.fn().mockResolvedValue({_id: 'c1',@@ -2151,11 +2155,10 @@ describe('createAdminConfigHandlers', () => {await handlers.toggleConfig(req, res);expect(res.statusCode).toBe(403);- expect(deps.toggleConfigActive).toHaveBeenCalledWith(+ expect(deps.toggleConfigActiveTracked).toHaveBeenCalledWith(expect.anything(),expect.anything(),expect.anything(),- undefined,{ expectEmpty: true },);});@@ -2229,7 +2232,10 @@ describe('createAdminConfigHandlers', () => {tombstoneConfigField: jest.fn(),unsetConfigField: jest.fn(),deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1' }),- toggleConfigActive: jest.fn().mockResolvedValue({ _id: 'c1', isActive: false }),+ /** The document as it was before the write. */+ toggleConfigActiveTracked: jest+ .fn()+ .mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: true }),hasConfigCapability: jest.fn().mockResolvedValue(false),};const handlers = createAdminConfigHandlers(deps);@@ -2577,4 +2583,202 @@ describe('createAdminConfigHandlers', () => {expect(deps.patchConfigFields).toHaveBeenCalledTimes(1);});});++ describe('audit entries', () => {+ const target = { type: 'config', id: 'role:editor', name: 'role:editor' };+ const params = { principalType: 'role', principalId: 'editor' };++ it('records a partial secret-field delete when the preview write fails', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ invalidateConfigCaches,+ unsetConfigField: jest+ .fn()+ .mockResolvedValueOnce({ _id: 'c1', overrides: {} })+ .mockRejectedValueOnce(new Error('preview write failed')),+ });+ const req = mockReq({ params, query: { fieldPath: 'ocr.apiKey' } });+ const res = mockRes();++ await handlers.deleteConfigField(req, res);++ expect(res.statusCode).toBe(500);+ expect(invalidateConfigCaches).toHaveBeenCalled();+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'config.updated',+ target,+ metadata: { operation: 'unset', fieldPath: 'ocr.apiKey', partial: true },+ }),+ );+ });++ it('records config.created for a new override document', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1, priority: 10 }),+ });+ const req = mockReq({+ params,+ body: { overrides: { interface: { modelSelect: false } } },+ });+ const res = mockRes();++ await handlers.upsertConfigOverrides(req, res);++ expect(res.statusCode).toBe(201);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'config.created',+ actor: expect.objectContaining({ type: 'user', id: 'u1' }),+ target,+ metadata: { operation: 'replace', sections: 'interface', priority: 10 },+ }),+ );+ });++ it('records config.updated for a patch with field paths but no values', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ findConfigByPrincipal: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {} }),+ });+ const req = mockReq({+ params,+ body: { entries: [{ fieldPath: 'registration.enabled', value: false }] },+ });+ const res = mockRes();++ await handlers.patchConfigField(req, res);++ expect(res.statusCode).toBe(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'config.updated',+ target,+ metadata: { operation: 'patch', fieldPaths: 'registration.enabled' },+ }),+ );+ });++ it('records config.created when the first tombstone creates the document', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ tombstoneConfigField: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),+ });+ const res = mockRes();++ await handlers.tombstoneConfigField(+ mockReq({ params, body: { fieldPath: 'mcpServers.github' } }),+ res,+ );++ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({ action: 'config.created' }),+ );+ });++ it('records tombstone and unset field operations', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({ recordAuditEntry });++ const tombstoneRes = mockRes();+ await handlers.tombstoneConfigField(+ mockReq({ params, body: { fieldPath: 'mcpServers.github' } }),+ tombstoneRes,+ );+ const unsetRes = mockRes();+ await handlers.deleteConfigField(+ mockReq({ params, query: { fieldPath: 'registration.enabled' } }),+ unsetRes,+ );++ expect(tombstoneRes.statusCode).toBe(200);+ expect(unsetRes.statusCode).toBe(200);+ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({+ action: 'config.updated',+ metadata: { operation: 'tombstone', fieldPath: 'mcpServers.github' },+ }),+ );+ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({+ action: 'config.updated',+ metadata: { operation: 'unset', fieldPath: 'registration.enabled' },+ }),+ );+ });++ it('records config.deleted and config.toggled', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({ recordAuditEntry });++ await handlers.deleteConfigOverrides(mockReq({ params }), mockRes());+ await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), mockRes());++ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({ action: 'config.deleted', target }),+ );+ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({+ action: 'config.toggled',+ target,+ metadata: { isActive: false },+ }),+ );+ });++ it('does not record a toggle that leaves isActive unchanged', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ toggleConfigActiveTracked: jest+ .fn()+ .mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: false }),+ });+ const res = mockRes();++ await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), res);++ expect(res.statusCode).toBe(200);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not record when the override document is missing', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ deleteConfig: jest.fn().mockResolvedValue(null),+ });+ const res = mockRes();++ await handlers.deleteConfigOverrides(mockReq({ params }), res);++ expect(res.statusCode).toBe(404);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not record a denied mutation', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({+ recordAuditEntry,+ hasConfigCapability: jest.fn().mockResolvedValue(false),+ hasCapability: jest.fn().mockResolvedValue(false),+ });+ const res = mockRes();++ await handlers.toggleConfig(mockReq({ params, body: { isActive: true } }), res);++ expect(res.statusCode).toBe(403);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+ });});diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.tsindex ddeaffe0e1..6ff2567032 100644--- a/packages/api/src/admin/config.ts+++ b/packages/api/src/admin/config.ts@@ -27,6 +27,7 @@ import type {import type { TCustomConfig } from 'librechat-data-provider';import type { Types, ClientSession } from 'mongoose';import type { Response } from 'express';+import type { AdminAuditEvent, RecordAuditEntry } from './audit';import type { CapabilityUser } from '~/middleware/capabilities';import type { ServerRequest } from '~/types/http';import {@@ -41,6 +42,8 @@ import {preserveConfigSecrets,redactConfigSecrets,} from './secrets';+import { getSafeErrorMetadata } from '~/utils/errors';+import { createAdminAuditEmitter } from './audit';const UNSAFE_SEGMENTS = /(?:^|\.)(__[\w]*|constructor|prototype)(?:\.|$)/;const MAX_PATCH_ENTRIES = 100;@@ -223,13 +226,13 @@ export interface AdminConfigDeps {session?: ClientSession,options?: { expectEmpty?: boolean },) => Promise<IConfig | null>;- toggleConfigActive: (+ /** Resolves to the post-write document and whether this write changed `isActive`. */+ toggleConfigActiveTracked: (principalType: PrincipalType,principalId: string | Types.ObjectId,isActive: boolean,- session?: ClientSession,options?: { expectEmpty?: boolean },- ) => Promise<IConfig | null>;+ ) => Promise<{ config: IConfig; changed: boolean } | null>;hasConfigCapability: (user: CapabilityUser,section: ConfigSection | null,@@ -251,6 +254,18 @@ export interface AdminConfigDeps {}) => Promise<AppConfig>;/** Invalidate all config-related caches after a mutation. */invalidateConfigCaches?: (tenantId?: string) => Promise<void>;+ /** Optional audit emission for override mutations; fail-open unless `auditFailClosed`. */+ recordAuditEntry?: RecordAuditEntry;+ /** When true, a failed audit write surfaces as a 5xx after the mutation has+ * been persisted. Defaults to fail-open. */+ auditFailClosed?: boolean;+}++/** Audit target for a principal's override document. Records field paths and+ * sections only: override values can carry secrets. */+function configTarget(principalType: string, principalId: string): AdminAuditEvent['target'] {+ const key = `${principalType}:${principalId}`;+ return { type: 'config', id: key, name: key };}// ── Validation helpers ───────────────────────────────────────────────@@ -466,7 +481,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {tombstoneConfigField: writeConfigTombstone,unsetConfigField,deleteConfig,- toggleConfigActive,+ toggleConfigActiveTracked,hasConfigCapability,hasAnyConfigReadAccess = async () => false,getReadableConfigSections = async (u, sections) => {@@ -481,8 +496,16 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {hasCapability = async () => false,getAppConfig,invalidateConfigCaches,+ recordAuditEntry,+ auditFailClosed,} = deps;+ const emitAudit = createAdminAuditEmitter({+ recordAuditEntry,+ failClosed: auditFailClosed,+ logPrefix: '[adminConfig]',+ });+/** The deployment's `librechat.yaml` config, which overrides are validated on top of. */async function getBaseYamlConfig(tenantId?: string): Promise<Partial<TCustomConfig>> {if (!getAppConfig) {@@ -514,7 +537,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const safeConfigs = filtered.map(redactConfigForResponse);return res.status(200).json({ configs: safeConfigs });} catch (error) {- logger.error('[adminConfig] listConfigs error:', error);+ logger.error('[adminConfig] listConfigs error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to list configs' });}}@@ -549,7 +572,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(200).json({ config: redactAppConfigForResponse(filteredAppConfig) });} catch (error) {- logger.error('[adminConfig] getBaseConfig error:', error);+ logger.error('[adminConfig] getBaseConfig error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get base config' });}}@@ -590,7 +613,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(200).json({ config: redactConfigForResponse(filteredConfig) });} catch (error) {- logger.error('[adminConfig] getConfig error:', error);+ logger.error('[adminConfig] getConfig error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get config' });}}@@ -800,11 +823,22 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after upsert:', err),);+ if (config) {+ await emitAudit(req, {+ action: config.configVersion === 1 ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: {+ operation: 'replace',+ sections: overrideSections.join(','),+ priority: config.priority,+ },+ });+ }return res.status(config?.configVersion === 1 ? 201 : 200).json({config: config ? redactConfigForResponse(config) : config,});} catch (error) {- logger.error('[adminConfig] upsertConfigOverrides error:', error);+ logger.error('[adminConfig] upsertConfigOverrides error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to upsert config' });}}@@ -970,9 +1004,16 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after patch:', err),);+ if (config) {+ await emitAudit(req, {+ action: config.configVersion === 1 ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'patch', fieldPaths: Object.keys(fields).join(',') },+ });+ }return res.status(200).json({ config: config ? redactConfigForResponse(config) : config });} catch (error) {- logger.error('[adminConfig] patchConfigField error:', error);+ logger.error('[adminConfig] patchConfigField error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to patch config fields' });}}@@ -1067,25 +1108,53 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {: null;let config: IConfig | null = null;- for (const path of getConfigSecretMutationPaths(fieldPath)) {- const fieldConfig = await writeConfigTombstone(- principalType,- principalId,- principalModel(principalType),- path,- requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,- );- if (fieldConfig) {- config = fieldConfig;+ /** Each write bumps configVersion, so creation is read off the first write only. */+ let created = false;+ try {+ for (const path of getConfigSecretMutationPaths(fieldPath)) {+ const fieldConfig = await writeConfigTombstone(+ principalType,+ principalId,+ principalModel(principalType),+ path,+ requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,+ );+ if (fieldConfig) {+ created ||= config == null && fieldConfig.configVersion === 1;+ config = fieldConfig;+ }}+ } catch (writeError) {+ /** An earlier path in the loop may already have been written. */+ if (config) {+ invalidateConfigCaches?.(user.tenantId)?.catch((err) =>+ logger.error(+ '[adminConfig] Cache invalidation failed after partial write:',+ getSafeErrorMetadata(err),+ ),+ );+ await emitAudit(req, {+ action: created ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'tombstone', fieldPath, partial: true },+ });+ }+ throw writeError;}invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after field tombstone:', err),);+ if (config) {+ await emitAudit(req, {+ action: created ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'tombstone', fieldPath },+ });+ }return res.status(200).json({ config: config ? redactConfigForResponse(config) : config });} catch (error) {- logger.error('[adminConfig] tombstoneConfigField error:', error);+ logger.error('[adminConfig] tombstoneConfigField error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to tombstone config field' });}}@@ -1161,11 +1230,29 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}let config: IConfig | null = null;- for (const path of getConfigSecretMutationPaths(fieldPath)) {- const fieldConfig = await unsetConfigField(principalType, principalId, path);- if (fieldConfig) {- config = fieldConfig;+ try {+ for (const path of getConfigSecretMutationPaths(fieldPath)) {+ const fieldConfig = await unsetConfigField(principalType, principalId, path);+ if (fieldConfig) {+ config = fieldConfig;+ }}+ } catch (writeError) {+ /** An earlier path in the loop may already have been written. */+ if (config) {+ invalidateConfigCaches?.(user.tenantId)?.catch((err) =>+ logger.error(+ '[adminConfig] Cache invalidation failed after partial write:',+ getSafeErrorMetadata(err),+ ),+ );+ await emitAudit(req, {+ action: 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'unset', fieldPath, partial: true },+ });+ }+ throw writeError;}if (!config) {return res.status(404).json({ error: 'Config not found' });@@ -1174,9 +1261,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after field delete:', err),);+ await emitAudit(req, {+ action: 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'unset', fieldPath },+ });return res.status(200).json({ config: redactConfigForResponse(config) });} catch (error) {- logger.error('[adminConfig] deleteConfigField error:', error);+ logger.error('[adminConfig] deleteConfigField error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to delete config field' });}}@@ -1231,9 +1323,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after config delete:', err),);+ await emitAudit(req, {+ action: 'config.deleted',+ severity: 'warning',+ target: configTarget(principalType, principalId),+ });return res.status(200).json({ success: true });} catch (error) {- logger.error('[adminConfig] deleteConfigOverrides error:', error);+ logger.error('[adminConfig] deleteConfigOverrides error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to delete config' });}}@@ -1275,10 +1372,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(403).json({ error: 'Insufficient permissions' });}- const config = await toggleConfigActive(principalType, principalId, isActive, undefined, {+ const toggled = await toggleConfigActiveTracked(principalType, principalId, isActive, {expectEmpty: !hasBroadManage,});- if (!config) {+ if (!toggled) {if (!hasBroadManage) {const exists = await findConfigByPrincipal(principalType, principalId, {includeInactive: true,@@ -1290,12 +1387,22 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(404).json({ error: 'Config not found' });}+ const { config, changed } = toggled;invalidateConfigCaches?.(user.tenantId)?.catch((err) =>logger.error('[adminConfig] Cache invalidation failed after toggle:', err),);+ /** A retry that finds the requested state already set changed nothing and is not recorded. */+ if (changed) {+ await emitAudit(req, {+ action: 'config.toggled',+ severity: 'warning',+ target: configTarget(principalType, principalId),+ metadata: { isActive },+ });+ }return res.status(200).json({ config: redactConfigForResponse(config) });} catch (error) {- logger.error('[adminConfig] toggleConfig error:', error);+ logger.error('[adminConfig] toggleConfig error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to toggle config' });}}diff --git a/packages/api/src/admin/groups.spec.ts b/packages/api/src/admin/groups.spec.tsindex d10dfda7e0..cb395b1a7d 100644--- a/packages/api/src/admin/groups.spec.ts+++ b/packages/api/src/admin/groups.spec.ts@@ -68,11 +68,19 @@ describe('createAdminGroupsHandlers', () => {countGroups: jest.fn().mockResolvedValue(0),findGroupById: jest.fn().mockResolvedValue(null),createGroup: jest.fn().mockResolvedValue(mockGroup()),- updateGroupById: jest.fn().mockResolvedValue(mockGroup()),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: mockGroup(), changed: true, changedFields: ['name'] }),deleteGroup: jest.fn().mockResolvedValue(mockGroup()),- addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),- removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),- removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ addUserToGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group: mockGroup(), changed: true }),+ removeUserFromGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group: mockGroup(), changed: true }),+ removeMemberByIdTracked: jest+ .fn()+ .mockResolvedValue({ group: mockGroup(), changed: true, changedFields: ['name'] }),findUsers: jest.fn().mockResolvedValue([]),deleteConfig: jest.fn().mockResolvedValue(null),deleteAclEntries: jest.fn().mockResolvedValue({ deletedCount: 0 }),@@ -492,7 +500,14 @@ describe('createAdminGroupsHandlers', () => {it('updates group and returns 200', async () => {const group = mockGroup({ name: 'Updated' });const deps = createDeps({- updateGroupById: jest.fn().mockResolvedValue(group),+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: group, changed: true, changedFields: ['name'] }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -508,7 +523,16 @@ describe('createAdminGroupsHandlers', () => {it('updates description only', async () => {const group = mockGroup({ description: 'New desc' });- const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const deps = createDeps({+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: group, changed: true, changedFields: ['name'] }),+ });const handlers = createAdminGroupsHandlers(deps);const { req, res, status } = createReqRes({params: { id: validId },@@ -518,12 +542,23 @@ describe('createAdminGroupsHandlers', () => {await handlers.updateGroup(req, res);expect(status).toHaveBeenCalledWith(200);- expect(deps.updateGroupById).toHaveBeenCalledWith(validId, { description: 'New desc' });+ expect(deps.updateGroupFieldsTracked).toHaveBeenCalledWith(validId, {+ description: 'New desc',+ });});it('updates email only', async () => {const group = mockGroup({ email: '[email protected]' });- const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const deps = createDeps({+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: group, changed: true, changedFields: ['name'] }),+ });const handlers = createAdminGroupsHandlers(deps);const { req, res, status } = createReqRes({params: { id: validId },@@ -533,12 +568,21 @@ describe('createAdminGroupsHandlers', () => {await handlers.updateGroup(req, res);expect(status).toHaveBeenCalledWith(200);- expect(deps.updateGroupById).toHaveBeenCalledWith(validId, { email: '[email protected]' });+ expect(deps.updateGroupFieldsTracked).toHaveBeenCalledWith(validId, { email: '[email protected]' });});it('updates avatar only', async () => {const group = mockGroup({ avatar: 'https://img.co/a.png' });- const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const deps = createDeps({+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: group, changed: true, changedFields: ['name'] }),+ });const handlers = createAdminGroupsHandlers(deps);const { req, res, status } = createReqRes({params: { id: validId },@@ -548,14 +592,23 @@ describe('createAdminGroupsHandlers', () => {await handlers.updateGroup(req, res);expect(status).toHaveBeenCalledWith(200);- expect(deps.updateGroupById).toHaveBeenCalledWith(validId, {+ expect(deps.updateGroupFieldsTracked).toHaveBeenCalledWith(validId, {avatar: 'https://img.co/a.png',});});it('updates multiple fields at once', async () => {const group = mockGroup({ name: 'New', description: 'Desc', email: '[email protected]' });- const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const deps = createDeps({+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest+ .fn()+ .mockResolvedValue({ group: group, changed: true, changedFields: ['name'] }),+ });const handlers = createAdminGroupsHandlers(deps);const { req, res, status } = createReqRes({params: { id: validId },@@ -565,7 +618,7 @@ describe('createAdminGroupsHandlers', () => {await handlers.updateGroup(req, res);expect(status).toHaveBeenCalledWith(200);- expect(deps.updateGroupById).toHaveBeenCalledWith(validId, {+ expect(deps.updateGroupFieldsTracked).toHaveBeenCalledWith(validId, {name: 'New',description: 'Desc',email: '[email protected]',@@ -626,7 +679,7 @@ describe('createAdminGroupsHandlers', () => {expect(status).toHaveBeenCalledWith(400);expect(json).toHaveBeenCalledWith({ error: 'name must not exceed 500 characters' });- expect(deps.updateGroupById).not.toHaveBeenCalled();+ expect(deps.updateGroupFieldsTracked).not.toHaveBeenCalled();});it('returns 400 when description exceeds max length', async () => {@@ -643,7 +696,7 @@ describe('createAdminGroupsHandlers', () => {expect(json).toHaveBeenCalledWith({error: 'description must not exceed 2000 characters',});- expect(deps.updateGroupById).not.toHaveBeenCalled();+ expect(deps.updateGroupFieldsTracked).not.toHaveBeenCalled();});it('returns 400 when email exceeds max length', async () => {@@ -658,7 +711,7 @@ describe('createAdminGroupsHandlers', () => {expect(status).toHaveBeenCalledWith(400);expect(json).toHaveBeenCalledWith({ error: 'email must not exceed 500 characters' });- expect(deps.updateGroupById).not.toHaveBeenCalled();+ expect(deps.updateGroupFieldsTracked).not.toHaveBeenCalled();});it('returns 400 when avatar exceeds max length', async () => {@@ -673,7 +726,7 @@ describe('createAdminGroupsHandlers', () => {expect(status).toHaveBeenCalledWith(400);expect(json).toHaveBeenCalledWith({ error: 'avatar must not exceed 2000 characters' });- expect(deps.updateGroupById).not.toHaveBeenCalled();+ expect(deps.updateGroupFieldsTracked).not.toHaveBeenCalled();});it('returns 400 when no valid fields provided', async () => {@@ -688,12 +741,17 @@ describe('createAdminGroupsHandlers', () => {expect(status).toHaveBeenCalledWith(400);expect(json).toHaveBeenCalledWith({ error: 'No valid fields to update' });- expect(deps.updateGroupById).not.toHaveBeenCalled();+ expect(deps.updateGroupFieldsTracked).not.toHaveBeenCalled();});- it('returns 404 when updateGroupById returns null', async () => {+ it('returns 404 when updateGroupFieldsTracked returns null', async () => {const deps = createDeps({- updateGroupById: jest.fn().mockResolvedValue(null),+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest.fn().mockResolvedValue(null),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -711,7 +769,12 @@ describe('createAdminGroupsHandlers', () => {const validationError = new Error('invalid field');validationError.name = 'ValidationError';const deps = createDeps({- updateGroupById: jest.fn().mockRejectedValue(validationError),+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest.fn().mockRejectedValue(validationError),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -727,7 +790,12 @@ describe('createAdminGroupsHandlers', () => {it('returns 500 on error', async () => {const deps = createDeps({- updateGroupById: jest.fn().mockRejectedValue(new Error('db down')),+ findGroupById: jest+ .fn()+ .mockResolvedValue(+ mockGroup({ name: 'old', description: 'old', email: '[email protected]', avatar: 'old' }),+ ),+ updateGroupFieldsTracked: jest.fn().mockRejectedValue(new Error('db down')),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1061,7 +1129,7 @@ describe('createAdminGroupsHandlers', () => {it('adds member and returns 200', async () => {const group = mockGroup();const deps = createDeps({- addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group }),+ addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group, changed: true }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1122,7 +1190,9 @@ describe('createAdminGroupsHandlers', () => {it('returns 404 when addUserToGroup returns null group', async () => {const deps = createDeps({- addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: null }),+ addUserToGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group: null, changed: false }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1187,7 +1257,9 @@ describe('createAdminGroupsHandlers', () => {describe('removeGroupMember', () => {it('removes member and returns 200', async () => {const deps = createDeps({- removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),+ removeUserFromGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group: mockGroup(), changed: true }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1214,9 +1286,11 @@ describe('createAdminGroupsHandlers', () => {expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });});- it('removes non-ObjectId member via removeMemberById', async () => {+ it('removes non-ObjectId member via removeMemberByIdTracked', async () => {const deps = createDeps({- removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ removeMemberByIdTracked: jest+ .fn()+ .mockResolvedValue({ group: mockGroup(), changed: true, changedFields: ['name'] }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1225,7 +1299,7 @@ describe('createAdminGroupsHandlers', () => {await handlers.removeGroupMember(req, res);- expect(deps.removeMemberById).toHaveBeenCalledWith(validId, 'ent-abc-123');+ expect(deps.removeMemberByIdTracked).toHaveBeenCalledWith(validId, 'ent-abc-123');expect(deps.removeUserFromGroup).not.toHaveBeenCalled();expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });@@ -1233,7 +1307,7 @@ describe('createAdminGroupsHandlers', () => {it('returns 404 when removeMemberById returns null', async () => {const deps = createDeps({- removeMemberById: jest.fn().mockResolvedValue(null),+ removeMemberByIdTracked: jest.fn().mockResolvedValue({ group: null, changed: false }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1249,7 +1323,9 @@ describe('createAdminGroupsHandlers', () => {it('falls back to removeMemberById when ObjectId userId not found as user', async () => {const deps = createDeps({removeUserFromGroup: jest.fn().mockRejectedValue(new Error('User not found')),- removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ removeMemberByIdTracked: jest+ .fn()+ .mockResolvedValue({ group: mockGroup(), changed: true, changedFields: ['name'] }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1259,14 +1335,16 @@ describe('createAdminGroupsHandlers', () => {await handlers.removeGroupMember(req, res);expect(deps.removeUserFromGroup).toHaveBeenCalledWith(validUserId, validId);- expect(deps.removeMemberById).toHaveBeenCalledWith(validId, validUserId);+ expect(deps.removeMemberByIdTracked).toHaveBeenCalledWith(validId, validUserId);expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });});it('returns 404 when removeUserFromGroup returns null group', async () => {const deps = createDeps({- removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: null }),+ removeUserFromGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group: null, changed: false }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1282,7 +1360,7 @@ describe('createAdminGroupsHandlers', () => {it('returns 404 when fallback removeMemberById also returns null', async () => {const deps = createDeps({removeUserFromGroup: jest.fn().mockRejectedValue(new Error('User not found')),- removeMemberById: jest.fn().mockResolvedValue(null),+ removeMemberByIdTracked: jest.fn().mockResolvedValue({ group: null, changed: false }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1313,7 +1391,9 @@ describe('createAdminGroupsHandlers', () => {it('returns 200 when removing ObjectId member not in group (idempotent delete)', async () => {const group = mockGroup({ memberIds: [] });const deps = createDeps({- removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group }),+ removeUserFromGroup: jest+ .fn()+ .mockResolvedValue({ user: mockUser(), group, changed: true }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1329,7 +1409,7 @@ describe('createAdminGroupsHandlers', () => {it('returns 200 when removing non-ObjectId member not in group (idempotent delete)', async () => {const group = mockGroup({ memberIds: [] });const deps = createDeps({- removeMemberById: jest.fn().mockResolvedValue(group),+ removeMemberByIdTracked: jest.fn().mockResolvedValue({ group, changed: true }),});const handlers = createAdminGroupsHandlers(deps);const { req, res, status, json } = createReqRes({@@ -1342,4 +1422,223 @@ describe('createAdminGroupsHandlers', () => {expect(json).toHaveBeenCalledWith({ success: true });});});++ describe('audit entries', () => {+ function withUser<T extends { req: ServerRequest }>(reqRes: T, tenantId?: string): T {+ (reqRes.req as unknown as { user: Partial<IUser> }).user = {+ _id: new Types.ObjectId(),+ name: 'Admin',+ tenantId,+ };+ return reqRes;+ }++ it('records group.created', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({ recordAuditEntry });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = withUser(createReqRes({ body: { name: 'Test Group' } }), 't1');++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'group.created',+ actor: expect.objectContaining({ type: 'user', name: 'Admin' }),+ target: { type: 'group', id: validId, name: 'Test Group' },+ metadata: { source: 'local', memberCount: 0 },+ tenantId: 't1',+ }),+ );+ });++ it('records a member_added entry for each initial member', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({ recordAuditEntry });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = withUser(+ createReqRes({ body: { name: 'Test Group', memberIds: ['ext-1', 'ext-2', 'ext-1'] } }),+ 't1',+ );++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ const added = recordAuditEntry.mock.calls+ .map(([entry]) => entry)+ .filter((entry) => entry.action === 'group.member_added');+ expect(added).toHaveLength(1);+ expect(added[0].metadata).toEqual({ userIds: 'ext-1,ext-2', count: 2 });+ });++ it('records group.updated with the changed field names only', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ updateGroupFieldsTracked: jest.fn().mockResolvedValue({+ group: mockGroup(),+ changed: true,+ changedFields: ['name', 'description'],+ }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = withUser(+ createReqRes({ params: { id: validId }, body: { name: 'Renamed', description: 'd' } }),+ );++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'group.updated',+ metadata: { fields: 'description,name' },+ }),+ );+ });++ it('records no group.updated entry when the write changed nothing', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ updateGroupFieldsTracked: jest.fn().mockResolvedValue({+ group: mockGroup({ name: 'Same' }),+ changed: false,+ changedFields: [],+ }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = withUser(+ createReqRes({ params: { id: validId }, body: { name: 'Same' } }),+ );++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('records group.deleted', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({ recordAuditEntry });+ 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.objectContaining({+ action: 'group.deleted',+ target: { type: 'group', id: validId, name: 'Test Group' },+ }),+ );+ });++ it('records the members whose access a group deletion revokes', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ deleteGroup: jest.fn().mockResolvedValue(mockGroup({ memberIds: ['m1', 'm2'] })),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = withUser(createReqRes({ params: { id: validId } }));++ await handlers.deleteGroup(req, res);++ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'group.member_removed',+ metadata: { userIds: 'm1,m2', count: 2, cause: 'group_deleted' },+ }),+ );+ });++ it('records group.member_added and group.member_removed when membership changes', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ addUserToGroup: jest.fn().mockResolvedValue({+ user: mockUser(),+ group: mockGroup({ memberIds: ['m1'] }),+ changed: true,+ }),+ removeUserFromGroup: jest.fn().mockResolvedValue({+ user: mockUser(),+ group: mockGroup({ memberIds: [] }),+ changed: true,+ }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const add = withUser(+ createReqRes({ params: { id: validId }, body: { userId: validUserId } }),+ );+ const remove = withUser(createReqRes({ params: { id: validId, userId: validUserId } }));++ await handlers.addGroupMember(add.req, add.res);+ await handlers.removeGroupMember(remove.req, remove.res);++ expect(add.status).toHaveBeenCalledWith(200);+ expect(remove.status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({+ action: 'group.member_added',+ metadata: { userId: validUserId },+ }),+ );+ expect(recordAuditEntry).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({+ action: 'group.member_removed',+ metadata: { userId: validUserId },+ }),+ );+ });++ it('does not record an idempotent add or a removal of a non-member', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ addUserToGroup: jest.fn().mockResolvedValue({+ user: mockUser(),+ group: mockGroup({ memberIds: ['m1'] }),+ changed: false,+ }),+ removeUserFromGroup: jest.fn().mockResolvedValue({+ user: mockUser(),+ group: mockGroup({ memberIds: ['m1'] }),+ changed: false,+ }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const add = withUser(+ createReqRes({ params: { id: validId }, body: { userId: validUserId } }),+ );+ const remove = withUser(createReqRes({ params: { id: validId, userId: validUserId } }));++ await handlers.addGroupMember(add.req, add.res);+ await handlers.removeGroupMember(remove.req, remove.res);++ expect(add.status).toHaveBeenCalledWith(200);+ expect(remove.status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not record when the group is missing', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ deleteGroup: jest.fn().mockResolvedValue(null),+ recordAuditEntry,+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = withUser(createReqRes({ params: { id: validId } }));++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+ });});diff --git a/packages/api/src/admin/groups.ts b/packages/api/src/admin/groups.tsindex d37ca3d294..80a0bcf115 100644--- a/packages/api/src/admin/groups.ts+++ b/packages/api/src/admin/groups.ts@@ -13,12 +13,17 @@ import type { FilterQuery, ClientSession, DeleteResult } from 'mongoose';import type { Response } from 'express';import type { ValidationError } from '~/types/error';import type { ServerRequest } from '~/types/http';+import type { RecordAuditEntry } from './audit';+import { getSafeErrorMetadata } from '~/utils/errors';+import { createAdminAuditEmitter } from './audit';import { parsePagination } from './pagination';type GroupListFilter = Pick<GroupFilterOptions, 'source' | 'search'>;const VALID_GROUP_SOURCES: ReadonlySet<string> = new Set(['local', 'entra']);const MAX_CREATE_MEMBER_IDS = 500;+/** Member ids per audit entry, so group creation writes a few ordered entries. */+const AUDIT_MEMBER_CHUNK = 100;const MAX_SEARCH_LENGTH = 200;const MAX_NAME_LENGTH = 500;const MAX_DESCRIPTION_LENGTH = 2000;@@ -46,30 +51,31 @@ export interface AdminGroupsDeps {session?: ClientSession,) => Promise<IGroup | null>;createGroup: (groupData: Partial<IGroup>, session?: ClientSession) => Promise<IGroup>;- updateGroupById: (+ /** Sets the fields and reports, from the write itself, whether any value changed. */+ updateGroupFieldsTracked: (groupId: string | Types.ObjectId,data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,- session?: ClientSession,- ) => Promise<IGroup | null>;+ ) => Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null>;deleteGroup: (groupId: string | Types.ObjectId,session?: ClientSession,) => Promise<IGroup | null>;+ /** `changed` is decided by the write itself: true only when the membership was altered. */addUserToGroup: (userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ) => Promise<{ user: IUser; group: IGroup | null }>;+ ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>;removeUserFromGroup: (userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ) => Promise<{ user: IUser; group: IGroup | null }>;- removeMemberById: (+ ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>;+ removeMemberByIdTracked: (groupId: string | Types.ObjectId,memberId: string,session?: ClientSession,- ) => Promise<IGroup | null>;+ ) => Promise<{ group: IGroup | null; changed: boolean }>;findUsers: (searchCriteria: FilterQuery<IUser>,fieldsToSelect?: string | string[] | null,@@ -82,6 +88,15 @@ export interface AdminGroupsDeps {principalType: PrincipalType;principalId: string | Types.ObjectId;}) => Promise<DeleteResult>;+ /** 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+ * been persisted. Defaults to fail-open. */+ auditFailClosed?: boolean;+}++function groupTarget(group: Pick<IGroup, 'name'> & { _id?: unknown }, id?: string) {+ return { type: 'group', id: id ?? String(group._id ?? ''), name: group.name };}export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {@@ -99,16 +114,24 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {countGroups,findGroupById,createGroup,- updateGroupById,+ updateGroupFieldsTracked,deleteGroup,addUserToGroup,removeUserFromGroup,- removeMemberById,+ removeMemberByIdTracked,findUsers,deleteConfig,deleteAclEntries,+ recordAuditEntry,+ auditFailClosed,} = deps;+ const emitAudit = createAdminAuditEmitter({+ recordAuditEntry,+ failClosed: auditFailClosed,+ logPrefix: '[adminGroups]',+ });+async function listGroupsHandler(req: ServerRequest, res: Response) {try {const { search, source } = req.query as { search?: string; source?: string };@@ -131,7 +154,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {]);return res.status(200).json({ groups, total, limit, offset });} catch (error) {- logger.error('[adminGroups] listGroups error:', error);+ logger.error('[adminGroups] listGroups error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to list groups' });}}@@ -148,7 +171,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {}return res.status(200).json({ group });} catch (error) {- logger.error('[adminGroups] getGroup error:', error);+ logger.error('[adminGroups] getGroup error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get group' });}}@@ -222,12 +245,29 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {memberIds,...(body.idOnTheSource ? { idOnTheSource: body.idOnTheSource } : {}),});+ await emitAudit(req, {+ action: 'group.created',+ target: groupTarget(group),+ metadata: { source: group.source ?? null, memberCount: memberIds.length },+ });+ /** The initial members gain group-scoped access, so each is recorded like a member add+ * (bounded by MAX_CREATE_MEMBER_IDS; sequential to keep the audit chain ordered). */+ const unique = [...new Set(memberIds)];+ for (let i = 0; i < unique.length; i += AUDIT_MEMBER_CHUNK) {+ const chunk = unique.slice(i, i + AUDIT_MEMBER_CHUNK);+ await emitAudit(req, {+ action: 'group.member_added',+ severity: 'warning',+ target: groupTarget(group),+ metadata: { userIds: chunk.join(','), count: chunk.length },+ });+ }return res.status(201).json({ group });} catch (error) {if ((error as ValidationError).name === 'ValidationError') {return res.status(400).json({ error: (error as ValidationError).message });}- logger.error('[adminGroups] createGroup error:', error);+ logger.error('[adminGroups] createGroup error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to create group' });}}@@ -285,16 +325,26 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {return res.status(400).json({ error: 'No valid fields to update' });}- const group = await updateGroupById(id, updateData);- if (!group) {+ /** The write itself reports whether it changed a value, so overlapping identical+ * requests record one entry. */+ const result = await updateGroupFieldsTracked(id, updateData);+ if (!result) {return res.status(404).json({ error: 'Group not found' });}+ const { group, changed, changedFields } = result;+ if (changed) {+ await emitAudit(req, {+ action: 'group.updated',+ target: groupTarget(group, id),+ metadata: { fields: [...changedFields].sort().join(',') },+ });+ }return res.status(200).json({ group });} catch (error) {if ((error as ValidationError).name === 'ValidationError') {return res.status(400).json({ error: (error as ValidationError).message });}- logger.error('[adminGroups] updateGroup error:', error);+ logger.error('[adminGroups] updateGroup error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to update group' });}}@@ -326,9 +376,25 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {logger.error('[adminGroups] cascade cleanup step failed for group:', id, result.reason);}}+ /** 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' },+ });+ }+ await emitAudit(req, {+ action: 'group.deleted',+ severity: 'warning',+ target: groupTarget(deleted, id),+ });return res.status(200).json({ success: true, id });} catch (error) {- logger.error('[adminGroups] deleteGroup error:', error);+ logger.error('[adminGroups] deleteGroup error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to delete group' });}}@@ -395,7 +461,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {return res.status(200).json({ members, total, limit, offset });} catch (error) {- logger.error('[adminGroups] getGroupMembers error:', error);+ logger.error('[adminGroups] getGroupMembers error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get group members' });}}@@ -416,10 +482,18 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {.json({ error: 'Only native user ObjectIds can be added via this endpoint' });}- const { group } = await addUserToGroup(userId, id);+ const { group, changed } = await addUserToGroup(userId, id);if (!group) {return res.status(404).json({ error: 'Group not found' });}+ if (changed) {+ await emitAudit(req, {+ action: 'group.member_added',+ severity: 'warning',+ target: groupTarget(group, id),+ metadata: { userId },+ });+ }return res.status(200).json({ group });} catch (error) {const message = error instanceof Error ? error.message : '';@@ -427,7 +501,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {if (isNotFound) {return res.status(404).json({ error: 'User not found' });}- logger.error('[adminGroups] addGroupMember error:', error);+ logger.error('[adminGroups] addGroupMember error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to add member' });}}@@ -437,14 +511,17 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {* (which resolves the user), falling back to a raw $pull if the user record* no longer exists. Returns null only when the group itself is not found.*/- async function removeObjectIdMember(groupId: string, userId: string): Promise<IGroup | null> {+ async function removeObjectIdMember(+ groupId: string,+ userId: string,+ ): Promise<{ group: IGroup | null; changed: boolean }> {try {- const { group } = await removeUserFromGroup(userId, groupId);- return group;+ const { group, changed } = await removeUserFromGroup(userId, groupId);+ return { group, changed };} catch (err) {const msg = err instanceof Error ? err.message : '';if (msg === 'User not found' || msg.startsWith('User not found:')) {- return removeMemberById(groupId, userId);+ return removeMemberByIdTracked(groupId, userId);}throw err;}@@ -457,16 +534,24 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {return res.status(400).json({ error: 'Invalid group ID format' });}- const group = isValidObjectIdString(userId)+ const { group, changed } = isValidObjectIdString(userId)? await removeObjectIdMember(id, userId)- : await removeMemberById(id, userId);+ : await removeMemberByIdTracked(id, userId);if (!group) {return res.status(404).json({ error: 'Group not found' });}+ if (changed) {+ await emitAudit(req, {+ action: 'group.member_removed',+ severity: 'warning',+ target: groupTarget(group, id),+ metadata: { userId },+ });+ }return res.status(200).json({ success: true });} catch (error) {- logger.error('[adminGroups] removeGroupMember error:', error);+ logger.error('[adminGroups] removeGroupMember error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to remove member' });}}diff --git a/packages/api/src/admin/index.ts b/packages/api/src/admin/index.tsindex 84f565c03f..0ecb60212c 100644--- a/packages/api/src/admin/index.ts+++ b/packages/api/src/admin/index.ts@@ -2,19 +2,27 @@ export { createAdminConfigHandlers } from './config';export { createAdminLangfuseHandlers } from './langfuse';export { createAdminGrantsHandlers } from './grants';export { createAdminGroupsHandlers } from './groups';-export { createAdminRolesHandlers } from './roles';+export { createAdminRolesHandlers, createRolePermissionsUpdateHandler } from './roles';export { createAdminSkillsSyncAccess, createAdminSkillsSyncHandlers } from './skills';export { createAdminUsersHandlers } from './users';export { createAdminAuditLogHandlers } from './auditLog';export { createAdminCodeEnvironmentHandlers } from './code';export { buildAuditContext } from './context';+export { cascadeStep, runCascade } from './cascade';+export { createAdminAuditEmitter, recordSystemAuditEntry, diffRolePermissions } from './audit';export { resolveConfigSecret, redactConfigSecretMaps } from './secrets';export type { AdminConfigDeps } from './config';export type { AdminLangfuseDeps } from './langfuse';export type { AdminGrantsDeps, GrantPrincipalType } from './grants';export type { AdminGroupsDeps } from './groups';-export type { AdminRolesDeps } from './roles';+export type {+ AdminRolesDeps,+ RolePermissionsUpdateDeps,+ RolePermissionsUpdateConfig,+} from './roles';export type { AdminSkillSyncAccessDeps, AdminSkillSyncDeps } from './skills';export type { AdminUsersDeps } from './users';export type { AdminAuditLogDeps } from './auditLog';+export type { CascadeStep, CascadeOutcome } from './cascade';export type { AdminCodeEnvironmentDeps } from './code';+export type { AdminAuditEmitter, AdminAuditEvent, RecordAuditEntry } from './audit';diff --git a/packages/api/src/admin/roles.spec.ts b/packages/api/src/admin/roles.spec.tsindex dc96975b41..6647cdf4f5 100644--- a/packages/api/src/admin/roles.spec.ts+++ b/packages/api/src/admin/roles.spec.ts@@ -4,9 +4,10 @@ import type { IRole, IUser } from '@librechat/data-schemas';import type { Response } from 'express';import type { ServerRequest } from '~/types/http';import type { AdminRolesDeps } from './roles';-import { createAdminRolesHandlers } from './roles';+import { createAdminRolesHandlers, createRolePermissionsUpdateHandler } from './roles';const { RoleConflictError } = jest.requireActual('@librechat/data-schemas');+const { logger } = jest.requireMock('@librechat/data-schemas');jest.mock('@librechat/data-schemas', () => ({...jest.requireActual('@librechat/data-schemas'),@@ -440,6 +441,26 @@ describe('createAdminRolesHandlers', () => {expect(deps.updateRoleByName).toHaveBeenCalledWith('editor', { name: 'senior-editor' });});+ it('writes and audits nothing when the description already matches', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValue(mockRole({ description: 'Can edit content' })),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { description: 'Can edit content' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.updateRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateRoleByName).not.toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+it('trims name before storage', async () => {const role = mockRole({ name: 'trimmed' });const deps = createDeps({@@ -918,20 +939,23 @@ describe('createAdminRolesHandlers', () => {});describe('deleteRole', () => {+ const deleteDeps = (overrides: Partial<AdminRolesDeps> = {}) =>+ createDeps({ getRoleByName: jest.fn().mockResolvedValue(mockRole()), ...overrides });+it('deletes role and returns 200', async () => {- const deps = createDeps();+ const deps = deleteDeps();const handlers = createAdminRolesHandlers(deps);const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });await handlers.deleteRole(req, res);- expect(deps.deleteRoleByName).toHaveBeenCalledWith('editor');+ expect(deps.deleteRoleByName).toHaveBeenCalledWith('editor', expect.any(Object));expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });});it('cleans up grants after successful deletion', async () => {- const deps = createDeps();+ const deps = deleteDeps();const handlers = createAdminRolesHandlers(deps);const { req, res, status } = createReqRes({ params: { name: 'editor' } });@@ -949,7 +973,7 @@ describe('createAdminRolesHandlers', () => {});it('passes tenantId to grant cleanup', async () => {- const deps = createDeps();+ const deps = deleteDeps();const handlers = createAdminRolesHandlers(deps);const { req, res, status } = createReqRes({params: { name: 'editor' },@@ -965,7 +989,7 @@ describe('createAdminRolesHandlers', () => {});it('does not clean up when role not found', async () => {- const deps = createDeps({ deleteRoleByName: jest.fn().mockResolvedValue(null) });+ const deps = deleteDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });const handlers = createAdminRolesHandlers(deps);const { req, res, status } = createReqRes({ params: { name: 'nonexistent' } });@@ -975,24 +999,345 @@ describe('createAdminRolesHandlers', () => {expect(deps.deleteConfig).not.toHaveBeenCalled();expect(deps.deleteAclEntries).not.toHaveBeenCalled();expect(deps.deleteGrantsForPrincipal).not.toHaveBeenCalled();+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();});- it('succeeds even when grant cleanup fails', async () => {- const deps = createDeps({+ it('removes grants, ACL entries and config before deleting the role', async () => {+ const order: string[] = [];+ const track = (name: string, value: unknown) =>+ jest.fn().mockImplementation(async () => {+ order.push(name);+ return value;+ });+ const deps = deleteDeps({+ deleteConfig: track('config', null),+ deleteAclEntries: track('acl', undefined),+ deleteGrantsForPrincipal: track('grants', []),+ deleteRoleByName: track('role', mockRole()),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(order[order.length - 1]).toBe('role');+ expect(order).toHaveLength(4);+ });++ it('returns 500 and keeps the role when grant cleanup fails', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({deleteGrantsForPrincipal: jest.fn().mockRejectedValue(new Error('cleanup failed')),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'ROLE_CLEANUP_FAILED' }));+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'success' }),+ );+ });++ it('restores config but leaves ACL entries and grants removed, and audits the grants, when a cleanup step fails', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const config = {+ principalModel: 'Role',+ overrides: { interface: { customWelcome: 'hi' } },+ priority: 7,+ };+ const deps = deleteDeps({+ deleteConfig: jest.fn().mockResolvedValue(config),+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl cleanup failed')),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ restoreConfig: jest.fn().mockResolvedValue(true),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'ROLE_CLEANUP_FAILED' }));+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);+ expect(deps.deleteAclEntries).toHaveBeenCalledTimes(1);+ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledTimes(1);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({ action: 'grant.removed' }),+ );+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({+ action: 'role.deleted',+ outcome: 'failure',+ metadata: { code: 'ROLE_CLEANUP_FAILED' },+ }),+ );+ expect(recordAuditEntry).not.toHaveBeenCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'success' }),+ );+ });++ it('skips the config restore when cleanup fails after the role was deleted by another request', async () => {+ const deps = deleteDeps({+ getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValue(null),+ deleteConfig: jest.fn().mockResolvedValue({ principalModel: 'Role', overrides: {} }),+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl cleanup failed')),+ restoreConfig: jest.fn().mockResolvedValue(true),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'ROLE_CLEANUP_FAILED' }));+ expect(deps.restoreConfig).not.toHaveBeenCalled();+ });++ it('restores only the config override when the role deletion itself fails', async () => {+ const deps = deleteDeps({+ deleteConfig: jest.fn().mockResolvedValue({+ principalModel: 'Role',+ overrides: {},+ priority: 3,+ }),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('db down')),+ restoreConfig: jest.fn().mockResolvedValue(true),+ invalidatePromptGroupAccessContext: jest.fn().mockResolvedValue(undefined),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to delete role' });+ expect(deps.restoreConfig).toHaveBeenCalledTimes(1);+ expect(deps.deleteAclEntries).toHaveBeenCalledTimes(1);+ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledTimes(1);+ expect(deps.invalidatePromptGroupAccessContext).toHaveBeenCalled();+ });++ it('deletes only the role it targeted and audits grants when that role is already replaced', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const original = mockRole({ _id: new Types.ObjectId() } as Partial<IRole>);+ const deps = deleteDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValue(original),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ /** The id-conditional delete matched nothing: the name now belongs to another role. */+ deleteRoleByName: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(deps.deleteRoleByName).toHaveBeenCalledWith('editor', { id: String(original._id) });+ expect(status).toHaveBeenCalledWith(404);+ expect(recordAuditEntry).not.toHaveBeenCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'success' }),+ );+ });++ it('does not restore dependents and audits the delete when the role is confirmed gone after a thrown delete', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValue(null),+ deleteConfig: jest.fn().mockResolvedValue({+ principalModel: 'Role',+ overrides: {},+ priority: 3,+ }),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('connection lost')),+ restoreConfig: jest.fn(),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.restoreConfig).not.toHaveBeenCalled();+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({ action: 'role.deleted' }),+ );+ });++ it('does not restore dependents onto a role recreated under the same name', async () => {+ const original = mockRole({ _id: new Types.ObjectId() } as Partial<IRole>);+ const replacement = mockRole({ _id: new Types.ObjectId() } as Partial<IRole>);+ const deps = deleteDeps({+ getRoleByName: jest.fn().mockResolvedValueOnce(original).mockResolvedValue(replacement),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('connection lost')),+ restoreConfig: jest.fn(),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.restoreConfig).not.toHaveBeenCalled();+ });++ it('restores nothing and reports a failure when the role state cannot be verified', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ getRoleByName: jest+ .fn()+ .mockResolvedValueOnce(mockRole())+ .mockRejectedValue(new Error('mongo down')),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('connection lost')),+ restoreConfig: jest.fn(),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.restoreConfig).not.toHaveBeenCalled();+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({ action: 'grant.removed' }),+ );+ });++ it('restores config insert-only so an override written after the snapshot is kept', async () => {+ const deps = deleteDeps({+ deleteConfig: jest.fn().mockResolvedValue({+ principalModel: 'Role',+ overrides: { old: true },+ priority: 3,+ }),+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl failed')),+ /** false: a config document already exists, so the insert-only write was refused */+ restoreConfig: jest.fn().mockResolvedValue(false),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.restoreConfig).toHaveBeenCalledWith({+ principalModel: 'Role',+ overrides: { old: true },+ priority: 3,+ });+ });++ it('leaves ACL entries removed when the ACL delete itself rejects', async () => {+ const deps = deleteDeps({+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('response lost')),+ invalidatePromptGroupAccessContext: jest.fn().mockResolvedValue(undefined),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.invalidatePromptGroupAccessContext).toHaveBeenCalled();+ });++ it('invalidates the access cache even when the role is gone after a failed delete', async () => {+ const deps = deleteDeps({+ getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValue(null),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('connection lost')),+ invalidatePromptGroupAccessContext: jest.fn().mockResolvedValue(undefined),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(deps.invalidatePromptGroupAccessContext).toHaveBeenCalled();+ });++ it('restores config from a pre-delete snapshot and never restores grants when their deletes reject', async () => {+ const config = { principalModel: 'Role', overrides: { a: 1 }, priority: 4 };+ const deps = deleteDeps({+ findConfigByPrincipal: jest.fn().mockResolvedValue(config),+ deleteConfig: jest.fn().mockRejectedValue(new Error('response lost')),+ deleteGrantsForPrincipal: jest.fn().mockRejectedValue(new Error('response lost')),+ restoreConfig: jest.fn().mockResolvedValue(true),});const handlers = createAdminRolesHandlers(deps);const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });await handlers.deleteRole(req, res);+ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'ROLE_CLEANUP_FAILED' }));+ expect(deps.restoreConfig).toHaveBeenCalledWith(config);+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();+ });++ it('still audits a committed deletion when the access cache invalidation fails', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ invalidatePromptGroupAccessContext: jest.fn().mockRejectedValue(new Error('cache down')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);+expect(status).toHaveBeenCalledWith(200);- expect(json).toHaveBeenCalledWith({ success: true });+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({ action: 'role.deleted' }),+ );+ });++ it('does not restore anything when the cascade and role deletion succeed', async () => {+ const deps = deleteDeps({+ restoreConfig: jest.fn(),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.restoreConfig).not.toHaveBeenCalled();});it('emits a grant.removed audit entry for each grant removed by the cascade', async () => {const recordAuditEntry = jest.fn().mockResolvedValue(undefined);- const deps = createDeps({+ const deps = deleteDeps({deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'manage:users', tenantId: 'tenant-1' },{ capability: 'read:users', tenantId: 'tenant-1' },@@ -1009,7 +1354,7 @@ describe('createAdminRolesHandlers', () => {await handlers.deleteRole(req, res);expect(status).toHaveBeenCalledWith(200);- expect(recordAuditEntry).toHaveBeenCalledTimes(2);+ expect(recordAuditEntry).toHaveBeenCalledTimes(5);expect(recordAuditEntry).toHaveBeenCalledWith(expect.objectContaining({action: 'grant.removed',@@ -1019,11 +1364,20 @@ describe('createAdminRolesHandlers', () => {tenantId: 'tenant-1',}),);+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({+ action: 'role.deleted',+ outcome: 'success',+ target: { type: 'role', id: 'editor', name: 'editor' },+ metadata: { grantsRemoved: 2, membersReassigned: 2 },+ tenantId: 'tenant-1',+ }),+ );});it('scopes each cascade audit entry to the removed grant’s own tenant', async () => {const recordAuditEntry = jest.fn().mockResolvedValue(undefined);- const deps = createDeps({+ const deps = deleteDeps({// a platform admin (no tenantId) deletes a role holding both a// platform-level grant and a tenant-scoped onedeleteGrantsForPrincipal: jest@@ -1053,9 +1407,45 @@ describe('createAdminRolesHandlers', () => {);});- it('does not audit when the deleted role had no grants', async () => {+ it('records each account reassigned by the deletion before the outcome', async () => {const recordAuditEntry = jest.fn().mockResolvedValue(undefined);- const deps = createDeps({ recordAuditEntry });+ const deps = deleteDeps({+ recordAuditEntry,+ findUserIdsByRole: jest.fn().mockResolvedValue(['u1', 'u2']),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ const removed = recordAuditEntry.mock.calls+ .map(([entry]) => entry)+ .filter((entry) => entry.action === 'role.member_removed');+ expect(removed).toHaveLength(1);+ expect(removed[0].metadata).toMatchObject({ userIds: 'u1,u2', count: 2 });+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({+ action: 'role.deleted',+ outcome: 'success',+ metadata: { grantsRemoved: 0, membersReassigned: 2 },+ }),+ );+ });++ it('keeps a committed deletion successful when a cascade audit write fails under auditFailClosed', async () => {+ const recordAuditEntry = jest.fn().mockImplementation(async (entry: { action: string }) => {+ if (entry.action === 'grant.removed' || entry.action === 'role.member_removed') {+ throw new Error('audit store down');+ }+ });+ const deps = deleteDeps({+ recordAuditEntry,+ auditFailClosed: true,+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue([{ capability: 'read:users' }]),+ });const handlers = createAdminRolesHandlers(deps);const { req, res, status } = createReqRes({params: { name: 'editor' },@@ -1065,11 +1455,155 @@ describe('createAdminRolesHandlers', () => {await handlers.deleteRole(req, res);expect(status).toHaveBeenCalledWith(200);- expect(recordAuditEntry).not.toHaveBeenCalled();+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'success' }),+ );});- it('succeeds even when all cascade operations fail', async () => {- const deps = createDeps({+ it('audits grants whose removal rejected after committing, from the pre-delete snapshot', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ findGrantsForPrincipal: jest+ .fn()+ .mockResolvedValueOnce([{ capability: 'read:users' }])+ .mockResolvedValue([]),+ deleteGrantsForPrincipal: jest.fn().mockRejectedValue(new Error('response lost')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'grant.removed',+ metadata: { capability: 'read:users' },+ }),+ );+ });++ it('aborts before cleanup when the grant snapshot cannot be read', async () => {+ const deps = deleteDeps({+ findGrantsForPrincipal: jest.fn().mockRejectedValue(new Error('mongo down')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.deleteGrantsForPrincipal).not.toHaveBeenCalled();+ });++ it('fails the delete instead of auditing zero members when the member lookup fails', async () => {+ const deps = deleteDeps({+ findUserIdsByRole: jest.fn().mockRejectedValue(new Error('mongo down')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ params: { name: 'editor' } });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();+ });++ it('records role.deleted as pending before any removal, then success, in order', async () => {+ const order: string[] = [];+ const recordAuditEntry = jest.fn(async (entry: { action: string; outcome?: string }) => {+ order.push(`${entry.action}:${entry.outcome}`);+ });+ const deps = deleteDeps({+ recordAuditEntry,+ deleteConfig: jest.fn(async () => {+ order.push('removal');+ return null;+ }),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(order[0]).toBe('role.deleted:pending');+ expect(order[order.length - 1]).toBe('role.deleted:success');+ expect(order).toContain('removal');+ });++ it('records role.deleted as failed when the role delete throws and the role remains', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('db down')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'failure' }),+ );+ });++ it('records role.deleted success when the delete committed before it threw', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValue(null),+ deleteRoleByName: jest.fn().mockRejectedValue(new Error('response lost')),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({ action: 'role.deleted', outcome: 'success' }),+ );+ });++ it('records only role.deleted when the deleted role had no grants', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = deleteDeps({ recordAuditEntry });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.deleteRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledTimes(3);+ expect(recordAuditEntry).toHaveBeenLastCalledWith(+ expect.objectContaining({+ action: 'role.deleted',+ outcome: 'success',+ metadata: { grantsRemoved: 0, membersReassigned: 2 },+ }),+ );+ });++ it('returns 500 and keeps the role when every cascade operation fails', async () => {+ const deps = deleteDeps({deleteConfig: jest.fn().mockRejectedValue(new Error('config cleanup failed')),deleteAclEntries: jest.fn().mockRejectedValue(new Error('acl cleanup failed')),deleteGrantsForPrincipal: jest.fn().mockRejectedValue(new Error('grant cleanup failed')),@@ -1079,12 +1613,13 @@ describe('createAdminRolesHandlers', () => {await handlers.deleteRole(req, res);- expect(status).toHaveBeenCalledWith(200);- expect(json).toHaveBeenCalledWith({ success: true });+ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith(expect.objectContaining({ code: 'ROLE_CLEANUP_FAILED' }));+ expect(deps.deleteRoleByName).not.toHaveBeenCalled();});it('returns 403 for system role', async () => {- const deps = createDeps();+ const deps = deleteDeps();const handlers = createAdminRolesHandlers(deps);const { req, res, status, json } = createReqRes({ params: { name: SystemRoles.ADMIN } });@@ -1096,7 +1631,7 @@ describe('createAdminRolesHandlers', () => {});it('returns 404 when role not found', async () => {- const deps = createDeps({ deleteRoleByName: jest.fn().mockResolvedValue(null) });+ const deps = deleteDeps({ deleteRoleByName: jest.fn().mockResolvedValue(null) });const handlers = createAdminRolesHandlers(deps);const { req, res, status, json } = createReqRes({ params: { name: 'nonexistent' } });@@ -1107,7 +1642,7 @@ describe('createAdminRolesHandlers', () => {});it('returns 500 on error', async () => {- const deps = createDeps({+ const deps = deleteDeps({deleteRoleByName: jest.fn().mockRejectedValue(new Error('db down')),});const handlers = createAdminRolesHandlers(deps);@@ -1251,11 +1786,40 @@ describe('createAdminRolesHandlers', () => {await handlers.addRoleMember(req, res);- expect(deps.updateUser).toHaveBeenCalledWith(validUserId, { role: 'editor' });+ expect(deps.updateUser).toHaveBeenCalledWith(+ validUserId,+ { role: 'editor' },+ expect.any(Object),+ );expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });});+ it('records no membership entry when an overlapping request already moved the user', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ findUser: jest+ .fn()+ .mockResolvedValueOnce(mockUser({ role: 'viewer' }))+ .mockResolvedValue(mockUser({ role: 'editor' })),+ /** The conditional write matched nothing: the other request got there first. */+ updateUser: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { userId: validUserId },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.addRoleMember(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+it('skips DB write when user already has the target role', async () => {const deps = createDeps({getRoleByName: jest.fn().mockResolvedValue(mockRole()),@@ -1368,7 +1932,11 @@ describe('createAdminRolesHandlers', () => {await handlers.addRoleMember(req, res);expect(status).toHaveBeenCalledWith(200);- expect(deps.updateUser).toHaveBeenCalledWith(validUserId, { role: 'editor' });+ expect(deps.updateUser).toHaveBeenCalledWith(+ validUserId,+ { role: 'editor' },+ expect.any(Object),+ );});it('rolls back assignment when post-write admin count is zero', async () => {@@ -1423,7 +1991,11 @@ describe('createAdminRolesHandlers', () => {await handlers.addRoleMember(req, res);- expect(deps.updateUser).toHaveBeenCalledWith(validUserId, { role: SystemRoles.ADMIN });+ expect(deps.updateUser).toHaveBeenCalledWith(+ validUserId,+ { role: SystemRoles.ADMIN },+ expect.any(Object),+ );expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });});@@ -1460,11 +2032,38 @@ describe('createAdminRolesHandlers', () => {await handlers.removeRoleMember(req, res);- expect(deps.updateUser).toHaveBeenCalledWith(validUserId, { role: SystemRoles.USER });+ expect(deps.updateUser).toHaveBeenCalledWith(+ validUserId,+ { role: SystemRoles.USER },+ expect.any(Object),+ );expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });});+ it('records no entry when an overlapping request already removed the member', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ recordAuditEntry,+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ findUser: jest+ .fn()+ .mockResolvedValueOnce(mockUser({ role: 'editor' }))+ .mockResolvedValue(mockUser({ role: SystemRoles.USER })),+ updateUser: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor', userId: validUserId },+ user: { _id: new Types.ObjectId(), role: 'admin' },+ });++ await handlers.removeRoleMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+it('returns 403 when removing from a non-ADMIN system role', async () => {const deps = createDeps();const handlers = createAdminRolesHandlers(deps);@@ -1573,7 +2172,11 @@ describe('createAdminRolesHandlers', () => {expect(status).toHaveBeenCalledWith(200);expect(json).toHaveBeenCalledWith({ success: true });- expect(deps.updateUser).toHaveBeenCalledWith(validUserId, { role: SystemRoles.USER });+ expect(deps.updateUser).toHaveBeenCalledWith(+ validUserId,+ { role: SystemRoles.USER },+ expect.any(Object),+ );});it('rolls back removal when post-write check finds zero admins', async () => {@@ -1592,9 +2195,12 @@ describe('createAdminRolesHandlers', () => {expect(status).toHaveBeenCalledWith(400);expect(json).toHaveBeenCalledWith({ error: 'Cannot remove the last admin user' });expect(deps.updateUser).toHaveBeenCalledTimes(2);- expect(deps.updateUser).toHaveBeenNthCalledWith(1, validUserId, {- role: SystemRoles.USER,- });+ expect(deps.updateUser).toHaveBeenNthCalledWith(+ 1,+ validUserId,+ { role: SystemRoles.USER },+ { role: SystemRoles.ADMIN },+ );expect(deps.updateUser).toHaveBeenNthCalledWith(2, validUserId, {role: SystemRoles.ADMIN,});@@ -1640,3 +2246,338 @@ describe('createAdminRolesHandlers', () => {});});});++describe('admin role audit entries', () => {+ const adminUser = () => ({ _id: new Types.ObjectId(), role: 'ADMIN', tenantId: 'tenant-1' });++ it('records role.created with the caller as actor', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ createRoleByName: jest+ .fn()+ .mockResolvedValue(mockRole({ permissions: { PROMPTS: { USE: true } } } as Partial<IRole>)),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const user = adminUser();+ const { req, res, status } = createReqRes({ body: { name: 'editor' }, user });++ await handlers.createRole(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.created',+ actor: expect.objectContaining({ type: 'user', id: user._id.toString() }),+ target: { type: 'role', id: 'editor', name: 'editor' },+ metadata: { permissions: 'PROMPTS.USE=true' },+ tenantId: 'tenant-1',+ }),+ );+ });++ it('records role.updated with the previous name on rename', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),+ updateRoleByName: jest.fn().mockResolvedValue(mockRole({ name: 'writer' })),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { name: 'writer' },+ user: adminUser(),+ });++ await handlers.updateRole(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.updated',+ target: { type: 'role', id: 'writer', name: 'writer' },+ metadata: { previousName: 'editor', descriptionChanged: false },+ }),+ );+ });++ it('records role.permissions_updated with only the flags that changed', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const before = mockRole({+ permissions: { PROMPTS: { USE: true, CREATE: false } },+ } as Partial<IRole>);+ const after = mockRole({+ permissions: { PROMPTS: { USE: true, CREATE: true } },+ } as Partial<IRole>);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValueOnce(before).mockResolvedValueOnce(after),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { permissions: { PROMPTS: { CREATE: true } } },+ user: adminUser(),+ });++ await handlers.updateRolePermissions(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.permissions_updated',+ metadata: { changes: 'PROMPTS.CREATE=true', changeCount: 1 },+ }),+ );+ });++ it('does not record a permissions update that changed nothing', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const role = mockRole({ permissions: { PROMPTS: { USE: true } } } as Partial<IRole>);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValue(role),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { permissions: { PROMPTS: { USE: true } } },+ user: adminUser(),+ });++ await handlers.updateRolePermissions(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('also records the removal from the previous role when a member is reassigned', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ findUser: jest.fn().mockResolvedValue(mockUser({ role: 'viewer' })),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res } = createReqRes({+ params: { name: 'editor' },+ body: { userId: validUserId },+ user: adminUser(),+ });++ await handlers.addRoleMember(req, res);++ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.member_removed',+ target: { type: 'role', id: 'viewer', name: 'viewer' },+ metadata: { userId: validUserId, newRole: 'editor' },+ }),+ );+ });++ it('records role.member_added as critical when a user is promoted to ADMIN', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),+ findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.USER })),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: SystemRoles.ADMIN },+ body: { userId: validUserId },+ user: adminUser(),+ });++ await handlers.addRoleMember(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.member_added',+ severity: 'critical',+ target: { type: 'role', id: SystemRoles.ADMIN, name: SystemRoles.ADMIN },+ metadata: { userId: validUserId, previousRole: SystemRoles.USER },+ }),+ );+ });++ it('does not record a membership change that was rolled back', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),+ countUsersByRole: jest.fn().mockResolvedValueOnce(2).mockResolvedValueOnce(0),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor' },+ body: { userId: validUserId },+ user: adminUser(),+ });++ await handlers.addRoleMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('records role.member_removed', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = createDeps({+ getRoleByName: jest.fn().mockResolvedValue(mockRole()),+ findUser: jest.fn().mockResolvedValue(mockUser()),+ recordAuditEntry,+ });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { name: 'editor', userId: validUserId },+ user: adminUser(),+ });++ await handlers.removeRoleMember(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.member_removed',+ severity: 'warning',+ metadata: { userId: validUserId, newRole: SystemRoles.USER },+ }),+ );+ });++ it('keeps the mutation and logs when an audit write fails (fail-open)', async () => {+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down: secret-dsn'));+ const deps = createDeps({ recordAuditEntry });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ body: { name: 'editor' }, user: adminUser() });++ await handlers.createRole(req, res);++ expect(status).toHaveBeenCalledWith(201);+ const logged = JSON.stringify(+ (logger.error as jest.Mock).mock.calls.filter(([message]) =>+ String(message).includes('audit write failed'),+ ),+ );+ expect(logged).toContain('audit write failed');+ expect(logged).not.toContain('secret-dsn');+ });++ it('surfaces an audit write failure as a 5xx when auditFailClosed is set', async () => {+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));+ const deps = createDeps({ recordAuditEntry, auditFailClosed: true });+ const handlers = createAdminRolesHandlers(deps);+ const { req, res, status } = createReqRes({ body: { name: 'editor' }, user: adminUser() });++ await handlers.createRole(req, res);++ expect(recordAuditEntry).toHaveBeenCalledWith(expect.anything(), { failClosed: true });+ expect(status).toHaveBeenCalledWith(500);+ });+});++describe('createRolePermissionsUpdateHandler', () => {+ const config = {+ schema: {+ partial: () => ({+ parse: (value: unknown) => {+ const body = value as Record<string, unknown>;+ if (Object.values(body).some((v) => typeof v !== 'boolean')) {+ throw Object.assign(new Error('invalid'), { errors: ['bad value'] });+ }+ return body as Record<string, boolean>;+ },+ }),+ },+ permissionType: 'PROMPTS',+ errorMessage: 'Invalid prompt permissions.',+ };++ function setup(role: IRole | null, recordAuditEntry = jest.fn().mockResolvedValue(undefined)) {+ const deps = {+ getRoleByName: jest.fn().mockResolvedValue(role),+ updateRoleByName: jest.fn().mockImplementation(async (_name, updates) => ({+ ...role,+ ...updates,+ })),+ recordAuditEntry,+ };+ return { deps, handler: createRolePermissionsUpdateHandler(deps, config) };+ }++ function createSendReqRes(body: unknown) {+ const req = {+ params: { roleName: 'USER' },+ body,+ headers: {},+ user: { _id: new Types.ObjectId(), role: SystemRoles.ADMIN },+ } as unknown as ServerRequest;+ const send = jest.fn();+ const status = jest.fn().mockReturnValue({ send });+ return { req, res: { status, send } as unknown as Response, status, send };+ }++ it('merges the update and records role.permissions_updated', async () => {+ const { deps, handler } = setup(+ mockRole({+ name: 'USER',+ permissions: { PROMPTS: { USE: true, CREATE: true } },+ } as Partial<IRole>),+ );+ const { req, res, status } = createSendReqRes({ CREATE: false });++ await handler(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateRoleByName).toHaveBeenCalledWith('USER', {+ permissions: { PROMPTS: { USE: true, CREATE: false } },+ });+ expect(deps.recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.permissions_updated',+ target: { type: 'role', id: 'USER', name: 'USER' },+ metadata: { changes: 'PROMPTS.CREATE=false', changeCount: 1 },+ }),+ );+ });++ it('skips the audit entry when nothing changed', async () => {+ const { deps, handler } = setup(+ mockRole({ name: 'USER', permissions: { PROMPTS: { USE: true } } } as Partial<IRole>),+ );+ const { req, res, status } = createSendReqRes({ USE: true });++ await handler(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.recordAuditEntry).not.toHaveBeenCalled();+ });++ it('returns 400 with the validation errors for an invalid body', async () => {+ const { deps, handler } = setup(mockRole());+ const { req, res, status, send } = createSendReqRes({ USE: 'yes' });++ await handler(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(send).toHaveBeenCalledWith({+ message: 'Invalid prompt permissions.',+ error: ['bad value'],+ });+ expect(deps.updateRoleByName).not.toHaveBeenCalled();+ });++ it('returns 404 when the role does not exist', async () => {+ const { handler } = setup(null);+ const { req, res, status } = createSendReqRes({ USE: true });++ await handler(req, res);++ expect(status).toHaveBeenCalledWith(404);+ });+});diff --git a/packages/api/src/admin/roles.ts b/packages/api/src/admin/roles.tsindex 3f452977c5..64bc58d6a3 100644--- a/packages/api/src/admin/roles.ts+++ b/packages/api/src/admin/roles.ts@@ -6,14 +6,16 @@ import type {IConfig,AdminMember,ISystemGrant,- RecordAuditEntryInput,- RecordAuditEntryOptions,+ AuditSeverity,} from '@librechat/data-schemas';import type { FilterQuery, Types } from 'mongoose';import type { Response } from 'express';import type { ServerRequest } from '~/types/http';+import type { RecordAuditEntry } from './audit';+import { createAdminAuditEmitter, diffRolePermissions } from './audit';+import { getSafeErrorMetadata } from '~/utils/errors';+import { cascadeStep, runCascade } from './cascade';import { parsePagination } from './pagination';-import { buildAuditContext } from './context';const systemRoleValues = new Set<string>(Object.values(SystemRoles));@@ -100,12 +102,19 @@ export interface AdminRolesDeps {perms: Record<string, Record<string, boolean>>,roleData?: IRole,) => Promise<void>;- deleteRoleByName: (name: string) => Promise<IRole | null>;+ /** With `options.id`, deletes only the role that still has that `_id`, so a role recreated+ * under the same name is never removed by a request that targeted the original. */+ deleteRoleByName: (name: string, options?: { id?: string }) => Promise<IRole | null>;findUser: (criteria: FilterQuery<IUser>,fields?: string | string[] | null,) => Promise<IUser | null>;- updateUser: (userId: string, data: Partial<IUser>) => Promise<IUser | null>;+ /** `expectedState` makes the write conditional: it resolves to null when the user no longer matches. */+ updateUser: (+ userId: string,+ data: Partial<IUser>,+ expectedState?: Record<string, unknown>,+ ) => Promise<IUser | null>;updateUsersByRole: (oldRole: string, newRole: string) => Promise<void>;findUserIdsByRole: (roleName: string) => Promise<string[]>;updateUsersRoleByIds: (userIds: string[], newRole: string) => Promise<void>;@@ -133,12 +142,42 @@ export interface AdminRolesDeps {principalId: string | Types.ObjectId,options?: { tenantId?: string },) => Promise<ISystemGrant[]>;- /** Optional audit emission for grants removed by the role-deletion cascade.- * Failure is logged but never blocks the deletion (which has already happened). */- recordAuditEntry?: (- input: RecordAuditEntryInput,- options?: RecordAuditEntryOptions,- ) => Promise<void>;+ /** Snapshot source and restore sink for the config override removed by the role-deletion+ * cascade. Only the override is restored on failure: ACL entries and grants are never+ * re-inserted, since that could resurrect access a concurrent request revoked, and+ * their removal only narrows access. */+ /** Reads the grants before the cascade so their removal is audited even when it rejects after committing. */+ findGrantsForPrincipal?: (+ principalType: PrincipalType,+ principalId: string,+ options?: { tenantId?: string },+ ) => Promise<ISystemGrant[]>;+ findConfigByPrincipal?: (+ principalType: PrincipalType,+ principalId: string,+ options?: { includeInactive?: boolean },+ ) => Promise<IConfig | null>;+ /** Re-creates a deleted config document in full, only if none exists. Resolves+ * to whether it inserted. */+ restoreConfig?: (snapshot: Record<string, unknown>) => Promise<boolean>;+ /** Optional audit emission for role mutations and the grants removed by the+ * role-deletion cascade. Failure is logged unless `auditFailClosed` is set. */+ recordAuditEntry?: RecordAuditEntry;+ /** When true, a failed audit write surfaces as a 5xx after the mutation has+ * been persisted. Defaults to fail-open. */+ auditFailClosed?: boolean;+}++/** Account ids per entry, so a large role is audited in a few ordered writes. */+const AUDIT_MEMBER_CHUNK = 100;++/** Changing who holds ADMIN is the most sensitive membership change. */+function memberChangeSeverity(...roles: Array<string | undefined>): AuditSeverity {+ return roles.includes(SystemRoles.ADMIN) ? 'critical' : 'warning';+}++function roleTarget(name: string) {+ return { type: 'role', id: name, name };}export function createAdminRolesHandlers(deps: AdminRolesDeps): {@@ -170,43 +209,44 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {deleteConfig,deleteAclEntries,deleteGrantsForPrincipal,+ restoreConfig,+ findConfigByPrincipal,+ findGrantsForPrincipal,recordAuditEntry,+ auditFailClosed,invalidatePromptGroupAccessContext,} = deps;+ const emitAudit = createAdminAuditEmitter({+ recordAuditEntry,+ failClosed: auditFailClosed,+ logPrefix: '[adminRoles]',+ });+ /** Role deletion revokes access, so its lifecycle entries are always fail-open. */+ const emitRevocationAudit = createAdminAuditEmitter({+ recordAuditEntry,+ logPrefix: '[adminRoles]',+ });+/** Emits a `grant.removed` audit entry for each grant the role-deletion cascade* removed, so the cascade leaves the same forensic trail as an explicit revoke.- * Fail-open: the role is already deleted, so a failed audit is logged, not- * propagated. Sequential to keep the per-tenant hash chain ordered. */+ * Sequential to keep the per-tenant hash chain ordered. */async function emitGrantRemovals(req: ServerRequest,roleName: string,grants: ISystemGrant[],): Promise<void> {- if (!recordAuditEntry || grants.length === 0) return;- const user = req.user;- const userId = user?._id?.toString() ?? user?.id;- if (!user || !userId) return;- const actorName = user.name || user.username || user.email || userId;- const context = buildAuditContext(req);for (const grant of grants) {- try {- await recordAuditEntry({- action: 'grant.removed',- outcome: 'success',- severity: 'warning',- actor: { type: 'user', id: userId, name: actorName },- target: { type: PrincipalType.ROLE, id: roleName, name: roleName },- metadata: { capability: grant.capability },- context,- /** Scope each entry to the removed grant's own tenant — a platform- * admin's role deletion can remove tenant-scoped grants, and those- * removals must land in the affected tenant's chain, not the caller's. */- tenantId: grant.tenantId,- });- } catch (err) {- logger.error('[adminRoles] grant.removed audit failed during role deletion', err);- }+ await emitRevocationAudit(req, {+ action: 'grant.removed',+ severity: 'warning',+ target: { type: PrincipalType.ROLE, id: roleName, name: roleName },+ metadata: { capability: grant.capability },+ /** Scope each entry to the removed grant's own tenant: a platform+ * admin's role deletion can remove tenant-scoped grants, and those+ * removals must land in the affected tenant's chain, not the caller's. */+ tenantId: grant.tenantId,+ });}}@@ -216,7 +256,7 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {const [roles, total] = await Promise.all([listRoles({ limit, offset }), countRoles()]);return res.status(200).json({ roles, total, limit, offset });} catch (error) {- logger.error('[adminRoles] listRoles error:', error);+ logger.error('[adminRoles] listRoles error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to list roles' });}}@@ -234,7 +274,7 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}return res.status(200).json({ role });} catch (error) {- logger.error('[adminRoles] getRole error:', error);+ logger.error('[adminRoles] getRole error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get role' });}}@@ -268,9 +308,15 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {roleData.description = description;}const role = await createRoleByName(roleData);+ const changes = diffRolePermissions(undefined, role.permissions);+ await emitAudit(req, {+ action: 'role.created',+ target: roleTarget(role.name),+ metadata: { permissions: changes.join(', ') || null },+ });return res.status(201).json({ role });} catch (error) {- logger.error('[adminRoles] createRole error:', error);+ logger.error('[adminRoles] createRole error:', getSafeErrorMetadata(error));if (error instanceof RoleConflictError) {return res.status(409).json({ error: error.message });}@@ -367,7 +413,8 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {if (isRename) {updates.name = trimmedName;}- if (body.description !== undefined) {+ /** A description equal to the stored one is not a change: no write and no audit entry. */+ if (body.description !== undefined && body.description !== existing.description) {updates.description = body.description;}@@ -377,11 +424,16 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {if (isRename) {const descUpdate =- body.description !== undefined ? { description: body.description } : undefined;+ updates.description !== undefined ? { description: updates.description } : undefined;const role = await renameRole(name, trimmedName, descUpdate);if (!role) {return res.status(404).json({ error: 'Role not found' });}+ await emitAudit(req, {+ action: 'role.updated',+ target: roleTarget(trimmedName),+ metadata: { previousName: name, descriptionChanged: descUpdate !== undefined },+ });return res.status(200).json({ role });}@@ -389,12 +441,17 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {if (!role) {return res.status(404).json({ error: 'Role not found' });}+ await emitAudit(req, {+ action: 'role.updated',+ target: roleTarget(name),+ metadata: { descriptionChanged: true },+ });return res.status(200).json({ role });} catch (error) {if (error instanceof RoleConflictError) {return res.status(409).json({ error: error.message });}- logger.error('[adminRoles] updateRole error:', error);+ logger.error('[adminRoles] updateRole error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to update role' });}}@@ -430,14 +487,32 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {if (!updated) {return res.status(404).json({ error: 'Role not found' });}+ const changes = diffRolePermissions(existing.permissions, updated.permissions);+ if (changes.length > 0) {+ await emitAudit(req, {+ action: 'role.permissions_updated',+ severity: 'warning',+ target: roleTarget(name),+ metadata: { changes: changes.join(', '), changeCount: changes.length },+ });+ }return res.status(200).json({ role: updated });} catch (error) {- logger.error('[adminRoles] updateRolePermissions error:', error);+ logger.error('[adminRoles] updateRolePermissions error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to update role permissions' });}}async function deleteRoleHandler(req: ServerRequest, res: Response) {+ /** Set once the deletion attempt is recorded; the outer catch uses it for unexpected failures. */+ let recordOutcome:+ | ((+ outcome: 'success' | 'failure',+ code?: string,+ metadata?: Record<string, number>,+ ) => Promise<void>)+ | undefined;+ let waitForAttempt: () => Promise<void> = async () => undefined;try {const { name } = req.params as RoleNameParams;const paramError = validateNameParam(name);@@ -448,33 +523,207 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {return res.status(403).json({ error: 'Cannot delete system role' });}- const deleted = await deleteRoleByName(name);- if (!deleted) {+ const existing = await getRoleByName(name);+ if (!existing) {return res.status(404).json({ error: 'Role not found' });}+ /**+ * The attempt is recorded as `pending` before any removal so a crash mid-cascade still+ * leaves a trail. The write is started without being awaited, so audit latency never+ * delays the revocation; every later entry waits for it to keep the chain ordered.+ */+ const target = roleTarget(name);+ const attempt = emitRevocationAudit(req, {+ action: 'role.deleted',+ outcome: 'pending',+ severity: 'warning',+ target,+ });+ waitForAttempt = () => attempt;+ recordOutcome = async (outcome, code, metadata) => {+ await attempt;+ await emitRevocationAudit(req, {+ action: 'role.deleted',+ outcome,+ severity: 'warning',+ target,+ ...(code || metadata ? { metadata: { ...(code ? { code } : {}), ...metadata } } : {}),+ });+ };++ /**+ * Grants, ACL entries and config overrides are keyed by role name, so they+ * are removed before the role itself: if any removal fails the role stays+ * and the admin can retry, instead of a later role with the same name+ * inheriting the leftovers. Every removal is idempotent.+ */const tenantId = req.user?.tenantId;- const [configResult, aclResult, grantsResult] = await Promise.allSettled([- deleteConfig(PrincipalType.ROLE, name),- deleteAclEntries({ principalType: PrincipalType.ROLE, principalId: name }),- deleteGrantsForPrincipal(PrincipalType.ROLE, name, { tenantId }),- ]);- for (const result of [configResult, aclResult, grantsResult]) {- if (result.status === 'rejected') {- logger.error('[adminRoles] cascade cleanup failed for role:', name, result.reason);+ /** deleteRoleByName reassigns members to USER, so who held the role is read first. */+ const memberIds = await findUserIdsByRole(name);+ /** The grants as they were, so removals are audited even when a removal rejects after committing. */+ const grantSnapshot = findGrantsForPrincipal+ ? await findGrantsForPrincipal(PrincipalType.ROLE, name, { tenantId })+ : null;+ const cascade = await runCascade(+ [+ cascadeStep(+ 'config',+ () => deleteConfig(PrincipalType.ROLE, name),+ restoreConfig+ ? async (config) => {+ if (!config) {+ return;+ }+ /** Insert-only: an override written after the snapshot is kept. */+ const plain = (config as { toObject?: () => unknown }).toObject?.() ?? config;+ const restored = await restoreConfig(plain as Record<string, unknown>);+ if (!restored) {+ logger.warn('[adminRoles] config restore skipped, override exists:', name);+ }+ }+ : undefined,+ findConfigByPrincipal+ ? () => findConfigByPrincipal(PrincipalType.ROLE, name, { includeInactive: true })+ : undefined,+ ),+ cascadeStep('acl', async () => {+ await deleteAclEntries({ principalType: PrincipalType.ROLE, principalId: name });+ }),+ cascadeStep('grants', () =>+ deleteGrantsForPrincipal(PrincipalType.ROLE, name, { tenantId }),+ ),+ ],+ '[adminRoles]',+ );++ /** The removed ACL entries can include PROMPTGROUP grants feeding the access+ * cache; the cache is stale after both a removal and a restore. */+ const invalidateAccess = async () => {+ try {+ await invalidatePromptGroupAccessContext?.();+ } catch (error) {+ /** The deletion already committed; a cache failure must not hide it from the audit trail. */+ logger.error(+ '[adminRoles] access cache invalidation failed:',+ getSafeErrorMetadata(error),+ );}+ };+ const cleanupFailedResponse = async () => {+ await recordOutcome?.('failure', 'ROLE_CLEANUP_FAILED');+ return res.status(500).json({+ error: 'Failed to remove the role grants and permissions; the role was not deleted',+ code: 'ROLE_CLEANUP_FAILED',+ });+ };++ /** Grants are never restored, so a failed delete still changed access and is audited. */+ const auditRemovedGrants = async () => {+ await waitForAttempt();+ let removed = cascade.removed.grants as ISystemGrant[] | undefined;+ if (!removed && grantSnapshot?.length && findGrantsForPrincipal) {+ /** The removal rejected and may have committed: audit what is no longer there. */+ const remaining = await findGrantsForPrincipal(PrincipalType.ROLE, name, {+ tenantId,+ }).then(+ (grants) => new Set(grants.map((g) => `${g.tenantId ?? ''}:${g.capability}`)),+ () => null,+ );+ removed = remaining+ ? grantSnapshot.filter((g) => !remaining.has(`${g.tenantId ?? ''}:${g.capability}`))+ : [];+ }+ await emitGrantRemovals(req, name, removed ?? []);+ };++ /** Reads the role again to learn whether it still is the one this request targeted. */+ const lookupRole = () =>+ getRoleByName(name).then(+ (role) => ({ known: true, role }),+ () => ({ known: false, role: null }),+ );+ /** A role recreated under the same name is a different role and must not inherit the+ * old one's dependents. */+ const isTargetedRole = (role: IRole | null) =>+ role != null &&+ (existing._id == null || role._id == null || String(existing._id) === String(role._id));++ if (cascade.failed.length > 0) {+ const lookup = await lookupRole();+ if (lookup.known && isTargetedRole(lookup.role)) {+ await cascade.compensate();+ } else {+ logger.warn('[adminRoles] config not restored, role changed during cleanup:', name);+ }+ await invalidateAccess();+ await auditRemovedGrants();+ return cleanupFailedResponse();}- if (aclResult.status === 'fulfilled') {- /** The removed entries can include PROMPTGROUP grants feeding the access cache */- await invalidatePromptGroupAccessContext?.();++ let deleted: IRole | null;+ try {+ deleted = await deleteRoleByName(name, {+ id: existing._id != null ? String(existing._id) : undefined,+ });+ } catch (error) {+ logger.error(+ '[adminRoles] deleteRole failed after cascade cleanup:',+ getSafeErrorMetadata(error),+ );+ /** The delete may have committed before it threw. Restoring dependents for a+ * role that is gone would orphan them for a later role with the same name. */+ const lookup = await lookupRole();+ if (lookup.known && isTargetedRole(lookup.role)) {+ await cascade.compensate();+ await invalidateAccess();+ await auditRemovedGrants();+ await recordOutcome('failure', 'ROLE_CLEANUP_FAILED');+ return res.status(500).json({ error: 'Failed to delete role' });+ }+ await invalidateAccess();+ if (!lookup.known || lookup.role) {+ await auditRemovedGrants();+ await recordOutcome('failure', 'ROLE_STATE_UNVERIFIABLE');+ logger.error('[adminRoles] dependents not restored, role state unverifiable:', name);+ return res.status(500).json({ error: 'Failed to delete role' });+ }+ /** Confirmed absent: the deletion did commit, so it is audited and reported as one. */+ deleted = existing;+ }+ await invalidateAccess();+ if (!deleted) {+ await auditRemovedGrants();+ await recordOutcome('failure', 'not_found');+ return res.status(404).json({ error: 'Role not found' });}- if (grantsResult.status === 'fulfilled') {- await emitGrantRemovals(req, name, grantsResult.value);+ const removedGrants = cascade.removed.grants as ISystemGrant[];+ await auditRemovedGrants();+ /** Each reassigned account is recorded (chunked) before the outcome entry. */+ const audited = memberIds;+ for (let i = 0; i < audited.length; i += AUDIT_MEMBER_CHUNK) {+ const chunk = audited.slice(i, i + AUDIT_MEMBER_CHUNK);+ await emitRevocationAudit(req, {+ action: 'role.member_removed',+ severity: memberChangeSeverity(name),+ target: roleTarget(name),+ metadata: {+ userIds: chunk.join(','),+ count: chunk.length,+ newRole: SystemRoles.USER,+ cause: 'role_deleted',+ },+ });}+ await recordOutcome('success', undefined, {+ grantsRemoved: removedGrants.length,+ membersReassigned: memberIds.length,+ });return res.status(200).json({ success: true });} catch (error) {- logger.error('[adminRoles] deleteRole error:', error);+ logger.error('[adminRoles] deleteRole error:', getSafeErrorMetadata(error));+ await recordOutcome?.('failure', 'ROLE_DELETE_FAILED').catch(() => undefined);return res.status(500).json({ error: 'Failed to delete role' });}}@@ -505,7 +754,7 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}));return res.status(200).json({ members, total, limit, offset });} catch (error) {- logger.error('[adminRoles] getRoleMembers error:', error);+ logger.error('[adminRoles] getRoleMembers error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to get role members' });}}@@ -551,9 +800,18 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}}- const updated = await updateUser(userId, { role: name });+ /** Conditional on the role read above: an overlapping identical request matches nothing,+ * so exactly one request records the transition. */+ const updated = await updateUser(userId, { role: name }, { role: user.role });if (!updated) {- return res.status(404).json({ error: 'User not found' });+ const current = await findUser({ _id: userId });+ if (!current) {+ return res.status(404).json({ error: 'User not found' });+ }+ if (current.role === name) {+ return res.status(200).json({ success: true });+ }+ return res.status(409).json({ error: 'User role changed concurrently' });}if (user.role === SystemRoles.ADMIN && name !== SystemRoles.ADMIN) {@@ -571,9 +829,24 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}}+ await emitAudit(req, {+ action: 'role.member_added',+ severity: memberChangeSeverity(name, user.role),+ target: roleTarget(name),+ metadata: { userId, previousRole: user.role ?? null },+ });+ /** The single-role write also ends the user's membership of the previous role. */+ if (user.role) {+ await emitAudit(req, {+ action: 'role.member_removed',+ severity: memberChangeSeverity(user.role),+ target: roleTarget(user.role),+ metadata: { userId, newRole: name },+ });+ }return res.status(200).json({ success: true });} catch (error) {- logger.error('[adminRoles] addRoleMember error:', error);+ logger.error('[adminRoles] addRoleMember error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to add role member' });}}@@ -614,9 +887,16 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}}- const removed = await updateUser(userId, { role: SystemRoles.USER });+ const removed = await updateUser(userId, { role: SystemRoles.USER }, { role: name });if (!removed) {- return res.status(404).json({ error: 'User not found' });+ const current = await findUser({ _id: userId });+ if (!current) {+ return res.status(404).json({ error: 'User not found' });+ }+ if (current.role !== name) {+ return res.status(400).json({ error: 'User is not a member of this role' });+ }+ return res.status(409).json({ error: 'User role changed concurrently' });}if (name === SystemRoles.ADMIN) {@@ -634,9 +914,15 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {}}+ await emitAudit(req, {+ action: 'role.member_removed',+ severity: memberChangeSeverity(name),+ target: roleTarget(name),+ metadata: { userId, newRole: SystemRoles.USER },+ });return res.status(200).json({ success: true });} catch (error) {- logger.error('[adminRoles] removeRoleMember error:', error);+ logger.error('[adminRoles] removeRoleMember error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to remove role member' });}}@@ -653,3 +939,92 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {removeRoleMember: removeRoleMemberHandler,};}++export interface RolePermissionsUpdateDeps {+ getRoleByName: (name: string, fields?: string | string[] | null) => Promise<IRole | null>;+ updateRoleByName: (name: string, updates: Partial<IRole>) => Promise<IRole | null>;+ recordAuditEntry?: RecordAuditEntry;+ /** When true, a failed audit write surfaces as a 5xx after the update has+ * been persisted. Defaults to fail-open. */+ auditFailClosed?: boolean;+}++export interface RolePermissionsUpdateConfig {+ /** Zod object schema for one permission type; parsed as a partial update. */+ schema: { partial: () => { parse: (value: unknown) => Record<string, boolean | undefined> } };+ permissionType: string;+ errorMessage: string;+}++/**+ * Builds the `PUT /api/roles/:roleName/<type>` handler for one permission type:+ * merges the validated partial update into the role's permissions and records+ * a `role.permissions_updated` audit entry when a flag actually changed.+ */+export function createRolePermissionsUpdateHandler(+ deps: RolePermissionsUpdateDeps,+ config: RolePermissionsUpdateConfig,+): (req: ServerRequest, res: Response) => Promise<Response> {+ const { getRoleByName, updateRoleByName, recordAuditEntry, auditFailClosed } = deps;+ const emitAudit = createAdminAuditEmitter({+ recordAuditEntry,+ failClosed: auditFailClosed,+ logPrefix: '[roles]',+ });++ return async function updateRolePermissions(req, res) {+ const { roleName } = req.params as { roleName: string };+ let parsedUpdates: Record<string, boolean | undefined>;+ try {+ parsedUpdates = config.schema.partial().parse(req.body);+ } catch (error) {+ return res+ .status(400)+ .send({ message: config.errorMessage, error: (error as { errors?: unknown }).errors });+ }++ try {+ const role = await getRoleByName(roleName);+ if (!role) {+ return res.status(404).send({ message: 'Role not found' });+ }++ const permissions = (role.permissions ?? {}) as Record<+ string,+ Record<string, boolean | undefined> | undefined+ >;+ const legacyPermissions = (role as unknown as Record<string, unknown>)[+ config.permissionType+ ] as Record<string, boolean | undefined> | undefined;+ const currentPermissions = permissions[config.permissionType] || legacyPermissions || {};++ const mergedPermissions = {+ ...permissions,+ [config.permissionType]: { ...currentPermissions, ...parsedUpdates },+ };+ const updatedRole = await updateRoleByName(roleName, {+ permissions: mergedPermissions as IRole['permissions'],+ });++ const changes = diffRolePermissions(+ { [config.permissionType]: currentPermissions },+ { [config.permissionType]: mergedPermissions[config.permissionType] },+ );+ if (updatedRole && changes.length > 0) {+ await emitAudit(req, {+ action: 'role.permissions_updated',+ severity: 'warning',+ target: roleTarget(roleName),+ metadata: { changes: changes.join(', '), changeCount: changes.length },+ });+ }+ return res.status(200).send(updatedRole);+ } catch (error) {+ logger.error(+ `[roles] ${config.permissionType} permission update failed:`,+ getSafeErrorMetadata(error),+ );+ return res.status(500).send({ message: 'Failed to update role permissions' });+ }+ };+}diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.tsindex 0580855699..8743eac7c0 100644--- a/packages/api/src/admin/secrets.integration.spec.ts+++ b/packages/api/src/admin/secrets.integration.spec.ts@@ -260,7 +260,7 @@ beforeAll(async () => {tombstoneConfigField: methods.tombstoneConfigField,unsetConfigField: methods.unsetConfigField,deleteConfig: methods.deleteConfig,- toggleConfigActive: methods.toggleConfigActive,+ toggleConfigActiveTracked: methods.toggleConfigActiveTracked,hasConfigCapability: async () => true,hasAnyConfigReadAccess: async () => true,hasCapability: async () => true,@@ -716,7 +716,7 @@ describe('config secret registry — real handlers against a real Config collecttombstoneConfigField: async () => null,unsetConfigField: async () => null,deleteConfig: async () => null,- toggleConfigActive: async () => null,+ toggleConfigActiveTracked: async () => null,hasConfigCapability: async () => true,hasAnyConfigReadAccess: async () => true,hasCapability: async () => true,diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.tsindex a67e96d1d1..74942b6554 100644--- a/packages/api/src/app/permissions.spec.ts+++ b/packages/api/src/app/permissions.spec.ts@@ -3128,3 +3128,181 @@ describe('updateInterfacePermissions - native web search warning', () => {expect(nativeWarnings()).toHaveLength(0);});});++describe('updateInterfacePermissions - role.synced audit', () => {+ type StoredPermissions = Record<string, Record<string, boolean>>;++ /** Role store whose writes mirror `updateAccessPermissions`' merge. */+ function createRoleStore(initial: Record<string, StoredPermissions>) {+ const roles = new Map(+ Object.entries(initial).map(([name, permissions]) => [name, { name, permissions }]),+ );+ const getRoleByName = jest.fn(async (name: string) => {+ const role = roles.get(name);+ return role ? (structuredClone(role) as unknown as IRole) : null;+ });+ const updateAccessPermissions = jest.fn(+ async (name: string, update: Record<string, Record<string, boolean | undefined>>) => {+ const role = roles.get(name);+ if (!role) {+ return;+ }+ for (const [permType, fields] of Object.entries(update)) {+ const next = { ...(role.permissions[permType] ?? {}) };+ for (const [field, value] of Object.entries(fields)) {+ if (value !== undefined) {+ next[field] = value;+ }+ }+ role.permissions[permType] = next;+ }+ },+ );+ return { getRoleByName, updateAccessPermissions };+ }++ async function run(+ config: Partial<TCustomConfig>,+ store: ReturnType<typeof createRoleStore>,+ recordAuditEntry: jest.Mock,+ ) {+ const configDefaults = { interface: {} } as TConfigDefaults;+ const interfaceConfig = await loadDefaultInterface({ config, configDefaults });+ const appConfig = { config, interfaceConfig } as unknown as AppConfig;+ await updateInterfacePermissions({+ appConfig,+ getRoleByName: store.getRoleByName,+ updateAccessPermissions: store.updateAccessPermissions,+ recordAuditEntry,+ });+ }++ /** Every permission type a role needs so the sync only touches explicit config. */+ function fullPermissions(role: SystemRoles): StoredPermissions {+ return structuredClone(roleDefaults[role].permissions) as unknown as StoredPermissions;+ }++ it('records role.synced with the persisted changes as a system actor', async () => {+ const user = fullPermissions(SystemRoles.USER);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: true };+ const store = createRoleStore({+ [SystemRoles.USER]: user,+ [SystemRoles.ADMIN]: fullPermissions(SystemRoles.ADMIN),+ });+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await run({ interface: { bookmarks: false } }, store, recordAuditEntry);++ const userEntry = recordAuditEntry.mock.calls.find(+ ([input]) => input.target.id === SystemRoles.USER,+ )?.[0];+ expect(userEntry).toEqual(+ expect.objectContaining({+ action: 'role.synced',+ actor: { type: 'system', name: 'librechat.yaml interface sync' },+ target: { type: 'role', id: SystemRoles.USER, name: SystemRoles.USER },+ metadata: expect.objectContaining({+ changes: expect.stringContaining('BOOKMARKS.USE=false'),+ }),+ }),+ );+ });++ it('records nothing when the stored permissions already match the config', async () => {+ const user = fullPermissions(SystemRoles.USER);+ const admin = fullPermissions(SystemRoles.ADMIN);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: false };+ admin[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: false };+ const store = createRoleStore({ [SystemRoles.USER]: user, [SystemRoles.ADMIN]: admin });+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await run({ interface: { bookmarks: false } }, store, recordAuditEntry);++ expect(store.updateAccessPermissions).toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('records a change the updater persisted even when the requested values already matched', async () => {+ const user = fullPermissions(SystemRoles.USER);+ const admin = fullPermissions(SystemRoles.ADMIN);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: false };+ admin[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: false };+ const store = createRoleStore({ [SystemRoles.USER]: user, [SystemRoles.ADMIN]: admin });+ const write = store.updateAccessPermissions.getMockImplementation()!;+ /** A legacy-document migration changes a flag the config never requested. */+ store.updateAccessPermissions.mockImplementation(async (name, update) => {+ await write(name, update);+ if (name === SystemRoles.USER) {+ await write(name, { [PermissionTypes.PROMPTS]: { [Permissions.USE]: false } });+ }+ });+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await run({ interface: { bookmarks: false } }, store, recordAuditEntry);++ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'role.synced',+ target: { type: 'role', id: SystemRoles.USER, name: SystemRoles.USER },+ }),+ );+ });++ it('records nothing when the write did not persist', async () => {+ const user = fullPermissions(SystemRoles.USER);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: true };+ const store = createRoleStore({+ [SystemRoles.USER]: user,+ [SystemRoles.ADMIN]: fullPermissions(SystemRoles.ADMIN),+ });+ store.updateAccessPermissions.mockResolvedValue(undefined);+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await run({ interface: { bookmarks: false } }, store, recordAuditEntry);++ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not fail startup when the verification read fails', async () => {+ const user = fullPermissions(SystemRoles.USER);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: true };+ const store = createRoleStore({+ [SystemRoles.USER]: user,+ [SystemRoles.ADMIN]: fullPermissions(SystemRoles.ADMIN),+ });+ const read = store.getRoleByName.getMockImplementation()!;+ let calls = 0;+ store.getRoleByName.mockImplementation(async (name: string) => {+ calls += 1;+ /** The first read per role loads it; the second is the post-sync verification. */+ if (calls === 2) {+ throw new Error('mongo unavailable');+ }+ return read(name);+ });+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await expect(+ run({ interface: { bookmarks: false } }, store, recordAuditEntry),+ ).resolves.toBeUndefined();+ expect(store.updateAccessPermissions).toHaveBeenCalledTimes(2);+ expect(recordAuditEntry).not.toHaveBeenCalledWith(+ expect.objectContaining({ target: expect.objectContaining({ id: SystemRoles.USER }) }),+ );+ });++ it('does not fail startup when the audit write fails', async () => {+ const user = fullPermissions(SystemRoles.USER);+ user[PermissionTypes.BOOKMARKS] = { [Permissions.USE]: true };+ const store = createRoleStore({+ [SystemRoles.USER]: user,+ [SystemRoles.ADMIN]: fullPermissions(SystemRoles.ADMIN),+ });+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));++ await expect(+ run({ interface: { bookmarks: false } }, store, recordAuditEntry),+ ).resolves.toBeUndefined();+ expect(recordAuditEntry).toHaveBeenCalled();+ });+});diff --git a/packages/api/src/app/permissions.ts b/packages/api/src/app/permissions.tsindex 9a5960a8e7..1dafb242f2 100644--- a/packages/api/src/app/permissions.ts+++ b/packages/api/src/app/permissions.ts@@ -1,4 +1,4 @@-import { logger, tenantStorage, SYSTEM_TENANT_ID } from '@librechat/data-schemas';+import { logger, getTenantId, tenantStorage, SYSTEM_TENANT_ID } from '@librechat/data-schemas';import {SystemRoles,Permissions,@@ -7,8 +7,13 @@ import {getConfigDefaults,} from 'librechat-data-provider';import type { IRole, AppConfig } from '@librechat/data-schemas';+import type { RecordAuditEntry } from '~/admin/audit';+import { diffRolePermissions, recordSystemAuditEntry } from '~/admin/audit';+import { getSafeErrorMetadata } from '~/utils/errors';import { isMemoryEnabled } from '~/memory/config';+type RolePermissions = Partial<Record<PermissionTypes, Record<string, boolean | undefined>>>;+/*** Checks if a permission type has explicit configuration*/@@ -100,6 +105,7 @@ export async function updateInterfacePermissions({appConfig,getRoleByName,updateAccessPermissions,+ recordAuditEntry,tenantId,}: {appConfig: AppConfig;@@ -110,6 +116,8 @@ export async function updateInterfacePermissions({roleData?: IRole | null,) => Promise<void>;+ /** Records a `role.synced` entry for each role whose stored permissions changed. */+ recordAuditEntry?: RecordAuditEntry;/*** Optional tenant ID for scoping role updates to a specific tenant.* When provided (and not SYSTEM_TENANT_ID), runs inside `tenantStorage.run({ tenantId })`.@@ -119,7 +127,12 @@ export async function updateInterfacePermissions({}): Promise<void> {if (tenantId && tenantId !== SYSTEM_TENANT_ID) {return tenantStorage.run({ tenantId }, async () =>- updateInterfacePermissions({ appConfig, getRoleByName, updateAccessPermissions }),+ updateInterfacePermissions({+ appConfig,+ getRoleByName,+ updateAccessPermissions,+ recordAuditEntry,+ }),);}@@ -155,6 +168,42 @@ export async function updateInterfacePermissions({const defaults = getConfigDefaults().interface;const webSearchDeniedRoles: string[] = [];+ /**+ * Re-reads the role so the entry lists what was persisted rather than what was+ * requested (`updateAccessPermissions` logs and swallows its own failures).+ */+ const recordRoleSync = async (roleName: string, before: RolePermissions | undefined) => {+ let after: IRole | null;+ let changes: string[];+ try {+ after = await getRoleByName(roleName);+ changes = diffRolePermissions(before, after?.permissions as RolePermissions | undefined);+ } catch (err) {+ /** The verification read is part of auditing, which must not fail startup. */+ logger.error(+ `[updateInterfacePermissions] could not verify '${roleName}' for audit`,+ getSafeErrorMetadata(err),+ );+ return;+ }+ if (!after || changes.length === 0) {+ return;+ }+ const tenantId = getTenantId();+ await recordSystemAuditEntry(+ recordAuditEntry,+ {+ action: 'role.synced',+ severity: 'warning',+ actor: { type: 'system', name: 'librechat.yaml interface sync' },+ target: { type: 'role', id: roleName, name: roleName },+ metadata: { changes: changes.join(', '), changeCount: changes.length },+ tenantId: tenantId && tenantId !== SYSTEM_TENANT_ID ? tenantId : undefined,+ },+ '[updateInterfacePermissions]',+ );+ };+// Permission precedence order:// 1. Explicit user configuration (from librechat.yaml)// 2. Role-specific defaults (from roleDefaults)@@ -807,6 +856,9 @@ export async function updateInterfacePermissions({// Update permissions if any need updatingif (Object.keys(permissionsToUpdate).length > 0) {await updateAccessPermissions(roleName, permissionsToUpdate, existingRole);+ if (recordAuditEntry) {+ await recordRoleSync(roleName, existingPermissions);+ }}}diff --git a/packages/api/src/auth/openidRoleSync.spec.ts b/packages/api/src/auth/openidRoleSync.spec.tsindex 4451d31f76..ad48272242 100644--- a/packages/api/src/auth/openidRoleSync.spec.ts+++ b/packages/api/src/auth/openidRoleSync.spec.ts@@ -4,6 +4,7 @@ import {getOpenIdRolesForOpenIdSync,getLibreChatRolesForOpenIdSync,selectOpenIdRole,+ recordIdpRoleChange,} from './openidRoleSync';describe('getOpenIdRoleSyncOptions', () => {@@ -396,3 +397,74 @@ describe('selectOpenIdRole', () => {});});});++describe('recordIdpRoleChange', () => {+ it('records an IdP admin grant as a critical user.role_changed entry', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await recordIdpRoleChange({+ recordAuditEntry,+ userId: 'u1',+ previousRole: SystemRoles.USER,+ role: SystemRoles.ADMIN,+ source: 'openid_login',+ tenantId: 't1',+ });++ expect(recordAuditEntry).toHaveBeenCalledWith({+ action: 'user.role_changed',+ severity: 'critical',+ actor: { type: 'system', name: 'OpenID role sync' },+ target: { type: 'user', id: 'u1' },+ metadata: { previousRole: SystemRoles.USER, role: SystemRoles.ADMIN, source: 'openid_login' },+ tenantId: 't1',+ });+ });++ it('records a non-admin change at warning severity', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await recordIdpRoleChange({+ recordAuditEntry,+ userId: 'u1',+ previousRole: SystemRoles.USER,+ role: 'STAFF',+ source: 'openid_login',+ });++ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ severity: 'warning',+ metadata: expect.objectContaining({ role: 'STAFF' }),+ }),+ );+ });++ it('records nothing when the role did not change', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);++ await recordIdpRoleChange({+ recordAuditEntry,+ userId: 'u1',+ previousRole: SystemRoles.ADMIN,+ role: SystemRoles.ADMIN,+ source: 'openid_login',+ });++ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not throw when the audit write fails', async () => {+ const recordAuditEntry = jest.fn().mockRejectedValue(new Error('audit down'));++ await expect(+ recordIdpRoleChange({+ recordAuditEntry,+ userId: 'u1',+ previousRole: SystemRoles.ADMIN,+ role: SystemRoles.USER,+ source: 'openid_login',+ }),+ ).resolves.toBeUndefined();+ });+});diff --git a/packages/api/src/auth/openidRoleSync.ts b/packages/api/src/auth/openidRoleSync.tsindex 3f028213ee..d41fa45bd4 100644--- a/packages/api/src/auth/openidRoleSync.ts+++ b/packages/api/src/auth/openidRoleSync.ts@@ -1,5 +1,7 @@import { get } from 'lodash';import { SystemRoles } from 'librechat-data-provider';+import type { RecordAuditEntry } from '~/admin/audit';+import { recordSystemAuditEntry } from '~/admin/audit';import { isEnabled } from '~/utils';export type OpenIdRoleSyncClaimSource = 'access' | 'id' | 'userinfo';@@ -312,3 +314,41 @@ export function selectOpenIdRole(return { reason: 'no_matching_role' };}++/**+ * Records a `user.role_changed` entry when an IdP claim moved a user to a new+ * role (OpenID admin-role claim or role sync). No-op when the role is unchanged.+ * Fail-open, since it runs inside login and API authentication.+ */+export async function recordIdpRoleChange({+ recordAuditEntry,+ userId,+ previousRole,+ role,+ source,+ tenantId,+}: {+ recordAuditEntry?: RecordAuditEntry;+ userId: string;+ previousRole?: string | null;+ role?: string | null;+ source: 'openid_login' | 'remote_agent_oidc';+ tenantId?: string;+}): Promise<void> {+ if (!role || role === previousRole) {+ return;+ }+ const adminChange = role === SystemRoles.ADMIN || previousRole === SystemRoles.ADMIN;+ await recordSystemAuditEntry(+ recordAuditEntry,+ {+ action: 'user.role_changed',+ severity: adminChange ? 'critical' : 'warning',+ actor: { type: 'system', name: 'OpenID role sync' },+ target: { type: 'user', id: userId },+ metadata: { previousRole: previousRole ?? null, role, source },+ tenantId,+ },+ '[openidRoleSync]',+ );+}diff --git a/packages/api/src/middleware/remoteAgentAuth.spec.ts b/packages/api/src/middleware/remoteAgentAuth.spec.tsindex 1fe57d8782..087d58e391 100644--- a/packages/api/src/middleware/remoteAgentAuth.spec.ts+++ b/packages/api/src/middleware/remoteAgentAuth.spec.ts@@ -224,7 +224,7 @@ function makeFindUser(...users: IUser[]): jest.MockedFunction<UserMethods['findUfunction makeDeps(appConfig: AppConfig = makeConfig()) {return {findUser: makeFindUser(makeUser()),- updateUser: jest.fn(),+ updateUser: jest.fn().mockResolvedValue({ _id: 'uid123' }),getRolesByNames: jest.fn(async (roleNames: string[]) =>roleNames.map((roleName) => ({ name: roleName })),),@@ -1618,6 +1618,70 @@ describe('createRemoteAgentAuth', () => {expect(mockNext).toHaveBeenCalled();});+ it('records a user.role_changed audit entry after persisting a synced role', async () => {+ enableApiRoleSync();+ setupOidcMocks({ sub: 'sub123', email: '[email protected]', roles: ['STANDARD-USER'] });++ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = { ...makeDeps(), recordAuditEntry };+ await createRemoteAgentAuth(asDeps(deps))(+ makeReq({ authorization: `Bearer ${FAKE_TOKEN}` }) as Request,+ makeRes().res,+ mockNext,+ );++ expect(deps.updateUser).toHaveBeenCalledWith('uid123', { role: 'STANDARD-USER' });+ expect(recordAuditEntry).toHaveBeenCalledWith(+ expect.objectContaining({+ action: 'user.role_changed',+ actor: expect.objectContaining({ type: 'system' }),+ target: { type: 'user', id: 'uid123' },+ metadata: expect.objectContaining({+ role: 'STANDARD-USER',+ source: 'remote_agent_oidc',+ }),+ }),+ );+ expect(mockNext).toHaveBeenCalled();+ });++ it('does not record an audit entry when the synced role was not persisted', async () => {+ enableApiRoleSync();+ setupOidcMocks({ sub: 'sub123', email: '[email protected]', roles: ['STANDARD-USER'] });++ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const base = makeDeps();+ const deps = { ...base, updateUser: jest.fn().mockResolvedValue(null), recordAuditEntry };+ await createRemoteAgentAuth(asDeps(deps))(+ makeReq({ authorization: `Bearer ${FAKE_TOKEN}` }) as Request,+ makeRes().res,+ mockNext,+ );++ expect(deps.updateUser).toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('does not record an audit entry when role sync keeps the current role', async () => {+ enableApiRoleSync();+ setupOidcMocks({ sub: 'sub123', email: '[email protected]', roles: ['STANDARD-USER'] });++ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const deps = {+ ...makeDeps(),+ findUser: makeFindUser(makeUser({ role: 'STANDARD-USER' })),+ recordAuditEntry,+ };+ await createRemoteAgentAuth(asDeps(deps))(+ makeReq({ authorization: `Bearer ${FAKE_TOKEN}` }) as Request,+ makeRes().res,+ mockNext,+ );++ expect(recordAuditEntry).not.toHaveBeenCalled();+ expect(mockNext).toHaveBeenCalled();+ });+it('applies fallback when the verified payload has no configured role match', async () => {enableApiRoleSync();setupOidcMocks({diff --git a/packages/api/src/middleware/remoteAgentAuth.ts b/packages/api/src/middleware/remoteAgentAuth.tsindex 1384a8fc4d..d81fc7dfa5 100644--- a/packages/api/src/middleware/remoteAgentAuth.ts+++ b/packages/api/src/middleware/remoteAgentAuth.ts@@ -5,6 +5,7 @@ import type { RequestHandler, Request, Response, NextFunction } from 'express';import type { TAgentsEndpoint } from 'librechat-data-provider';import type { JwtPayload } from 'jsonwebtoken';import type { GetAppConfigOptions } from '../app/service';+import type { RecordAuditEntry } from '~/admin/audit';import type { ServerRequest } from '~/types/http';import type { ContextRequest } from './tenant';import {@@ -12,6 +13,7 @@ import {getOpenIdRolesForOpenIdSync,getOpenIdRoleSyncOptions,selectOpenIdRole,+ recordIdpRoleChange,} from '../auth/openidRoleSync';import { clearOidcAccessTokenCache, extractBearerToken, verifyOidcAccessToken } from '../auth/oidc';import { findOpenIDUser, getOpenIdEmail, normalizeOpenIdIssuer } from '../auth/openid';@@ -24,6 +26,8 @@ export interface RemoteAgentAuthDeps {updateUser: UserMethods['updateUser'];isPrincipalActive: (userId: string) => Promise<boolean>;getAppConfig: (options?: GetAppConfigOptions) => Promise<AppConfig>;+ /** Records role changes made by OpenID role sync; fail-open. */+ recordAuditEntry?: RecordAuditEntry;}type OidcConfig = NonNullable<@@ -332,18 +336,17 @@ async function selectOpenIdRoleForOpenIdSync(async function updateResolvedUser(userResolution: Extract<UserResolution, { status: 'resolved' }>,updateUser: RemoteAgentAuthDeps['updateUser'],-): Promise<void> {+): Promise<boolean> {if (Object.keys(userResolution.updateData).length === 0) {- return;+ return true;}const update = async () => updateUser(userResolution.user.id, userResolution.updateData);if (userResolution.user.tenantId && getTenantId() !== userResolution.user.tenantId) {- await tenantStorage.run({ tenantId: userResolution.user.tenantId }, update);- return;+ return Boolean(await tenantStorage.run({ tenantId: userResolution.user.tenantId }, update));}- await update();+ return Boolean(await update());}/**@@ -374,6 +377,7 @@ export function createRemoteAgentAuth({updateUser,isPrincipalActive,getAppConfig,+ recordAuditEntry,}: RemoteAgentAuthDeps): RequestHandler {/*** Annotated as `express.Request` (and helpers below take the same type)@@ -477,6 +481,7 @@ export function createRemoteAgentAuth({return;}+ const previousRole = userResolution.user.role;const selectedRole = await selectOpenIdRoleForOpenIdSync(payload,userResolution.user,@@ -509,7 +514,17 @@ export function createRemoteAgentAuth({return;}- await updateResolvedUser(userResolution, updateUser);+ const persisted = await updateResolvedUser(userResolution, updateUser);+ if (roleChanged && persisted) {+ await recordIdpRoleChange({+ recordAuditEntry,+ userId: userResolution.user.id,+ previousRole,+ role: selectedRole,+ source: 'remote_agent_oidc',+ tenantId: userResolution.user.tenantId,+ });+ }req.user = userResolution.user;return continueWithAuthenticatedTenantContext(req, res, next);diff --git a/packages/data-schemas/src/methods/auditLog.spec.ts b/packages/data-schemas/src/methods/auditLog.spec.tsindex 9ae3262696..da7b52312e 100644--- a/packages/data-schemas/src/methods/auditLog.spec.ts+++ b/packages/data-schemas/src/methods/auditLog.spec.ts@@ -3,7 +3,9 @@ import { MongoMemoryServer } from 'mongodb-memory-server';import type { RecordAuditEntryInput } from '~/types';import type * as t from '~/types';import auditLogSchema, { GENESIS_HASH, PLATFORM_CHAIN_KEY } from '~/schema/auditLog';+import { AUDIT_ACTIONS, AUDIT_ACTION_CATEGORY } from '~/types/admin';import { auditChainKey, createAuditLogMethods } from './auditLog';+import logger from '~/config/winston';jest.mock('~/config/winston', () => ({error: jest.fn(),@@ -79,6 +81,17 @@ describe('auditLog methods', () => {expect(persisted?.createdAt).toBeInstanceOf(Date);});+ it('accepts every registered action and derives its category', async () => {+ for (const action of AUDIT_ACTIONS) {+ await methods.recordAuditEntry(baseInput({ action }), { failClosed: true });+ }+ const persisted = await AuditLog.find({ chainKey: CK_A }).sort({ seq: 1 }).lean();+ expect(persisted.map((entry) => entry.action)).toEqual([...AUDIT_ACTIONS]);+ for (const entry of persisted) {+ expect(entry.category).toBe(AUDIT_ACTION_CATEGORY[entry.action]);+ }+ });+it('derives a warning severity for non-success outcomes', async () => {await methods.recordAuditEntry(baseInput({ outcome: 'denied' }));const persisted = await AuditLog.findOne({ chainKey: CK_A }).lean();@@ -155,6 +168,23 @@ describe('auditLog methods', () => {});});+ describe('write failure logging', () => {+ it('logs the error name and code, never the message', async () => {+ const create = jest+ .spyOn(AuditLog, 'create')+ .mockRejectedValueOnce(new Error('connect mongodb://user:secret@host failed'));+ const logSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);++ await methods.recordAuditEntry(baseInput());++ const logged = JSON.stringify(logSpy.mock.calls);+ expect(logged).toContain('errName');+ expect(logged).not.toContain('secret');+ create.mockRestore();+ logSpy.mockRestore();+ });+ });+describe('append-only enforcement', () => {it('rejects every query-level update and delete path', async () => {await methods.recordAuditEntry(baseInput());diff --git a/packages/data-schemas/src/methods/auditLog.ts b/packages/data-schemas/src/methods/auditLog.tsindex d645b9c574..dc8077dbdf 100644--- a/packages/data-schemas/src/methods/auditLog.ts+++ b/packages/data-schemas/src/methods/auditLog.ts@@ -427,7 +427,9 @@ export function createAuditLogMethods(actorType: actor.type,targetType: target.type,targetId: target.id ?? null,- err,+ /** Name and driver code only: the message can echo query text or connection details. */+ errName: err instanceof Error ? err.name : typeof err,+ errCode: (err as { code?: unknown } | null)?.code ?? null,});if (options?.failClosed) {throw err instanceof Error ? err : new Error('Failed to record audit entry');diff --git a/packages/data-schemas/src/methods/config.spec.ts b/packages/data-schemas/src/methods/config.spec.tsindex f22684fa67..d0eba53048 100644--- a/packages/data-schemas/src/methods/config.spec.ts+++ b/packages/data-schemas/src/methods/config.spec.ts@@ -27,6 +27,34 @@ beforeEach(async () => {await mongoose.models.Config.deleteMany({});});+describe('restoreConfig', () => {+ it('restores tombstones and the inactive flag, and never overwrites a newer document', async () => {+ await methods.upsertConfig(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, {}, 10);+ await methods.tombstoneConfigField(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, 'a.b', 10);+ await methods.toggleConfigActive(PrincipalType.ROLE, 'admin', false);+ const deleted = await methods.deleteConfig(PrincipalType.ROLE, 'admin');+ const snapshot = deleted!.toObject() as Record<string, unknown>;++ expect(await methods.restoreConfig(snapshot)).toBe(true);+ const restored = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'admin', {+ includeInactive: true,+ });+ expect(restored!.isActive).toBe(false);+ expect(restored!.tombstones).toContain('a.b');++ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'admin',+ PrincipalModel.ROLE,+ { interface: { modelSelect: false } },+ 99,+ );+ expect(await methods.restoreConfig(snapshot)).toBe(false);+ const kept = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'admin');+ expect(kept!.priority).toBe(99);+ });+});+describe('upsertConfig tombstone preservation', () => {it('creates a new config document', async () => {const result = await methods.upsertConfig(@@ -646,3 +674,17 @@ describe('expectEmpty atomic guard', () => {expect(Object.keys(doc!.overrides ?? {}).length).toBeGreaterThan(0);});});++describe('toggleConfigActiveTracked', () => {+ it('reports a change once and returns the persisted document', async () => {+ await methods.upsertConfig(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, {}, 10);++ const first = await methods.toggleConfigActiveTracked(PrincipalType.ROLE, 'admin', false);+ const second = await methods.toggleConfigActiveTracked(PrincipalType.ROLE, 'admin', false);+ const missing = await methods.toggleConfigActiveTracked(PrincipalType.ROLE, 'none', false);++ expect(first).toMatchObject({ changed: true, config: { isActive: false } });+ expect(second).toMatchObject({ changed: false, config: { isActive: false } });+ expect(missing).toBeNull();+ });+});diff --git a/packages/data-schemas/src/methods/config.ts b/packages/data-schemas/src/methods/config.tsindex d3051506ab..fe8fc157fd 100644--- a/packages/data-schemas/src/methods/config.ts+++ b/packages/data-schemas/src/methods/config.ts@@ -68,6 +68,7 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {session?: ClientSession,options?: { expectEmpty?: boolean },) => Promise<IConfig | null>;+ restoreConfig: (snapshot: Record<string, unknown>) => Promise<boolean>;toggleConfigActive: (principalType: PrincipalType,principalId: string | Types.ObjectId,@@ -75,6 +76,13 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {session?: ClientSession,options?: { expectEmpty?: boolean },) => Promise<IConfig | null>;+ /** Like `toggleConfigActive`, but also reports whether this write changed `isActive`. */+ toggleConfigActiveTracked: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ isActive: boolean,+ options?: { expectEmpty?: boolean },+ ) => Promise<{ config: IConfig; changed: boolean } | null>;} {async function findConfigByPrincipal(principalType: PrincipalType,@@ -320,17 +328,16 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {return await Config.findOneAndDelete(filter).session(session ?? null);}- async function toggleConfigActive(+ function toggleFilter(principalType: PrincipalType,principalId: string | Types.ObjectId,- isActive: boolean,- session?: ClientSession,options?: { expectEmpty?: boolean },- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;+ extra: FilterQuery<IConfig> = {},+ ): FilterQuery<IConfig> {const filter: FilterQuery<IConfig> = {principalType,principalId: principalId.toString(),+ ...extra,};if (options?.expectEmpty) {filter.$and = [@@ -338,13 +345,60 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {{ $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },];}+ return filter;+ }++ async function toggleConfigActive(+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ isActive: boolean,+ session?: ClientSession,+ options?: { expectEmpty?: boolean },+ ): Promise<IConfig | null> {+ const Config = mongoose.models.Config as Model<IConfig>;return await Config.findOneAndUpdate(- filter,+ toggleFilter(principalType, principalId, options),{ $set: { isActive } },{ new: true, ...(session ? { session } : {}) },);}+ async function toggleConfigActiveTracked(+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ isActive: boolean,+ options?: { expectEmpty?: boolean },+ ): Promise<{ config: IConfig; changed: boolean } | null> {+ const Config = mongoose.models.Config as Model<IConfig>;+ /** The filter matches only a document that differs, so a match is exactly one real change. */+ const changed = await Config.findOneAndUpdate(+ toggleFilter(principalType, principalId, options, { isActive: { $ne: isActive } }),+ { $set: { isActive } },+ { new: true },+ );+ if (changed) {+ return { config: changed, changed: true };+ }+ const current = await Config.findOne(toggleFilter(principalType, principalId, options));+ return current ? { config: current, changed: false } : null;+ }++ /**+ * Re-creates a deleted config document exactly as it was (tombstones, active flag,+ * version), only when no document exists for the principal. Returns whether it+ * inserted, so a document written after the snapshot is never overwritten.+ */+ async function restoreConfig(snapshot: Record<string, unknown>): Promise<boolean> {+ const Config = mongoose.models.Config as Model<IConfig>;+ const { principalType, principalId } = snapshot;+ const result = await Config.updateOne(+ { principalType, principalId },+ { $setOnInsert: snapshot },+ { upsert: true, timestamps: false },+ );+ return result.upsertedCount > 0;+ }+return {listAllConfigs,findConfigByPrincipal,@@ -354,7 +408,9 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {tombstoneConfigField,unsetConfigField,deleteConfig,+ restoreConfig,toggleConfigActive,+ toggleConfigActiveTracked,};}diff --git a/packages/data-schemas/src/methods/role.methods.spec.ts b/packages/data-schemas/src/methods/role.methods.spec.tsindex d02d30cf78..6efa0bdcce 100644--- a/packages/data-schemas/src/methods/role.methods.spec.ts+++ b/packages/data-schemas/src/methods/role.methods.spec.ts@@ -885,6 +885,29 @@ describe('deleteRoleByName', () => {expect(carol!.role).toBe(SystemRoles.USER);});+ it('leaves a role recreated under the same name when the expected id no longer matches', async () => {+ const original = await createRoleByName({ name: 'editor' });+ await Role.deleteOne({ name: 'editor' });+ await createRoleByName({ name: 'editor' });+ await User.create({ name: 'Dana', email: '[email protected]', role: 'editor', username: 'dana' });++ const result = await deleteRoleByName('editor', { id: String(original._id) });++ expect(result).toBeNull();+ expect(await Role.exists({ name: 'editor' })).toBeTruthy();+ const dana = await User.findOne({ email: '[email protected]' }).lean();+ expect(dana!.role).toBe('editor');+ });++ it('deletes the role when the expected id matches', async () => {+ const created = await createRoleByName({ name: 'editor' });++ const result = await deleteRoleByName('editor', { id: String(created._id) });++ expect(result?.name).toBe('editor');+ expect(await Role.exists({ name: 'editor' })).toBeNull();+ });+it('returns null when role does not exist', async () => {const result = await deleteRoleByName('nonexistent');expect(result).toBeNull();diff --git a/packages/data-schemas/src/methods/role.ts b/packages/data-schemas/src/methods/role.tsindex 3b42e82306..dd12c1b813 100644--- a/packages/data-schemas/src/methods/role.ts+++ b/packages/data-schemas/src/methods/role.ts@@ -58,7 +58,7 @@ export function createRoleMethods() => Promise<void>;migrateRoleSchema: (roleName?: string) => Promise<number>;createRoleByName: (roleData: Partial<IRole>) => Promise<IRole>;- deleteRoleByName: (roleName: string) => Promise<IRole | null>;+ deleteRoleByName: (roleName: string, options?: { id?: string }) => Promise<IRole | null>;updateUsersByRole: (oldRole: string, newRole: string) => Promise<void>;findUserIdsByRole: (roleName: string) => Promise<string[]>;updateUsersRoleByIds: (userIds: string[], newRole: string) => Promise<void>;@@ -569,16 +569,26 @@ export function createRoleMethods(* the delete call, which will succeed since the `updateMany` is a no-op on* the second pass.*/- async function deleteRoleByName(roleName: string): Promise<IRole | null> {+ async function deleteRoleByName(+ roleName: string,+ options?: { id?: string },+ ): Promise<IRole | null> {if (isSystemRoleName(roleName)) {throw new Error(`Cannot delete system role: ${roleName}`);}const Role = mongoose.models.Role;+ /** A role recreated under this name has another `_id`: leave it and its members alone. */+ if (options?.id && !(await Role.exists({ _id: options.id, name: roleName }))) {+ return null;+ }const User = mongoose.models.User as Model<IUser>;const affectedUserIds = await findUserIdsByRole(roleName);await User.updateMany({ role: roleName }, { $set: { role: SystemRoles.USER } });await invalidateAuthUserDocCache(affectedUserIds);- const deleted = await Role.findOneAndDelete({ name: roleName }).lean();+ const deleted = await Role.findOneAndDelete({+ name: roleName,+ ...(options?.id ? { _id: options.id } : {}),+ }).lean();try {const cache = deps.getCache?.(CacheKeys.ROLES);if (cache) {diff --git a/packages/data-schemas/src/methods/systemGrant.spec.ts b/packages/data-schemas/src/methods/systemGrant.spec.tsindex c76c4bf373..867805097b 100644--- a/packages/data-schemas/src/methods/systemGrant.spec.ts+++ b/packages/data-schemas/src/methods/systemGrant.spec.ts@@ -776,6 +776,20 @@ describe('systemGrant methods', () => {});});+ describe('findGrantsForPrincipal', () => {+ it('reads the grants deleteGrantsForPrincipal would remove, without removing them', async () => {+ await methods.grantCapability({+ principalType: PrincipalType.ROLE,+ principalId: 'find-role',+ capability: SystemCapabilities.READ_USERS,+ });++ const found = await methods.findGrantsForPrincipal(PrincipalType.ROLE, 'find-role');+ expect(found.map((g) => g.capability)).toEqual([SystemCapabilities.READ_USERS]);+ expect(await methods.findGrantsForPrincipal(PrincipalType.ROLE, 'find-role')).toHaveLength(1);+ });+ });+describe('deleteGrantsForPrincipal', () => {it('deletes all grants for a principal', async () => {const groupId = new Types.ObjectId();diff --git a/packages/data-schemas/src/methods/systemGrant.ts b/packages/data-schemas/src/methods/systemGrant.tsindex c030b6ed51..e49d166d61 100644--- a/packages/data-schemas/src/methods/systemGrant.ts+++ b/packages/data-schemas/src/methods/systemGrant.ts@@ -139,6 +139,11 @@ export function createSystemGrantMethods(mongoose: typeof import('mongoose')): {principalId: string | Types.ObjectId,options?: { tenantId?: string; session?: ClientSession },) => Promise<ISystemGrant[]>;+ findGrantsForPrincipal: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ options?: { tenantId?: string },+ ) => Promise<ISystemGrant[]>;} {function tenantCondition(tenantId?: string): FilterQuery<ISystemGrant> {return tenantId != null@@ -590,6 +595,20 @@ export function createSystemGrantMethods(mongoose: typeof import('mongoose')): {return removed;}+ /** Reads the grants {@link deleteGrantsForPrincipal} would remove, without removing them. */+ async function findGrantsForPrincipal(+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ options?: { tenantId?: string },+ ): Promise<ISystemGrant[]> {+ const SystemGrant = mongoose.models.SystemGrant as Model<ISystemGrant>;+ return SystemGrant.find({+ principalType,+ principalId: normalizePrincipalId(principalId, principalType),+ ...(options?.tenantId != null && { tenantId: options.tenantId }),+ }).lean<ISystemGrant[]>();+ }+return {grantCapability,seedSystemGrants,@@ -602,6 +621,7 @@ export function createSystemGrantMethods(mongoose: typeof import('mongoose')): {getCapabilitiesForPrincipal,getCapabilitiesForPrincipals,deleteGrantsForPrincipal,+ findGrantsForPrincipal,};}diff --git a/packages/data-schemas/src/methods/userGroup.methods.spec.ts b/packages/data-schemas/src/methods/userGroup.methods.spec.tsindex abb3a1f948..81e778b14a 100644--- a/packages/data-schemas/src/methods/userGroup.methods.spec.ts+++ b/packages/data-schemas/src/methods/userGroup.methods.spec.ts@@ -412,6 +412,44 @@ describe('UserGroup Methods - Detailed Tests', () => {expect(result.group?.memberIds).toContain((user._id as mongoose.Types.ObjectId).toString());});+ test('reports a change only for the call that altered membership', async () => {+ const groupId = group._id as mongoose.Types.ObjectId;+ const userId = user._id as mongoose.Types.ObjectId;++ const [first, second] = await Promise.all([+ methods.addUserToGroup(userId, groupId),+ methods.addUserToGroup(userId, groupId),+ ]);+ expect([first.changed, second.changed].filter(Boolean)).toHaveLength(1);+ expect(first.group?.memberIds).toHaveLength(1);++ const removed = await methods.removeUserFromGroup(userId, groupId);+ expect(removed.changed).toBe(true);+ const again = await methods.removeUserFromGroup(userId, groupId);+ expect(again.changed).toBe(false);+ expect(again.group).toBeDefined();+ });++ test('reports a field change only for the call that altered it', async () => {+ const groupId = group._id as mongoose.Types.ObjectId;++ const [first, second] = await Promise.all([+ methods.updateGroupFieldsTracked(groupId, { name: 'Renamed' }),+ methods.updateGroupFieldsTracked(groupId, { name: 'Renamed' }),+ ]);++ expect([first?.changed, second?.changed].filter(Boolean)).toHaveLength(1);+ expect(first?.group.name).toBe('Renamed');+ expect(await methods.updateGroupFieldsTracked(groupId, { name: 'Renamed' })).toMatchObject({+ changed: false,+ });+ const mixed = await methods.updateGroupFieldsTracked(groupId, {+ name: 'Renamed',+ description: 'new description',+ });+ expect(mixed).toMatchObject({ changed: true, changedFields: ['description'] });+ });+test('should remove user from group', async () => {// First add userawait methods.addUserToGroup(@@ -708,6 +746,24 @@ describe('UserGroup Methods - Detailed Tests', () => {});});+ describe('removeMemberByIdTracked', () => {+ test('reports whether the member was actually removed', async () => {+ const group = await Group.create({ name: 'Test', source: 'local', memberIds: ['m1', 'm2'] });+ const groupId = group._id as mongoose.Types.ObjectId;++ const removed = await methods.removeMemberByIdTracked(groupId, 'm1');+ expect(removed.changed).toBe(true);+ expect(removed.group?.memberIds).toEqual(['m2']);++ const absent = await methods.removeMemberByIdTracked(groupId, 'm1');+ expect(absent.changed).toBe(false);+ expect(absent.group?.memberIds).toEqual(['m2']);++ const missing = await methods.removeMemberByIdTracked(new mongoose.Types.ObjectId(), 'm1');+ expect(missing).toEqual({ group: null, changed: false });+ });+ });+describe('removeMemberById', () => {test('removes member from memberIds array', async () => {const group = await Group.create({diff --git a/packages/data-schemas/src/methods/userGroup.ts b/packages/data-schemas/src/methods/userGroup.tsindex 8d6d225eda..2e3bc9827f 100644--- a/packages/data-schemas/src/methods/userGroup.ts+++ b/packages/data-schemas/src/methods/userGroup.ts@@ -206,17 +206,22 @@ export function createUserGroupMethods(userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ) => Promise<{ user: IUser; group: IGroup | null }>;+ ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>;removeUserFromGroup: (userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ) => Promise<{ user: IUser; group: IGroup | null }>;+ ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>;removeUserFromAllGroups: (userId: string | Types.ObjectId) => Promise<void>;findGroupByQuery: (filter: Record<string, unknown>,session?: ClientSession,) => Promise<IGroup | null>;+ /** Sets scalar fields and reports atomically whether any value actually changed. */+ updateGroupFieldsTracked: (+ groupId: string | Types.ObjectId,+ data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,+ ) => Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null>;updateGroupById: (groupId: string | Types.ObjectId,data: Record<string, unknown>,@@ -279,6 +284,11 @@ export function createUserGroupMethods(memberId: string,session?: ClientSession,) => Promise<IGroup | null>;+ removeMemberByIdTracked: (+ groupId: string | Types.ObjectId,+ memberId: string,+ session?: ClientSession,+ ) => Promise<{ group: IGroup | null; changed: boolean }>;} {const getPrincipalsCache = (): CacheStore | undefined =>deps.getCache?.(CacheKeys.USER_PRINCIPALS);@@ -742,7 +752,7 @@ export function createUserGroupMethods(userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ): Promise<{ user: IUser; group: IGroup | null }> {+ ): Promise<{ user: IUser; group: IGroup | null; changed: boolean }> {const User = mongoose.models.User as Model<IUser>;const Group = mongoose.models.Group as Model<IGroup>;@@ -757,14 +767,19 @@ export function createUserGroupMethods(}const userIdOnTheSource = user.idOnTheSource || userId.toString();- const updatedGroup = await Group.findByIdAndUpdate(- groupId,+ /** The filter makes the update match only when the member is absent, so a match+ * is exactly one real change even when identical requests overlap. */+ const changedGroup = await Group.findOneAndUpdate(+ { _id: groupId, memberIds: { $ne: userIdOnTheSource } },{ $addToSet: { memberIds: userIdOnTheSource } },options,).lean<IGroup>();+ const updatedGroup =+ changedGroup ??+ (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());await runAfterTransaction(session, () => invalidateMemberGroupsCache([userIdOnTheSource]));- return { user: user as IUser, group: updatedGroup };+ return { user: user as IUser, group: updatedGroup, changed: changedGroup != null };}/**@@ -781,7 +796,7 @@ export function createUserGroupMethods(userId: string | Types.ObjectId,groupId: string | Types.ObjectId,session?: ClientSession,- ): Promise<{ user: IUser; group: IGroup | null }> {+ ): Promise<{ user: IUser; group: IGroup | null; changed: boolean }> {const User = mongoose.models.User as Model<IUser>;const Group = mongoose.models.Group as Model<IGroup>;@@ -796,14 +811,17 @@ export function createUserGroupMethods(}const userIdOnTheSource = user.idOnTheSource || userId.toString();- const updatedGroup = await Group.findByIdAndUpdate(- groupId,+ const changedGroup = await Group.findOneAndUpdate(+ { _id: groupId, memberIds: userIdOnTheSource },{ $pullAll: { memberIds: [userIdOnTheSource] } },options,).lean<IGroup>();+ const updatedGroup =+ changedGroup ??+ (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());await runAfterTransaction(session, () => invalidateMemberGroupsCache([userIdOnTheSource]));- return { user: user as IUser, group: updatedGroup };+ return { user: user as IUser, group: updatedGroup, changed: changedGroup != null };}/**@@ -1246,6 +1264,36 @@ export function createUserGroupMethods(* @param groupId - The group's ObjectId* @param data - Fields to set via $set*/+ async function updateGroupFieldsTracked(+ groupId: string | Types.ObjectId,+ data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,+ ): Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null> {+ const Group = mongoose.models.Group as Model<IGroup>;+ const entries = Object.entries(data);+ const unchanged = async () => {+ const current = await Group.findById(groupId).lean<IGroup>();+ return current ? { group: current, changed: false, changedFields: [] as string[] } : null;+ };+ if (entries.length === 0) {+ return unchanged();+ }+ /** The filter matches only a group that differs, and the pre-image names exactly the fields+ * this write changed, so overlapping identical requests record one change. */+ const previous = await Group.findOneAndUpdate(+ { _id: groupId, $or: entries.map(([key, value]) => ({ [key]: { $ne: value } })) },+ { $set: data },+ { new: false },+ ).lean<IGroup>();+ if (!previous) {+ return unchanged();+ }+ const changedFields = entries+ .filter(([key, value]) => (previous as unknown as Record<string, unknown>)[key] !== value)+ .map(([key]) => key);+ const group = (await Group.findById(groupId).lean<IGroup>()) ?? previous;+ return { group, changed: true, changedFields };+ }+async function updateGroupById(groupId: string | Types.ObjectId,data: Record<string, unknown>,@@ -1381,20 +1429,31 @@ export function createUserGroupMethods(* @param memberId - The raw memberId string to remove (ObjectId or idOnTheSource)* @param session - Optional MongoDB session for transactions*/- async function removeMemberById(+ async function removeMemberByIdTracked(groupId: string | Types.ObjectId,memberId: string,session?: ClientSession,- ): Promise<IGroup | null> {+ ): Promise<{ group: IGroup | null; changed: boolean }> {const Group = mongoose.models.Group as Model<IGroup>;const options = { new: true, ...(session ? { session } : {}) };- const group = await Group.findByIdAndUpdate(- groupId,+ const changedGroup = await Group.findOneAndUpdate(+ { _id: groupId, memberIds: memberId },{ $pull: { memberIds: memberId } },options,).lean<IGroup>();+ const group =+ changedGroup ??+ (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());await runAfterTransaction(session, () => invalidateMemberGroupsCache([memberId]));- return group;+ return { group, changed: changedGroup != null };+ }++ async function removeMemberById(+ groupId: string | Types.ObjectId,+ memberId: string,+ session?: ClientSession,+ ): Promise<IGroup | null> {+ return (await removeMemberByIdTracked(groupId, memberId, session)).group;}return {@@ -1410,6 +1469,7 @@ export function createUserGroupMethods(removeUserFromAllGroups,findGroupByQuery,updateGroupById,+ updateGroupFieldsTracked,bulkUpdateGroups,getUserGroups,getUserPrincipals,@@ -1421,6 +1481,7 @@ export function createUserGroupMethods(countGroups,deleteGroup,removeMemberById,+ removeMemberByIdTracked,};}diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.tsindex 665a1623e1..c0a3011436 100644--- a/packages/data-schemas/src/types/admin.ts+++ b/packages/data-schemas/src/types/admin.ts@@ -56,20 +56,72 @@ export const AUDIT_CATEGORIES = ['permission','auth','approval',+ 'role',+ 'group',+ 'user',+ 'acl',+ 'credential',+ 'audit',] as const;export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];/*** Single source of truth for the audit-action enum. Actions are namespaced- * `<category>.<verb>` so the registry stays readable as it grows and every- * action maps unambiguously to a category. The Mongoose schema enum and the- * HTTP handler's whitelist both consume this constant so they cannot drift.+ * `<resource>.<verb>` (past tense) so the registry stays readable as it grows;+ * `AUDIT_ACTION_CATEGORY` maps each one to the coarse category used for SIEM+ * routing and filtering. The Mongoose schema enum and the HTTP handler's+ * whitelist both consume this constant so they cannot drift. Actions are only+ * ever appended: stored entries keep their action forever.+ *+ * Actor conventions: admin API mutations record `{ type: 'user' }` with the+ * caller; IdP-driven and startup syncs record `{ type: 'system' }`.*/export const AUDIT_ACTIONS = ['grant.assigned','grant.removed','permission.insights_assigned','permission.insights_removed',+ /** Role lifecycle and membership; target `{ type: 'role', id: name, name }`. */+ 'role.created',+ 'role.updated',+ 'role.permissions_updated',+ 'role.deleted',+ 'role.member_added',+ 'role.member_removed',+ /** Role permissions rewritten by the startup `librechat.yaml` interface sync. */+ 'role.synced',+ /** Group lifecycle and membership; target `{ type: 'group', id, name }`. */+ 'group.created',+ 'group.updated',+ 'group.deleted',+ 'group.member_added',+ 'group.member_removed',+ /** Per-principal config overrides; target `{ type: 'config', id: '<principalType>:<principalId>' }`. */+ 'config.created',+ 'config.updated',+ 'config.deleted',+ 'config.toggled',+ /** Account lifecycle; `role_changed` covers IdP-driven role assignment. */+ 'user.deleted',+ 'user.role_changed',+ /** Resource ACL (sharing) changes. */+ 'acl.granted',+ 'acl.revoked',+ 'acl.public_changed',+ 'mcp_server.created',+ 'mcp_server.updated',+ 'mcp_server.deleted',+ 'code_worker.paired',+ 'code_worker.revoked',+ 'langfuse.updated',+ 'skill_credential.set',+ 'skill_credential.deleted',+ 'passkey.registered',+ 'passkey.removed',+ /** Reads of the audit log itself and retention purges. */+ 'audit.read',+ 'audit.exported',+ 'audit.purged',] as const;export type AuditAction = (typeof AUDIT_ACTIONS)[number];@@ -79,6 +131,40 @@ export const AUDIT_ACTION_CATEGORY: Record<AuditAction, AuditCategory> = {'grant.removed': 'grant','permission.insights_assigned': 'permission','permission.insights_removed': 'permission',+ 'role.created': 'role',+ 'role.updated': 'role',+ 'role.permissions_updated': 'role',+ 'role.deleted': 'role',+ 'role.member_added': 'role',+ 'role.member_removed': 'role',+ 'role.synced': 'role',+ 'group.created': 'group',+ 'group.updated': 'group',+ 'group.deleted': 'group',+ 'group.member_added': 'group',+ 'group.member_removed': 'group',+ 'config.created': 'config',+ 'config.updated': 'config',+ 'config.deleted': 'config',+ 'config.toggled': 'config',+ 'user.deleted': 'user',+ 'user.role_changed': 'user',+ 'acl.granted': 'acl',+ 'acl.revoked': 'acl',+ 'acl.public_changed': 'acl',+ 'mcp_server.created': 'mcp',+ 'mcp_server.updated': 'mcp',+ 'mcp_server.deleted': 'mcp',+ 'code_worker.paired': 'credential',+ 'code_worker.revoked': 'credential',+ 'langfuse.updated': 'config',+ 'skill_credential.set': 'credential',+ 'skill_credential.deleted': 'credential',+ 'passkey.registered': 'auth',+ 'passkey.removed': 'auth',+ 'audit.read': 'audit',+ 'audit.exported': 'audit',+ 'audit.purged': 'audit',};/** Result of the audited operation. Kept first-class instead of being encoded