Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { Types } from 'mongoose';
import { PrincipalType, SystemRoles, promptPermissionsSchema } from 'librechat-data-provider';
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, 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'),
logger: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
}));
const validUserId = new Types.ObjectId().toString();
function mockRole(overrides: Partial<IRole> = {}): IRole {
return {
name: 'editor',
description: 'Can edit content',
permissions: {},
...overrides,
} as IRole;
}
function mockUser(overrides: Partial<IUser> = {}): IUser {
return {
_id: new Types.ObjectId(validUserId),
name: 'Test User',
email: '[email protected]',
avatar: 'https://example.com/avatar.png',
role: 'editor',
...overrides,
} as IUser;
}
function createReqRes(
overrides: {
params?: Record<string, string>;
query?: Record<string, string>;
body?: Record<string, unknown>;
user?: { _id: Types.ObjectId; role: string; tenantId?: string };
} = {},
) {
const req = {
params: overrides.params ?? {},
query: overrides.query ?? {},
body: overrides.body ?? {},
user: overrides.user,
} as unknown as ServerRequest;
const json = jest.fn();
const status = jest.fn().mockReturnValue({ json });
const res = { status, json } as unknown as Response;
return { req, res, status, json };
}
function createDeps(overrides: Partial<AdminRolesDeps> = {}): AdminRolesDeps {
return {
listRoles: jest.fn().mockResolvedValue([]),
countRoles: jest.fn().mockResolvedValue(0),
getRoleByName: jest.fn().mockResolvedValue(null),
createRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateAccessPermissions: jest.fn().mockResolvedValue(undefined),
deleteRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(null),
updateUser: jest.fn().mockResolvedValue(mockUser()),
updateUsersByRole: jest.fn().mockResolvedValue(undefined),
findUserIdsByRole: jest.fn().mockResolvedValue(['uid-1', 'uid-2']),
updateUsersRoleByIds: jest.fn().mockResolvedValue(undefined),
listUsersByRole: jest.fn().mockResolvedValue([]),
countUsersByRole: jest.fn().mockResolvedValue(0),
deleteConfig: jest.fn().mockResolvedValue(null),
deleteAclEntries: jest.fn().mockResolvedValue(undefined),
deleteGrantsForPrincipal: jest.fn().mockResolvedValue([]),
...overrides,
};
}
describe('createAdminRolesHandlers', () => {
describe('listRoles', () => {
it('returns paginated roles with 200', async () => {
const roles = [mockRole()];
const deps = createDeps({
listRoles: jest.fn().mockResolvedValue(roles),
countRoles: jest.fn().mockResolvedValue(1),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes();
await handlers.listRoles(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ roles, total: 1, limit: 50, offset: 0 });
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 50, offset: 0 });
});
it('passes custom limit and offset from query', async () => {
const deps = createDeps({
countRoles: jest.fn().mockResolvedValue(100),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
query: { limit: '25', offset: '50' },
});
await handlers.listRoles(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ roles: [], total: 100, limit: 25, offset: 50 });
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 25, offset: 50 });
});
it('clamps limit to 200', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({ query: { limit: '999' } });
await handlers.listRoles(req, res);
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 200, offset: 0 });
});
it('clamps negative offset to 0', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({ query: { offset: '-5' } });
await handlers.listRoles(req, res);
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 50, offset: 0 });
});
it('treats non-numeric limit as default', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({ query: { limit: 'abc' } });
await handlers.listRoles(req, res);
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 50, offset: 0 });
});
it('clamps limit=0 to 1', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({ query: { limit: '0' } });
await handlers.listRoles(req, res);
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 1, offset: 0 });
});
it('truncates float offset to integer', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({ query: { offset: '1.7' } });
await handlers.listRoles(req, res);
expect(deps.listRoles).toHaveBeenCalledWith({ limit: 50, offset: 1 });
});
it('returns 500 on error', async () => {
const deps = createDeps({ listRoles: jest.fn().mockRejectedValue(new Error('db down')) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes();
await handlers.listRoles(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to list roles' });
});
});
describe('getRole', () => {
it('returns role with 200', async () => {
const role = mockRole();
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(role) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ role });
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'nonexistent' } });
await handlers.getRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 500 on error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockRejectedValue(new Error('db down')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to get role' });
});
});
describe('createRole', () => {
it('creates role and returns 201', async () => {
const role = mockRole();
const deps = createDeps({ createRoleByName: jest.fn().mockResolvedValue(role) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'editor', description: 'Can edit' },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(201);
expect(json).toHaveBeenCalledWith({ role });
expect(deps.createRoleByName).toHaveBeenCalledWith({
name: 'editor',
description: 'Can edit',
permissions: {},
});
});
it('passes provided permissions to createRoleByName', async () => {
const perms = { chat: { read: true, write: false } } as unknown as IRole['permissions'];
const role = mockRole({ permissions: perms });
const deps = createDeps({ createRoleByName: jest.fn().mockResolvedValue(role) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'editor', permissions: perms },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(201);
expect(json).toHaveBeenCalledWith({ role });
expect(deps.createRoleByName).toHaveBeenCalledWith({
name: 'editor',
permissions: perms,
});
});
it('returns 400 when name is missing', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: {} });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name is required' });
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when name is whitespace-only', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: ' ' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name is required' });
});
it('returns 400 when name contains control characters', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: 'bad\x00name' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name contains invalid characters' });
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when name is a reserved path segment', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: 'members' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({
error: 'name is a reserved path segment',
code: 'ROLE_NAME_RESERVED',
});
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when name is the base config principal id', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: ' __base__ ' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({
error: 'name is reserved for the base config',
code: 'ROLE_NAME_RESERVED',
});
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when name exceeds max length', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'a'.repeat(501) },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name must not exceed 500 characters' });
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when description exceeds max length', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'editor', description: 'a'.repeat(2001) },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({
error: 'description must not exceed 2000 characters',
});
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 409 when role already exists', async () => {
const deps = createDeps({
createRoleByName: jest
.fn()
.mockRejectedValue(new RoleConflictError('Role "editor" already exists')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: 'editor' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(409);
expect(json).toHaveBeenCalledWith({ error: 'Role "editor" already exists' });
});
it('returns 409 when name is reserved system role', async () => {
const deps = createDeps({
createRoleByName: jest
.fn()
.mockRejectedValue(
new RoleConflictError('Cannot create role with reserved system name: ADMIN'),
),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: 'ADMIN' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(409);
expect(json).toHaveBeenCalledWith({
error: 'Cannot create role with reserved system name: ADMIN',
});
});
it('returns 500 on unexpected error', async () => {
const deps = createDeps({
createRoleByName: jest.fn().mockRejectedValue(new Error('db crash')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ body: { name: 'editor' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to create role' });
});
it('does not classify unrelated errors as 409', async () => {
const deps = createDeps({
createRoleByName: jest
.fn()
.mockRejectedValue(new Error('Disk space reserved for system use')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({ body: { name: 'test' } });
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(500);
});
it('returns 400 when description is not a string', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'editor', description: 123 },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'description must be a string' });
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when permissions is an array', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
body: { name: 'editor', permissions: [1, 2, 3] },
});
await handlers.createRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'permissions must be an object' });
expect(deps.createRoleByName).not.toHaveBeenCalled();
});
});
describe('updateRole', () => {
it('updates role and returns 200', async () => {
const role = mockRole({ name: 'senior-editor' });
const existing = mockRole({ _id: new Types.ObjectId() } as Partial<IRole>);
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(existing).mockResolvedValueOnce(null),
updateRoleByName: jest.fn().mockResolvedValue(role),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: 'senior-editor' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ role });
/** The rename writes the role document it read, not another tenant's of that name. */
expect(deps.updateRoleByName).toHaveBeenCalledWith(
'editor',
{ name: 'senior-editor' },
{ id: String(existing._id) },
);
});
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({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
updateRoleByName: jest.fn().mockResolvedValue(role),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({
params: { name: 'editor' },
body: { name: ' trimmed ' },
});
await handlers.updateRole(req, res);
expect(deps.updateRoleByName).toHaveBeenCalledWith('editor', { name: 'trimmed' }, undefined);
});
it('migrates users before renaming role', async () => {
const role = mockRole({ name: 'new-name' });
const callOrder: string[] = [];
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
findUserIdsByRole: jest.fn().mockImplementation(() => {
callOrder.push('findUserIdsByRole');
return Promise.resolve(['uid-1']);
}),
updateUsersByRole: jest.fn().mockImplementation(() => {
callOrder.push('updateUsersByRole');
return Promise.resolve();
}),
updateRoleByName: jest.fn().mockImplementation(() => {
callOrder.push('updateRoleByName');
return Promise.resolve(role);
}),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(deps.findUserIdsByRole).toHaveBeenCalledWith('editor');
expect(deps.updateUsersByRole).toHaveBeenCalledWith('editor', 'new-name');
expect(callOrder).toEqual(['findUserIdsByRole', 'updateUsersByRole', 'updateRoleByName']);
});
it('does not rename role when user migration fails', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
updateUsersByRole: jest.fn().mockRejectedValue(new Error('migration failed')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(deps.updateRoleByName).not.toHaveBeenCalled();
});
it('does not migrate users when name unchanged', async () => {
const role = mockRole({ description: 'updated' });
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateRoleByName: jest.fn().mockResolvedValue(role),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({
params: { name: 'editor' },
body: { description: 'updated' },
});
await handlers.updateRole(req, res);
expect(deps.updateUsersByRole).not.toHaveBeenCalled();
});
it('renames and updates description in a single request', async () => {
const role = mockRole({ name: 'senior-editor', description: 'Updated desc' });
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
updateRoleByName: jest.fn().mockResolvedValue(role),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: 'senior-editor', description: 'Updated desc' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ role });
expect(deps.updateUsersByRole).toHaveBeenCalledWith('editor', 'senior-editor');
expect(deps.updateRoleByName).toHaveBeenCalledWith(
'editor',
{ name: 'senior-editor', description: 'Updated desc' },
undefined,
);
});
it('returns 403 when renaming a system role', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN },
body: { name: 'custom-admin' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(403);
expect(json).toHaveBeenCalledWith({ error: 'Cannot rename system role' });
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
it('returns 403 when renaming to a system role name', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: SystemRoles.ADMIN },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(403);
expect(json).toHaveBeenCalledWith({ error: 'Cannot use a reserved system role name' });
});
it('returns 409 when target name already exists', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: 'viewer' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(409);
expect(json).toHaveBeenCalledWith({ error: 'Role "viewer" already exists' });
});
it('returns 400 when name is empty string', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: '' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name must be a non-empty string' });
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
it('returns 400 when name is whitespace-only', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: ' ' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name must be a non-empty string' });
});
it('returns 400 when name exceeds max length', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: 'a'.repeat(501) },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'name must not exceed 500 characters' });
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'nonexistent' },
body: { description: 'updated' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 404 when updateRoleByName returns null', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateRoleByName: jest.fn().mockResolvedValue(null),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { description: 'updated' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('rolls back user migration when rename fails', async () => {
const ids = ['uid-1', 'uid-2'];
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
findUserIdsByRole: jest.fn().mockResolvedValue(ids),
updateRoleByName: jest.fn().mockResolvedValue(null),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
expect(deps.updateUsersByRole).toHaveBeenCalledTimes(1);
expect(deps.updateUsersByRole).toHaveBeenCalledWith('editor', 'new-name');
expect(deps.updateUsersRoleByIds).toHaveBeenCalledWith(ids, 'editor', {
fromRole: 'new-name',
});
});
it('rolls back user migration when rename throws', async () => {
const ids = ['uid-1', 'uid-2'];
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
findUserIdsByRole: jest.fn().mockResolvedValue(ids),
updateRoleByName: jest.fn().mockRejectedValue(new Error('db crash')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(deps.updateUsersByRole).toHaveBeenCalledTimes(1);
expect(deps.updateUsersByRole).toHaveBeenCalledWith('editor', 'new-name');
expect(deps.updateUsersRoleByIds).toHaveBeenCalledWith(ids, 'editor', {
fromRole: 'new-name',
});
});
it('logs rollback failure and still returns 500', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
findUserIdsByRole: jest.fn().mockResolvedValue(['uid-1']),
updateUsersRoleByIds: jest.fn().mockRejectedValue(new Error('rollback failed')),
updateRoleByName: jest.fn().mockRejectedValue(new Error('rename failed')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(deps.updateUsersByRole).toHaveBeenCalledTimes(1);
expect(deps.updateUsersRoleByIds).toHaveBeenCalledTimes(1);
});
it('returns 400 when description exceeds max length', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { description: 'a'.repeat(2001) },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({
error: 'description must not exceed 2000 characters',
});
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
it('returns 500 on unexpected error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateRoleByName: jest.fn().mockRejectedValue(new Error('db error')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { description: 'updated' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to update role' });
});
it('does not roll back when error occurs before user migration', async () => {
const deps = createDeps({
getRoleByName: jest
.fn()
.mockResolvedValueOnce(mockRole())
.mockRejectedValueOnce(new Error('db crash')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(deps.updateUsersByRole).not.toHaveBeenCalled();
});
it('does not migrate users when findUserIdsByRole throws', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(mockRole()).mockResolvedValueOnce(null),
findUserIdsByRole: jest.fn().mockRejectedValue(new Error('db crash')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { name: 'new-name' },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(deps.updateUsersByRole).not.toHaveBeenCalled();
expect(deps.updateUsersRoleByIds).not.toHaveBeenCalled();
});
it('returns existing role early when update body has no changes', async () => {
const role = mockRole();
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(role),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: {},
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ role });
expect(deps.updateRoleByName).not.toHaveBeenCalled();
});
it('rejects invalid description before making DB calls', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { description: 123 },
});
await handlers.updateRole(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'description must be a string' });
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
});
describe('updateRolePermissions', () => {
it('updates permissions and returns 200 with updated role', async () => {
const role = mockRole();
const updatedRole = mockRole({
permissions: { chat: { read: true, write: true } } as IRole['permissions'],
});
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValueOnce(role).mockResolvedValueOnce(updatedRole),
});
const handlers = createAdminRolesHandlers(deps);
const perms = { chat: { read: true, write: true } };
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { permissions: perms },
});
await handlers.updateRolePermissions(req, res);
expect(deps.updateAccessPermissions).toHaveBeenCalledWith('editor', perms, role);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ role: updatedRole });
});
it('returns 400 when permissions is missing', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: {},
});
await handlers.updateRolePermissions(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'permissions object is required' });
});
it('returns 400 when permissions is an array', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { permissions: [1, 2, 3] },
});
await handlers.updateRolePermissions(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'permissions object is required' });
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'nonexistent' },
body: { permissions: { chat: { read: true } } },
});
await handlers.updateRolePermissions(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 500 on error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
updateAccessPermissions: jest.fn().mockRejectedValue(new Error('db down')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { permissions: { chat: { read: true } } },
});
await handlers.updateRolePermissions(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to update role permissions' });
});
});
describe('deleteRole', () => {
const deleteDeps = (overrides: Partial<AdminRolesDeps> = {}) =>
createDeps({ getRoleByName: jest.fn().mockResolvedValue(mockRole()), ...overrides });
it('deletes role and returns 200', async () => {
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.any(Object));
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ success: true });
});
it('cleans up grants after successful deletion', async () => {
const deps = deleteDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({ params: { name: 'editor' } });
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(deps.deleteConfig).toHaveBeenCalledWith(PrincipalType.ROLE, 'editor');
expect(deps.deleteAclEntries).toHaveBeenCalledWith({
principalType: PrincipalType.ROLE,
principalId: 'editor',
});
expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.ROLE, 'editor', {
tenantId: undefined,
});
});
it('passes tenantId to grant cleanup', async () => {
const deps = deleteDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
user: { _id: new Types.ObjectId(), role: 'admin', tenantId: 'tenant-1' },
});
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.ROLE, 'editor', {
tenantId: 'tenant-1',
});
});
it('does not clean up when role not found', async () => {
const deps = deleteDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({ params: { name: 'nonexistent' } });
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(deps.deleteConfig).not.toHaveBeenCalled();
expect(deps.deleteAclEntries).not.toHaveBeenCalled();
expect(deps.deleteGrantsForPrincipal).not.toHaveBeenCalled();
expect(deps.deleteRoleByName).not.toHaveBeenCalled();
});
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(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 = deleteDeps({
deleteGrantsForPrincipal: jest.fn().mockResolvedValue([
{ capability: 'manage:users', tenantId: 'tenant-1' },
{ capability: 'read:users', tenantId: 'tenant-1' },
]),
recordAuditEntry,
});
const handlers = createAdminRolesHandlers(deps);
const userId = new Types.ObjectId();
const { req, res, status } = createReqRes({
params: { name: 'editor' },
user: { _id: userId, role: 'admin', tenantId: 'tenant-1' },
});
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(recordAuditEntry).toHaveBeenCalledTimes(5);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'grant.removed',
actor: expect.objectContaining({ type: 'user', id: userId.toString() }),
target: { type: PrincipalType.ROLE, id: 'editor', name: 'editor' },
metadata: { capability: 'manage:users' },
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 = deleteDeps({
// each removed grant names its own scope, whatever the caller's
deleteGrantsForPrincipal: jest
.fn()
.mockResolvedValue([
{ capability: 'read:users' },
{ capability: 'manage:users', tenantId: 'tenant-x' },
]),
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);
// platform grant → platform chain (tenantId undefined)
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({ metadata: { capability: 'read:users' }, tenantId: undefined }),
);
// tenant grant → that tenant's chain, not the caller's (undefined) scope
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({ metadata: { capability: 'manage:users' }, tenantId: 'tenant-x' }),
);
});
it('records each account reassigned by the deletion before the outcome', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
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' },
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('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')),
});
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.deleteRoleByName).not.toHaveBeenCalled();
});
it('returns 403 for system role', async () => {
const deps = deleteDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: SystemRoles.ADMIN } });
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(403);
expect(json).toHaveBeenCalledWith({ error: 'Cannot delete system role' });
expect(deps.deleteRoleByName).not.toHaveBeenCalled();
});
it('returns 404 when role not found', async () => {
const deps = deleteDeps({ deleteRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'nonexistent' } });
await handlers.deleteRole(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 500 on error', async () => {
const deps = deleteDeps({
deleteRoleByName: jest.fn().mockRejectedValue(new Error('db down')),
});
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' });
});
});
describe('getRoleMembers', () => {
it('returns paginated members with 200', async () => {
const user = mockUser();
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
listUsersByRole: jest.fn().mockResolvedValue([user]),
countUsersByRole: jest.fn().mockResolvedValue(1),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRoleMembers(req, res);
expect(deps.listUsersByRole).toHaveBeenCalledWith('editor', { limit: 50, offset: 0 });
expect(deps.countUsersByRole).toHaveBeenCalledWith('editor');
expect(status).toHaveBeenCalledWith(200);
const response = json.mock.calls[0][0];
expect(response.members).toHaveLength(1);
expect(response.members[0]).toEqual({
userId: validUserId,
name: 'Test User',
email: '[email protected]',
avatarUrl: 'https://example.com/avatar.png',
});
expect(response.total).toBe(1);
expect(response.limit).toBe(50);
expect(response.offset).toBe(0);
});
it('passes pagination parameters from query', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
countUsersByRole: jest.fn().mockResolvedValue(0),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({
params: { name: 'editor' },
query: { limit: '10', offset: '20' },
});
await handlers.getRoleMembers(req, res);
expect(deps.listUsersByRole).toHaveBeenCalledWith('editor', { limit: 10, offset: 20 });
});
it('clamps limit to 200', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
countUsersByRole: jest.fn().mockResolvedValue(0),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res } = createReqRes({
params: { name: 'editor' },
query: { limit: '999' },
});
await handlers.getRoleMembers(req, res);
expect(deps.listUsersByRole).toHaveBeenCalledWith('editor', { limit: 200, offset: 0 });
});
it('does not include joinedAt in response', async () => {
const user = mockUser();
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
listUsersByRole: jest.fn().mockResolvedValue([user]),
countUsersByRole: jest.fn().mockResolvedValue(1),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRoleMembers(req, res);
const member = json.mock.calls[0][0].members[0];
expect(member).not.toHaveProperty('joinedAt');
});
it('returns empty array when no members', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
countUsersByRole: jest.fn().mockResolvedValue(0),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRoleMembers(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ members: [], total: 0, limit: 50, offset: 0 });
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'nonexistent' } });
await handlers.getRoleMembers(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 500 on error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
listUsersByRole: jest.fn().mockRejectedValue(new Error('db down')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
await handlers.getRoleMembers(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to get role members' });
});
});
describe('addRoleMember', () => {
it('adds member and returns 200', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'viewer' })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
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()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'editor' })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ success: true });
expect(deps.updateUser).not.toHaveBeenCalled();
});
it('returns 400 when userId is missing', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: {},
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'userId is required' });
});
it('returns 400 for invalid ObjectId', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: 'not-valid' },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Invalid user ID format' });
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'nonexistent' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
});
it('returns 404 when user not found', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(null),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'User not found' });
});
it('returns 400 when reassigning the last admin to another role', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: 'editor' })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValue(1),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Cannot remove the last admin user' });
expect(deps.updateUser).not.toHaveBeenCalled();
});
it('allows reassigning an admin when multiple admins exist', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: 'editor' })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValue(3),
updateUser: jest.fn().mockResolvedValue(mockUser({ role: 'editor' })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(deps.updateUser).toHaveBeenCalledWith(
validUserId,
{ role: 'editor' },
expect.any(Object),
);
});
it('rolls back assignment when post-write admin count is zero', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: 'editor' })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValueOnce(2).mockResolvedValueOnce(0),
updateUser: jest.fn().mockResolvedValue(mockUser()),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(deps.updateUser).toHaveBeenCalledTimes(2);
expect(deps.updateUser).toHaveBeenLastCalledWith(validUserId, { role: SystemRoles.ADMIN });
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Cannot remove the last admin user' });
});
it('returns 403 when adding to a non-ADMIN system role', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.USER },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(403);
expect(json).toHaveBeenCalledWith({
error: 'Cannot directly assign members to a system role',
});
expect(deps.updateUser).not.toHaveBeenCalled();
});
it('allows promoting a non-admin user to the ADMIN role', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'editor' })),
updateUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(deps.updateUser).toHaveBeenCalledWith(
validUserId,
{ role: SystemRoles.ADMIN },
expect.any(Object),
);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ success: true });
});
it('returns 500 on unexpected error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'viewer' })),
updateUser: jest.fn().mockRejectedValue(new Error('timeout')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor' },
body: { userId: validUserId },
});
await handlers.addRoleMember(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to add role member' });
});
});
describe('removeRoleMember', () => {
it('removes member and returns 200', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'editor' })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor', userId: validUserId },
});
await handlers.removeRoleMember(req, res);
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);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.USER, userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(403);
expect(json).toHaveBeenCalledWith({ error: 'Cannot remove members from a system role' });
expect(deps.getRoleByName).not.toHaveBeenCalled();
});
it('returns 400 for invalid ObjectId', async () => {
const deps = createDeps();
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor', userId: 'bad' },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Invalid user ID format' });
expect(deps.findUser).not.toHaveBeenCalled();
});
it('returns 404 when role not found', async () => {
const deps = createDeps({ getRoleByName: jest.fn().mockResolvedValue(null) });
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'nonexistent', userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'Role not found' });
expect(deps.findUser).not.toHaveBeenCalled();
});
it('returns 404 when user not found', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(null),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor', userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(404);
expect(json).toHaveBeenCalledWith({ error: 'User not found' });
});
it('returns 400 when user is not a member of the role', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'other-role' })),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor', userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'User is not a member of this role' });
expect(deps.updateUser).not.toHaveBeenCalled();
});
it('returns 400 when removing the last admin user', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValue(1),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN, userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Cannot remove the last admin user' });
expect(deps.updateUser).not.toHaveBeenCalled();
});
it('allows removing an admin when multiple admins exist', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValue(3),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN, userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(200);
expect(json).toHaveBeenCalledWith({ success: true });
expect(deps.updateUser).toHaveBeenCalledWith(
validUserId,
{ role: SystemRoles.USER },
expect.any(Object),
);
});
it('rolls back removal when post-write check finds zero admins', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValueOnce(2).mockResolvedValueOnce(0),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN, userId: validUserId },
});
await handlers.removeRoleMember(req, res);
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 },
{ role: SystemRoles.ADMIN },
);
expect(deps.updateUser).toHaveBeenNthCalledWith(2, validUserId, {
role: SystemRoles.ADMIN,
});
});
it('returns 400 even when rollback updateUser throws', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole({ name: SystemRoles.ADMIN })),
findUser: jest.fn().mockResolvedValue(mockUser({ role: SystemRoles.ADMIN })),
countUsersByRole: jest.fn().mockResolvedValueOnce(2).mockResolvedValueOnce(0),
updateUser: jest
.fn()
.mockResolvedValueOnce(mockUser({ role: SystemRoles.USER }))
.mockRejectedValueOnce(new Error('rollback failed')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: SystemRoles.ADMIN, userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(400);
expect(json).toHaveBeenCalledWith({ error: 'Cannot remove the last admin user' });
expect(deps.updateUser).toHaveBeenCalledTimes(2);
});
it('returns 500 on unexpected error', async () => {
const deps = createDeps({
getRoleByName: jest.fn().mockResolvedValue(mockRole()),
findUser: jest.fn().mockResolvedValue(mockUser({ role: 'editor' })),
updateUser: jest.fn().mockRejectedValue(new Error('timeout')),
});
const handlers = createAdminRolesHandlers(deps);
const { req, res, status, json } = createReqRes({
params: { name: 'editor', userId: validUserId },
});
await handlers.removeRoleMember(req, res);
expect(status).toHaveBeenCalledWith(500);
expect(json).toHaveBeenCalledWith({ error: 'Failed to remove role member' });
});
});
});
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,
configMoved: false,
grantsMoved: 0,
grantCapabilities: null,
aclEntriesMoved: 0,
},
}),
);
});
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: promptPermissionsSchema,
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: [expect.objectContaining({ code: 'invalid_type', path: ['USE'] })],
});
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);
});
});