Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

📜 feat: Audit Admin Role, Group, Config and IdP Role Mutations (#17052)

Marco Berettaccae5b988def
diff --git a/api/server/experimental.js b/api/server/experimental.js
index 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 the
diff --git a/api/server/index.js b/api/server/index.js
index 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 the
diff --git a/api/server/routes/__tests__/roles.spec.js b/api/server/routes/__tests__/roles.spec.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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/:roleName
diff --git a/api/strategies/openidStrategy.js b/api/strategies/openidStrategy.js
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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',
@@ -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.ts
index 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.ts
index 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.ts
index 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 one
deleteGrantsForPrincipal: 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.ts
index 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.ts
index 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 collect
tombstoneConfigField: 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.ts
index 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.ts
index 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 updating
if (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.ts
index 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.ts
index 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.ts
index 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['findU
function 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 user
await 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.ts
index 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.ts
index 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