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: Admin Roles API Endpoints (#12400)

Dustin Healy5972a21479e6
diff --git a/api/server/index.js b/api/server/index.js
index 4ecc966476..813b453468 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -145,6 +145,7 @@ const startServer = async () => {
app.use('/api/admin', routes.adminAuth);
app.use('/api/admin/config', routes.adminConfig);
app.use('/api/admin/groups', routes.adminGroups);
+ app.use('/api/admin/roles', routes.adminRoles);
app.use('/api/actions', routes.actions);
app.use('/api/keys', routes.keys);
app.use('/api/api-keys', routes.apiKeys);
diff --git a/api/server/routes/admin/roles.js b/api/server/routes/admin/roles.js
new file mode 100644
index 0000000000..2d0f1b1128
--- /dev/null
+++ b/api/server/routes/admin/roles.js
@@ -0,0 +1,43 @@
+const express = require('express');
+const { createAdminRolesHandlers } = require('@librechat/api');
+const { SystemCapabilities } = require('@librechat/data-schemas');
+const { requireCapability } = require('~/server/middleware/roles/capabilities');
+const { requireJwtAuth } = require('~/server/middleware');
+const db = require('~/models');
+
+const router = express.Router();
+
+const requireAdminAccess = requireCapability(SystemCapabilities.ACCESS_ADMIN);
+const requireReadRoles = requireCapability(SystemCapabilities.READ_ROLES);
+const requireManageRoles = requireCapability(SystemCapabilities.MANAGE_ROLES);
+
+const handlers = createAdminRolesHandlers({
+ listRoles: db.listRoles,
+ countRoles: db.countRoles,
+ getRoleByName: db.getRoleByName,
+ createRoleByName: db.createRoleByName,
+ updateRoleByName: db.updateRoleByName,
+ updateAccessPermissions: db.updateAccessPermissions,
+ deleteRoleByName: db.deleteRoleByName,
+ findUser: db.findUser,
+ updateUser: db.updateUser,
+ updateUsersByRole: db.updateUsersByRole,
+ findUserIdsByRole: db.findUserIdsByRole,
+ updateUsersRoleByIds: db.updateUsersRoleByIds,
+ listUsersByRole: db.listUsersByRole,
+ countUsersByRole: db.countUsersByRole,
+});
+
+router.use(requireJwtAuth, requireAdminAccess);
+
+router.get('/', requireReadRoles, handlers.listRoles);
+router.post('/', requireManageRoles, handlers.createRole);
+router.get('/:name', requireReadRoles, handlers.getRole);
+router.patch('/:name', requireManageRoles, handlers.updateRole);
+router.delete('/:name', requireManageRoles, handlers.deleteRole);
+router.patch('/:name/permissions', requireManageRoles, handlers.updateRolePermissions);
+router.get('/:name/members', requireReadRoles, handlers.getRoleMembers);
+router.post('/:name/members', requireManageRoles, handlers.addRoleMember);
+router.delete('/:name/members/:userId', requireManageRoles, handlers.removeRoleMember);
+
+module.exports = router;
diff --git a/api/server/routes/index.js b/api/server/routes/index.js
index f9a088649c..71ae041fc2 100644
--- a/api/server/routes/index.js
+++ b/api/server/routes/index.js
@@ -4,6 +4,7 @@ const categories = require('./categories');
const adminAuth = require('./admin/auth');
const adminConfig = require('./admin/config');
const adminGroups = require('./admin/groups');
+const adminRoles = require('./admin/roles');
const endpoints = require('./endpoints');
const staticRoute = require('./static');
const messages = require('./messages');
@@ -35,6 +36,7 @@ module.exports = {
adminAuth,
adminConfig,
adminGroups,
+ adminRoles,
keys,
apiKeys,
user,
diff --git a/packages/api/src/admin/groups.ts b/packages/api/src/admin/groups.ts
index 58ff4d9782..ab4490e05f 100644
--- a/packages/api/src/admin/groups.ts
+++ b/packages/api/src/admin/groups.ts
@@ -13,6 +13,7 @@ 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 { parsePagination } from './pagination';
type GroupListFilter = Pick<GroupFilterOptions, 'source' | 'search'>;
@@ -119,8 +120,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps) {
if (search) {
filter.search = search;
}
- const limit = Math.min(Math.max(Number(req.query.limit) || 50, 1), 200);
- const offset = Math.max(Number(req.query.offset) || 0, 0);
+ const { limit, offset } = parsePagination(req.query);
const [groups, total] = await Promise.all([
listGroups({ ...filter, limit, offset }),
countGroups(filter),
@@ -348,8 +348,7 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps) {
*/
const allMemberIds = [...new Set(group.memberIds || [])];
const total = allMemberIds.length;
- const limit = Math.min(Math.max(Number(req.query.limit) || 50, 1), 200);
- const offset = Math.max(Number(req.query.offset) || 0, 0);
+ const { limit, offset } = parsePagination(req.query);
if (total === 0 || offset >= total) {
return res.status(200).json({ members: [], total, limit, offset });
diff --git a/packages/api/src/admin/index.ts b/packages/api/src/admin/index.ts
index d833c7e2b0..fe60f1d993 100644
--- a/packages/api/src/admin/index.ts
+++ b/packages/api/src/admin/index.ts
@@ -1,4 +1,6 @@
export { createAdminConfigHandlers } from './config';
export { createAdminGroupsHandlers } from './groups';
+export { createAdminRolesHandlers } from './roles';
export type { AdminConfigDeps } from './config';
export type { AdminGroupsDeps } from './groups';
+export type { AdminRolesDeps } from './roles';
diff --git a/packages/api/src/admin/pagination.ts b/packages/api/src/admin/pagination.ts
new file mode 100644
index 0000000000..69003f0418
--- /dev/null
+++ b/packages/api/src/admin/pagination.ts
@@ -0,0 +1,17 @@
+export const DEFAULT_PAGE_LIMIT = 50;
+export const MAX_PAGE_LIMIT = 200;
+
+export function parsePagination(query: { limit?: string; offset?: string }): {
+ limit: number;
+ offset: number;
+} {
+ const rawLimit = parseInt(query.limit ?? '', 10);
+ const rawOffset = parseInt(query.offset ?? '', 10);
+ return {
+ limit: Math.min(
+ Math.max(Number.isNaN(rawLimit) ? DEFAULT_PAGE_LIMIT : rawLimit, 1),
+ MAX_PAGE_LIMIT,
+ ),
+ offset: Math.max(Number.isNaN(rawOffset) ? 0 : rawOffset, 0),
+ };
+}
diff --git a/packages/api/src/admin/roles.spec.ts b/packages/api/src/admin/roles.spec.ts
new file mode 100644
index 0000000000..3f43079bfb
--- /dev/null
+++ b/packages/api/src/admin/roles.spec.ts
@@ -0,0 +1,1484 @@
+import { Types } from 'mongoose';
+import { SystemRoles } 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 } from './roles';
+
+const { RoleConflictError } = jest.requireActual('@librechat/data-schemas');
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: { error: 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>;
+ } = {},
+) {
+ const req = {
+ params: overrides.params ?? {},
+ query: overrides.query ?? {},
+ body: overrides.body ?? {},
+ } 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),
+ ...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' });
+ 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 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' },
+ });
+
+ await handlers.updateRole(req, res);
+
+ expect(status).toHaveBeenCalledWith(200);
+ expect(json).toHaveBeenCalledWith({ role });
+ expect(deps.updateRoleByName).toHaveBeenCalledWith('editor', { name: 'senior-editor' });
+ });
+
+ 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' });
+ });
+
+ 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',
+ });
+ });
+
+ 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');
+ });
+
+ 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');
+ });
+
+ 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', () => {
+ it('deletes role and returns 200', async () => {
+ const deps = createDeps();
+ const handlers = createAdminRolesHandlers(deps);
+ const { req, res, status, json } = createReqRes({ params: { name: 'editor' } });
+
+ await handlers.deleteRole(req, res);
+
+ expect(deps.deleteRoleByName).toHaveBeenCalledWith('editor');
+ expect(status).toHaveBeenCalledWith(200);
+ expect(json).toHaveBeenCalledWith({ success: true });
+ });
+
+ it('returns 403 for system role', async () => {
+ const deps = createDeps();
+ 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 = createDeps({ 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 = createDeps({
+ 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(status).toHaveBeenCalledWith(200);
+ expect(json).toHaveBeenCalledWith({ success: true });
+ });
+
+ 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' });
+ });
+
+ 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(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(status).toHaveBeenCalledWith(200);
+ expect(json).toHaveBeenCalledWith({ success: true });
+ });
+
+ 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 });
+ });
+
+ 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,
+ });
+ 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' });
+ });
+ });
+});
diff --git a/packages/api/src/admin/roles.ts b/packages/api/src/admin/roles.ts
new file mode 100644
index 0000000000..b8c87c23ea
--- /dev/null
+++ b/packages/api/src/admin/roles.ts
@@ -0,0 +1,550 @@
+import { SystemRoles } from 'librechat-data-provider';
+import { logger, isValidObjectIdString, RoleConflictError } from '@librechat/data-schemas';
+import type { IRole, IUser, AdminMember } from '@librechat/data-schemas';
+import type { FilterQuery, Types } from 'mongoose';
+import type { Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+import { parsePagination } from './pagination';
+
+const systemRoleValues = new Set<string>(Object.values(SystemRoles));
+
+/** Case-insensitive check — the legacy roles route uppercases params. */
+function isSystemRoleName(name: string): boolean {
+ return systemRoleValues.has(name.toUpperCase());
+}
+
+const MAX_NAME_LENGTH = 500;
+const MAX_DESCRIPTION_LENGTH = 2000;
+const CONTROL_CHAR_RE = /\p{Cc}/u;
+/**
+ * Role names that would create semantically ambiguous URLs.
+ * e.g. GET /api/admin/roles/members — is that "list roles" or "get role named members"?
+ * Express routing resolves this correctly (single vs multi-segment), but the URLs
+ * are confusing for API consumers. Keep in sync with sub-path routes in routes/admin/roles.js.
+ */
+const RESERVED_ROLE_NAMES = new Set(['members', 'permissions']);
+
+function validateNameParam(name: string): string | null {
+ if (!name || typeof name !== 'string') {
+ return 'name parameter is required';
+ }
+ if (name.length > MAX_NAME_LENGTH) {
+ return `name must not exceed ${MAX_NAME_LENGTH} characters`;
+ }
+ if (CONTROL_CHAR_RE.test(name)) {
+ return 'name contains invalid characters';
+ }
+ return null;
+}
+
+function validateRoleName(name: unknown, required: boolean): string | null {
+ if (name === undefined) {
+ return required ? 'name is required' : null;
+ }
+ if (typeof name !== 'string' || !name.trim()) {
+ return required ? 'name is required' : 'name must be a non-empty string';
+ }
+ const trimmed = name.trim();
+ if (trimmed.length > MAX_NAME_LENGTH) {
+ return `name must not exceed ${MAX_NAME_LENGTH} characters`;
+ }
+ if (CONTROL_CHAR_RE.test(trimmed)) {
+ return 'name contains invalid characters';
+ }
+ if (RESERVED_ROLE_NAMES.has(trimmed)) {
+ return 'name is a reserved path segment';
+ }
+ return null;
+}
+
+function validateDescription(description: unknown): string | null {
+ if (description === undefined) {
+ return null;
+ }
+ if (typeof description !== 'string') {
+ return 'description must be a string';
+ }
+ if (description.length > MAX_DESCRIPTION_LENGTH) {
+ return `description must not exceed ${MAX_DESCRIPTION_LENGTH} characters`;
+ }
+ return null;
+}
+
+interface RoleNameParams {
+ name: string;
+}
+
+interface RoleMemberParams extends RoleNameParams {
+ userId: string;
+}
+
+export type RoleListItem = { _id: Types.ObjectId | string; name: string; description?: string };
+
+export interface AdminRolesDeps {
+ listRoles: (options?: { limit?: number; offset?: number }) => Promise<RoleListItem[]>;
+ countRoles: () => Promise<number>;
+ getRoleByName: (name: string, fields?: string | string[] | null) => Promise<IRole | null>;
+ createRoleByName: (roleData: Partial<IRole>) => Promise<IRole>;
+ updateRoleByName: (name: string, updates: Partial<IRole>) => Promise<IRole | null>;
+ updateAccessPermissions: (
+ name: string,
+ perms: Record<string, Record<string, boolean>>,
+ roleData?: IRole,
+ ) => Promise<void>;
+ deleteRoleByName: (name: string) => Promise<IRole | null>;
+ findUser: (
+ criteria: FilterQuery<IUser>,
+ fields?: string | string[] | null,
+ ) => Promise<IUser | null>;
+ updateUser: (userId: string, data: Partial<IUser>) => Promise<IUser | null>;
+ updateUsersByRole: (oldRole: string, newRole: string) => Promise<void>;
+ findUserIdsByRole: (roleName: string) => Promise<string[]>;
+ updateUsersRoleByIds: (userIds: string[], newRole: string) => Promise<void>;
+ listUsersByRole: (
+ roleName: string,
+ options?: { limit?: number; offset?: number },
+ ) => Promise<IUser[]>;
+ countUsersByRole: (roleName: string) => Promise<number>;
+}
+
+export function createAdminRolesHandlers(deps: AdminRolesDeps) {
+ const {
+ listRoles,
+ countRoles,
+ getRoleByName,
+ createRoleByName,
+ updateRoleByName,
+ updateAccessPermissions,
+ deleteRoleByName,
+ findUser,
+ updateUser,
+ updateUsersByRole,
+ findUserIdsByRole,
+ updateUsersRoleByIds,
+ listUsersByRole,
+ countUsersByRole,
+ } = deps;
+
+ async function listRolesHandler(req: ServerRequest, res: Response) {
+ try {
+ const { limit, offset } = parsePagination(req.query);
+ 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);
+ return res.status(500).json({ error: 'Failed to list roles' });
+ }
+ }
+
+ async function getRoleHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ const role = await getRoleByName(name);
+ if (!role) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+ return res.status(200).json({ role });
+ } catch (error) {
+ logger.error('[adminRoles] getRole error:', error);
+ return res.status(500).json({ error: 'Failed to get role' });
+ }
+ }
+
+ async function createRoleHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name, description, permissions } = req.body as {
+ name?: string;
+ description?: string;
+ permissions?: IRole['permissions'];
+ };
+ const nameError = validateRoleName(name, true);
+ if (nameError) {
+ return res.status(400).json({ error: nameError });
+ }
+ const descError = validateDescription(description);
+ if (descError) {
+ return res.status(400).json({ error: descError });
+ }
+ if (
+ permissions !== undefined &&
+ (permissions === null || typeof permissions !== 'object' || Array.isArray(permissions))
+ ) {
+ return res.status(400).json({ error: 'permissions must be an object' });
+ }
+ const roleData: Partial<IRole> = {
+ name: (name as string).trim(),
+ permissions: permissions ?? {},
+ };
+ if (description !== undefined) {
+ roleData.description = description;
+ }
+ const role = await createRoleByName(roleData);
+ return res.status(201).json({ role });
+ } catch (error) {
+ logger.error('[adminRoles] createRole error:', error);
+ if (error instanceof RoleConflictError) {
+ return res.status(409).json({ error: error.message });
+ }
+ return res.status(500).json({ error: 'Failed to create role' });
+ }
+ }
+
+ async function rollbackMigratedUsers(
+ migratedIds: string[],
+ currentName: string,
+ newName: string,
+ ): Promise<void> {
+ if (migratedIds.length === 0) {
+ return;
+ }
+ try {
+ await updateUsersRoleByIds(migratedIds, currentName);
+ } catch (rollbackError) {
+ logger.error(
+ `[adminRoles] CRITICAL: rename rollback failed — ${migratedIds.length} users have dangling role "${newName}": [${migratedIds.join(', ')}]`,
+ rollbackError,
+ );
+ }
+ }
+
+ /**
+ * Renames a role by migrating users to the new name and updating the role document.
+ *
+ * The ID snapshot from `findUserIdsByRole` is a point-in-time read. Users assigned
+ * to `currentName` between the snapshot and the bulk `updateUsersByRole` write will
+ * be moved to `newName` but will NOT be reverted on rollback. This window is narrow
+ * and only relevant under concurrent admin operations during a rename.
+ */
+ async function renameRole(
+ currentName: string,
+ newName: string,
+ extraUpdates?: Partial<IRole>,
+ ): Promise<IRole | null> {
+ const migratedIds = await findUserIdsByRole(currentName);
+ await updateUsersByRole(currentName, newName);
+ try {
+ const updates: Partial<IRole> = { name: newName, ...extraUpdates };
+ const role = await updateRoleByName(currentName, updates);
+ if (!role) {
+ await rollbackMigratedUsers(migratedIds, currentName, newName);
+ }
+ return role;
+ } catch (error) {
+ await rollbackMigratedUsers(migratedIds, currentName, newName);
+ throw error;
+ }
+ }
+
+ async function updateRoleHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ const body = req.body as { name?: string; description?: string };
+ const nameError = validateRoleName(body.name, false);
+ if (nameError) {
+ return res.status(400).json({ error: nameError });
+ }
+ const descError = validateDescription(body.description);
+ if (descError) {
+ return res.status(400).json({ error: descError });
+ }
+
+ const trimmedName = body.name?.trim() ?? '';
+ const isRename = trimmedName !== '' && trimmedName !== name;
+
+ if (isRename && isSystemRoleName(name)) {
+ return res.status(403).json({ error: 'Cannot rename system role' });
+ }
+ if (isRename && isSystemRoleName(trimmedName)) {
+ return res.status(403).json({ error: 'Cannot use a reserved system role name' });
+ }
+
+ const existing = await getRoleByName(name);
+ if (!existing) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+
+ if (isRename) {
+ const duplicate = await getRoleByName(trimmedName);
+ if (duplicate) {
+ return res.status(409).json({ error: `Role "${trimmedName}" already exists` });
+ }
+ }
+
+ const updates: Partial<IRole> = {};
+ if (isRename) {
+ updates.name = trimmedName;
+ }
+ if (body.description !== undefined) {
+ updates.description = body.description;
+ }
+
+ if (Object.keys(updates).length === 0) {
+ return res.status(200).json({ role: existing });
+ }
+
+ if (isRename) {
+ const descUpdate =
+ body.description !== undefined ? { description: body.description } : undefined;
+ const role = await renameRole(name, trimmedName, descUpdate);
+ if (!role) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+ return res.status(200).json({ role });
+ }
+
+ const role = await updateRoleByName(name, updates);
+ if (!role) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+ 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);
+ return res.status(500).json({ error: 'Failed to update role' });
+ }
+ }
+
+ /**
+ * The re-fetch via `getRoleByName` after `updateAccessPermissions` depends on the
+ * callee having written the updated document to the role cache. If the cache layer
+ * is refactored to stop writing from within `updateAccessPermissions`, this handler
+ * must be updated to perform an explicit uncached DB read.
+ */
+ async function updateRolePermissionsHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ const { permissions } = req.body as {
+ permissions: Record<string, Record<string, boolean>>;
+ };
+
+ if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
+ return res.status(400).json({ error: 'permissions object is required' });
+ }
+
+ const existing = await getRoleByName(name);
+ if (!existing) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+
+ await updateAccessPermissions(name, permissions, existing);
+ const updated = await getRoleByName(name);
+ if (!updated) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+ return res.status(200).json({ role: updated });
+ } catch (error) {
+ logger.error('[adminRoles] updateRolePermissions error:', error);
+ return res.status(500).json({ error: 'Failed to update role permissions' });
+ }
+ }
+
+ async function deleteRoleHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ if (isSystemRoleName(name)) {
+ return res.status(403).json({ error: 'Cannot delete system role' });
+ }
+
+ const deleted = await deleteRoleByName(name);
+ if (!deleted) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+ return res.status(200).json({ success: true });
+ } catch (error) {
+ logger.error('[adminRoles] deleteRole error:', error);
+ return res.status(500).json({ error: 'Failed to delete role' });
+ }
+ }
+
+ async function getRoleMembersHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ const existing = await getRoleByName(name);
+ if (!existing) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+
+ const { limit, offset } = parsePagination(req.query);
+
+ const [users, total] = await Promise.all([
+ listUsersByRole(name, { limit, offset }),
+ countUsersByRole(name),
+ ]);
+ const members: AdminMember[] = users.map((u) => ({
+ userId: u._id?.toString() ?? '',
+ name: u.name ?? u._id?.toString() ?? '',
+ email: u.email ?? '',
+ avatarUrl: u.avatar,
+ }));
+ return res.status(200).json({ members, total, limit, offset });
+ } catch (error) {
+ logger.error('[adminRoles] getRoleMembers error:', error);
+ return res.status(500).json({ error: 'Failed to get role members' });
+ }
+ }
+
+ async function addRoleMemberHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name } = req.params as RoleNameParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ const { userId } = req.body as { userId: string };
+
+ if (!userId || typeof userId !== 'string') {
+ return res.status(400).json({ error: 'userId is required' });
+ }
+ if (!isValidObjectIdString(userId)) {
+ return res.status(400).json({ error: 'Invalid user ID format' });
+ }
+
+ if (isSystemRoleName(name) && name !== SystemRoles.ADMIN) {
+ return res.status(403).json({ error: 'Cannot directly assign members to a system role' });
+ }
+
+ const existing = await getRoleByName(name);
+ if (!existing) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+
+ const user = await findUser({ _id: userId });
+ if (!user) {
+ return res.status(404).json({ error: 'User not found' });
+ }
+
+ if (user.role === name) {
+ return res.status(200).json({ success: true });
+ }
+
+ if (user.role === SystemRoles.ADMIN && name !== SystemRoles.ADMIN) {
+ const adminCount = await countUsersByRole(SystemRoles.ADMIN);
+ if (adminCount <= 1) {
+ return res.status(400).json({ error: 'Cannot remove the last admin user' });
+ }
+ }
+
+ const updated = await updateUser(userId, { role: name });
+ if (!updated) {
+ return res.status(404).json({ error: 'User not found' });
+ }
+
+ if (user.role === SystemRoles.ADMIN && name !== SystemRoles.ADMIN) {
+ const postCount = await countUsersByRole(SystemRoles.ADMIN);
+ if (postCount === 0) {
+ try {
+ await updateUser(userId, { role: SystemRoles.ADMIN });
+ } catch (rollbackError) {
+ logger.error(
+ `[adminRoles] CRITICAL: admin rollback failed in addRoleMember for user ${userId}:`,
+ rollbackError,
+ );
+ }
+ return res.status(400).json({ error: 'Cannot remove the last admin user' });
+ }
+ }
+
+ return res.status(200).json({ success: true });
+ } catch (error) {
+ logger.error('[adminRoles] addRoleMember error:', error);
+ return res.status(500).json({ error: 'Failed to add role member' });
+ }
+ }
+
+ async function removeRoleMemberHandler(req: ServerRequest, res: Response) {
+ try {
+ const { name, userId } = req.params as RoleMemberParams;
+ const paramError = validateNameParam(name);
+ if (paramError) {
+ return res.status(400).json({ error: paramError });
+ }
+ if (!isValidObjectIdString(userId)) {
+ return res.status(400).json({ error: 'Invalid user ID format' });
+ }
+
+ if (isSystemRoleName(name) && name !== SystemRoles.ADMIN) {
+ return res.status(403).json({ error: 'Cannot remove members from a system role' });
+ }
+
+ const existing = await getRoleByName(name);
+ if (!existing) {
+ return res.status(404).json({ error: 'Role not found' });
+ }
+
+ const user = await findUser({ _id: userId });
+ if (!user) {
+ return res.status(404).json({ error: 'User not found' });
+ }
+
+ if (user.role !== name) {
+ return res.status(400).json({ error: 'User is not a member of this role' });
+ }
+
+ if (name === SystemRoles.ADMIN) {
+ const adminCount = await countUsersByRole(SystemRoles.ADMIN);
+ if (adminCount <= 1) {
+ return res.status(400).json({ error: 'Cannot remove the last admin user' });
+ }
+ }
+
+ const removed = await updateUser(userId, { role: SystemRoles.USER });
+ if (!removed) {
+ return res.status(404).json({ error: 'User not found' });
+ }
+
+ if (name === SystemRoles.ADMIN) {
+ const postCount = await countUsersByRole(SystemRoles.ADMIN);
+ if (postCount === 0) {
+ try {
+ await updateUser(userId, { role: SystemRoles.ADMIN });
+ } catch (rollbackError) {
+ logger.error(
+ `[adminRoles] CRITICAL: admin rollback failed for user ${userId}:`,
+ rollbackError,
+ );
+ }
+ return res.status(400).json({ error: 'Cannot remove the last admin user' });
+ }
+ }
+
+ return res.status(200).json({ success: true });
+ } catch (error) {
+ logger.error('[adminRoles] removeRoleMember error:', error);
+ return res.status(500).json({ error: 'Failed to remove role member' });
+ }
+ }
+
+ return {
+ listRoles: listRolesHandler,
+ getRole: getRoleHandler,
+ createRole: createRoleHandler,
+ updateRole: updateRoleHandler,
+ updateRolePermissions: updateRolePermissionsHandler,
+ deleteRole: deleteRoleHandler,
+ getRoleMembers: getRoleMembersHandler,
+ addRoleMember: addRoleMemberHandler,
+ removeRoleMember: removeRoleMemberHandler,
+ };
+}
diff --git a/packages/data-schemas/package.json b/packages/data-schemas/package.json
index 0124552002..145b8925d1 100644
--- a/packages/data-schemas/package.json
+++ b/packages/data-schemas/package.json
@@ -1,6 +1,6 @@
{
"name": "@librechat/data-schemas",
- "version": "0.0.46",
+ "version": "0.0.47",
"description": "Mongoose schemas and models for LibreChat",
"type": "module",
"main": "dist/index.cjs",
diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.ts
index cd683c937c..d673db1f5c 100644
--- a/packages/data-schemas/src/index.ts
+++ b/packages/data-schemas/src/index.ts
@@ -7,6 +7,7 @@ export * from './utils';
export { createModels } from './models';
export {
createMethods,
+ RoleConflictError,
DEFAULT_REFRESH_TOKEN_EXPIRY,
DEFAULT_SESSION_EXPIRY,
tokenValues,
diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.ts
index 4202cac0eb..830d88ff4c 100644
--- a/packages/data-schemas/src/methods/index.ts
+++ b/packages/data-schemas/src/methods/index.ts
@@ -1,9 +1,8 @@
import { createSessionMethods, DEFAULT_REFRESH_TOKEN_EXPIRY, type SessionMethods } from './session';
import { createTokenMethods, type TokenMethods } from './token';
-import { createRoleMethods, type RoleMethods, type RoleDeps } from './role';
+import { createRoleMethods, RoleConflictError } from './role';
+import type { RoleMethods, RoleDeps } from './role';
import { createUserMethods, DEFAULT_SESSION_EXPIRY, type UserMethods } from './user';
-
-export { DEFAULT_REFRESH_TOKEN_EXPIRY, DEFAULT_SESSION_EXPIRY };
import { createKeyMethods, type KeyMethods } from './key';
import { createFileMethods, type FileMethods } from './file';
/* Memories */
@@ -51,6 +50,7 @@ import { createAgentMethods, type AgentMethods, type AgentDeps } from './agent';
/* Config */
import { createConfigMethods, type ConfigMethods } from './config';
+export { RoleConflictError, DEFAULT_REFRESH_TOKEN_EXPIRY, DEFAULT_SESSION_EXPIRY };
export { tokenValues, cacheTokenValues, premiumTokenValues, defaultRate };
export type AllMethods = UserMethods &
diff --git a/packages/data-schemas/src/methods/role.methods.spec.ts b/packages/data-schemas/src/methods/role.methods.spec.ts
index 78d7f98ea1..f8a66bef5d 100644
--- a/packages/data-schemas/src/methods/role.methods.spec.ts
+++ b/packages/data-schemas/src/methods/role.methods.spec.ts
@@ -1,10 +1,17 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { SystemRoles, Permissions, roleDefaults, PermissionTypes } from 'librechat-data-provider';
-import type { IRole, RolePermissions } from '..';
+import type { IRole, IUser, RolePermissions } from '..';
import { createRoleMethods } from './role';
import { createModels } from '../models';
+jest.mock('~/config/winston', () => ({
+ error: jest.fn(),
+ warn: jest.fn(),
+ info: jest.fn(),
+ debug: jest.fn(),
+}));
+
const mockCache = {
get: jest.fn(),
set: jest.fn(),
@@ -14,9 +21,18 @@ const mockCache = {
const mockGetCache = jest.fn().mockReturnValue(mockCache);
let Role: mongoose.Model<IRole>;
+let User: mongoose.Model<IUser>;
let getRoleByName: ReturnType<typeof createRoleMethods>['getRoleByName'];
let updateAccessPermissions: ReturnType<typeof createRoleMethods>['updateAccessPermissions'];
let initializeRoles: ReturnType<typeof createRoleMethods>['initializeRoles'];
+let createRoleByName: ReturnType<typeof createRoleMethods>['createRoleByName'];
+let deleteRoleByName: ReturnType<typeof createRoleMethods>['deleteRoleByName'];
+let updateUsersByRole: ReturnType<typeof createRoleMethods>['updateUsersByRole'];
+let listUsersByRole: ReturnType<typeof createRoleMethods>['listUsersByRole'];
+let countUsersByRole: ReturnType<typeof createRoleMethods>['countUsersByRole'];
+let updateRoleByName: ReturnType<typeof createRoleMethods>['updateRoleByName'];
+let listRoles: ReturnType<typeof createRoleMethods>['listRoles'];
+let countRoles: ReturnType<typeof createRoleMethods>['countRoles'];
let mongoServer: MongoMemoryServer;
beforeAll(async () => {
@@ -25,10 +41,19 @@ beforeAll(async () => {
await mongoose.connect(mongoUri);
createModels(mongoose);
Role = mongoose.models.Role;
+ User = mongoose.models.User as mongoose.Model<IUser>;
const methods = createRoleMethods(mongoose, { getCache: mockGetCache });
getRoleByName = methods.getRoleByName;
updateAccessPermissions = methods.updateAccessPermissions;
initializeRoles = methods.initializeRoles;
+ createRoleByName = methods.createRoleByName;
+ deleteRoleByName = methods.deleteRoleByName;
+ updateRoleByName = methods.updateRoleByName;
+ updateUsersByRole = methods.updateUsersByRole;
+ listUsersByRole = methods.listUsersByRole;
+ countUsersByRole = methods.countUsersByRole;
+ listRoles = methods.listRoles;
+ countRoles = methods.countRoles;
});
afterAll(async () => {
@@ -38,6 +63,7 @@ afterAll(async () => {
beforeEach(async () => {
await Role.deleteMany({});
+ await User.deleteMany({});
mockGetCache.mockClear();
mockCache.get.mockClear();
mockCache.set.mockClear();
@@ -515,3 +541,362 @@ describe('initializeRoles', () => {
expect(userRole.permissions[PermissionTypes.MULTI_CONVO]?.USE).toBeDefined();
});
});
+
+describe('createRoleByName', () => {
+ it('creates a custom role and caches it', async () => {
+ const role = await createRoleByName({ name: 'editor', description: 'Can edit' });
+
+ expect(role.name).toBe('editor');
+ expect(role.description).toBe('Can edit');
+ expect(mockCache.set).toHaveBeenCalledWith(
+ 'editor',
+ expect.objectContaining({ name: 'editor' }),
+ );
+
+ const persisted = await Role.findOne({ name: 'editor' }).lean();
+ expect(persisted).toBeTruthy();
+ });
+
+ it('trims whitespace from role name', async () => {
+ const role = await createRoleByName({ name: ' editor ' });
+
+ expect(role.name).toBe('editor');
+ });
+
+ it('throws when name is empty', async () => {
+ await expect(createRoleByName({ name: '' })).rejects.toThrow('Role name is required');
+ });
+
+ it('throws when name is whitespace-only', async () => {
+ await expect(createRoleByName({ name: ' ' })).rejects.toThrow('Role name is required');
+ });
+
+ it('throws when name is undefined', async () => {
+ await expect(createRoleByName({})).rejects.toThrow('Role name is required');
+ });
+
+ it('throws for reserved system role names', async () => {
+ await expect(createRoleByName({ name: SystemRoles.ADMIN })).rejects.toThrow(
+ /reserved system name/,
+ );
+ await expect(createRoleByName({ name: SystemRoles.USER })).rejects.toThrow(
+ /reserved system name/,
+ );
+ });
+
+ it('throws when role already exists', async () => {
+ await createRoleByName({ name: 'editor' });
+
+ await expect(createRoleByName({ name: 'editor' })).rejects.toThrow(/already exists/);
+ });
+});
+
+describe('deleteRoleByName', () => {
+ it('deletes a custom role and reassigns users to USER', async () => {
+ await createRoleByName({ name: 'editor' });
+ await User.create([
+ { name: 'Alice', email: '[email protected]', role: 'editor', username: 'alice' },
+ { name: 'Bob', email: '[email protected]', role: 'editor', username: 'bob' },
+ { name: 'Carol', email: '[email protected]', role: SystemRoles.USER, username: 'carol' },
+ ]);
+
+ const deleted = await deleteRoleByName('editor');
+
+ expect(deleted).toBeTruthy();
+ expect(deleted!.name).toBe('editor');
+
+ const alice = await User.findOne({ email: '[email protected]' }).lean();
+ const bob = await User.findOne({ email: '[email protected]' }).lean();
+ const carol = await User.findOne({ email: '[email protected]' }).lean();
+ expect(alice!.role).toBe(SystemRoles.USER);
+ expect(bob!.role).toBe(SystemRoles.USER);
+ expect(carol!.role).toBe(SystemRoles.USER);
+ });
+
+ it('returns null when role does not exist', async () => {
+ const result = await deleteRoleByName('nonexistent');
+ expect(result).toBeNull();
+ });
+
+ it('throws for system roles', async () => {
+ await expect(deleteRoleByName(SystemRoles.ADMIN)).rejects.toThrow(/Cannot delete system role/);
+ await expect(deleteRoleByName(SystemRoles.USER)).rejects.toThrow(/Cannot delete system role/);
+ });
+
+ it('sets cache entry to null after deletion', async () => {
+ await createRoleByName({ name: 'editor' });
+ mockCache.set.mockClear();
+
+ await deleteRoleByName('editor');
+
+ expect(mockCache.set).toHaveBeenCalledWith('editor', null);
+ });
+
+ it('returns null and invalidates cache when role does not exist', async () => {
+ mockCache.set.mockClear();
+
+ const result = await deleteRoleByName('nonexistent');
+
+ expect(result).toBeNull();
+ expect(mockCache.set).toHaveBeenCalledWith('nonexistent', null);
+ });
+});
+
+describe('updateRoleByName - cache on rename', () => {
+ it('invalidates old key and populates new key on rename', async () => {
+ await createRoleByName({ name: 'editor', description: 'Can edit' });
+ mockCache.set.mockClear();
+
+ const updated = await updateRoleByName('editor', { name: 'senior-editor' });
+
+ expect(updated.name).toBe('senior-editor');
+ expect(mockCache.set).toHaveBeenCalledWith('editor', null);
+ expect(mockCache.set).toHaveBeenCalledWith(
+ 'senior-editor',
+ expect.objectContaining({ name: 'senior-editor' }),
+ );
+ });
+
+ it('writes same key when name unchanged', async () => {
+ await createRoleByName({ name: 'editor' });
+ mockCache.set.mockClear();
+
+ await updateRoleByName('editor', { description: 'Updated desc' });
+
+ expect(mockCache.set).toHaveBeenCalledWith(
+ 'editor',
+ expect.objectContaining({ name: 'editor', description: 'Updated desc' }),
+ );
+ expect(mockCache.set).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('listUsersByRole', () => {
+ it('returns users matching the role', async () => {
+ await User.create([
+ { name: 'Alice', email: '[email protected]', role: 'editor', username: 'alice' },
+ { name: 'Bob', email: '[email protected]', role: 'editor', username: 'bob' },
+ { name: 'Carol', email: '[email protected]', role: SystemRoles.USER, username: 'carol' },
+ ]);
+
+ const users = await listUsersByRole('editor');
+
+ expect(users).toHaveLength(2);
+ const names = users.map((u) => u.name).sort();
+ expect(names).toEqual(['Alice', 'Bob']);
+ });
+
+ it('returns empty array when no users have the role', async () => {
+ const users = await listUsersByRole('nonexistent');
+ expect(users).toEqual([]);
+ });
+
+ it('respects limit and offset for pagination', async () => {
+ await User.create([
+ { name: 'Alice', email: '[email protected]', role: 'editor', username: 'a' },
+ { name: 'Bob', email: '[email protected]', role: 'editor', username: 'b' },
+ { name: 'Carol', email: '[email protected]', role: 'editor', username: 'c' },
+ { name: 'Dave', email: '[email protected]', role: 'editor', username: 'd' },
+ { name: 'Eve', email: '[email protected]', role: 'editor', username: 'e' },
+ ]);
+
+ const page1 = await listUsersByRole('editor', { limit: 2, offset: 0 });
+ const page2 = await listUsersByRole('editor', { limit: 2, offset: 2 });
+ const page3 = await listUsersByRole('editor', { limit: 2, offset: 4 });
+
+ expect(page1).toHaveLength(2);
+ expect(page2).toHaveLength(2);
+ expect(page3).toHaveLength(1);
+
+ const allIds = [...page1, ...page2, ...page3].map((u) => u._id!.toString());
+ expect(new Set(allIds).size).toBe(5);
+ });
+
+ it('selects only expected fields', async () => {
+ await User.create({
+ name: 'Alice',
+ email: '[email protected]',
+ role: 'editor',
+ username: 'alice',
+ password: 'secret123',
+ });
+
+ const users = await listUsersByRole('editor');
+
+ expect(users).toHaveLength(1);
+ expect(users[0].name).toBe('Alice');
+ expect(users[0].email).toBe('[email protected]');
+ expect(users[0]._id).toBeDefined();
+ expect('password' in users[0]).toBe(false);
+ expect('username' in users[0]).toBe(false);
+ });
+});
+
+describe('updateUsersByRole', () => {
+ it('migrates all users from one role to another', async () => {
+ await User.create([
+ { name: 'Alice', email: '[email protected]', role: 'editor', username: 'alice' },
+ { name: 'Bob', email: '[email protected]', role: 'editor', username: 'bob' },
+ { name: 'Carol', email: '[email protected]', role: SystemRoles.USER, username: 'carol' },
+ ]);
+
+ await updateUsersByRole('editor', 'senior-editor');
+
+ const alice = await User.findOne({ email: '[email protected]' }).lean();
+ const bob = await User.findOne({ email: '[email protected]' }).lean();
+ const carol = await User.findOne({ email: '[email protected]' }).lean();
+ expect(alice!.role).toBe('senior-editor');
+ expect(bob!.role).toBe('senior-editor');
+ expect(carol!.role).toBe(SystemRoles.USER);
+ });
+
+ it('is a no-op when no users have the source role', async () => {
+ await User.create({
+ name: 'Alice',
+ email: '[email protected]',
+ role: SystemRoles.USER,
+ username: 'alice',
+ });
+
+ await updateUsersByRole('nonexistent', 'new-role');
+
+ const alice = await User.findOne({ email: '[email protected]' }).lean();
+ expect(alice!.role).toBe(SystemRoles.USER);
+ });
+});
+
+describe('countUsersByRole', () => {
+ it('returns the count of users with the given role', async () => {
+ await User.create([
+ { name: 'Alice', email: '[email protected]', role: 'editor', username: 'alice' },
+ { name: 'Bob', email: '[email protected]', role: 'editor', username: 'bob' },
+ { name: 'Carol', email: '[email protected]', role: SystemRoles.USER, username: 'carol' },
+ ]);
+
+ expect(await countUsersByRole('editor')).toBe(2);
+ expect(await countUsersByRole(SystemRoles.USER)).toBe(1);
+ });
+
+ it('returns 0 when no users have the role', async () => {
+ expect(await countUsersByRole('nonexistent')).toBe(0);
+ });
+});
+
+describe('listRoles', () => {
+ beforeEach(async () => {
+ await Role.deleteMany({});
+ });
+
+ it('returns roles sorted alphabetically by name', async () => {
+ await Role.create([
+ { name: 'zebra', permissions: {} },
+ { name: 'alpha', permissions: {} },
+ { name: 'middle', permissions: {} },
+ ]);
+
+ const roles = await listRoles();
+
+ expect(roles.map((r) => r.name)).toEqual(['alpha', 'middle', 'zebra']);
+ });
+
+ it('respects limit and offset for pagination', async () => {
+ await Role.create([
+ { name: 'a-role', permissions: {} },
+ { name: 'b-role', permissions: {} },
+ { name: 'c-role', permissions: {} },
+ { name: 'd-role', permissions: {} },
+ { name: 'e-role', permissions: {} },
+ ]);
+
+ const page1 = await listRoles({ limit: 2, offset: 0 });
+ const page2 = await listRoles({ limit: 2, offset: 2 });
+ const page3 = await listRoles({ limit: 2, offset: 4 });
+
+ expect(page1).toHaveLength(2);
+ expect(page1.map((r) => r.name)).toEqual(['a-role', 'b-role']);
+ expect(page2).toHaveLength(2);
+ expect(page2.map((r) => r.name)).toEqual(['c-role', 'd-role']);
+ expect(page3).toHaveLength(1);
+ expect(page3.map((r) => r.name)).toEqual(['e-role']);
+ });
+
+ it('defaults to limit 50 and offset 0', async () => {
+ await Role.create({ name: 'only-role', permissions: {} });
+
+ const roles = await listRoles();
+
+ expect(roles).toHaveLength(1);
+ expect(roles[0].name).toBe('only-role');
+ });
+
+ it('returns only name and description fields', async () => {
+ await Role.create({
+ name: 'editor',
+ description: 'Can edit',
+ permissions: { PROMPTS: { USE: true } },
+ });
+
+ const roles = await listRoles();
+
+ expect(roles).toHaveLength(1);
+ expect(roles[0].name).toBe('editor');
+ expect(roles[0].description).toBe('Can edit');
+ expect(roles[0]._id).toBeDefined();
+ expect('permissions' in roles[0]).toBe(false);
+ });
+
+ it('returns empty array when no roles exist', async () => {
+ const roles = await listRoles();
+ expect(roles).toEqual([]);
+ });
+
+ it('returns undefined description for pre-existing roles without the field', async () => {
+ await Role.collection.insertOne({ name: 'legacy', permissions: {} });
+
+ const roles = await listRoles();
+
+ expect(roles).toHaveLength(1);
+ expect(roles[0].name).toBe('legacy');
+ expect(roles[0].description).toBeUndefined();
+ });
+});
+
+describe('countRoles', () => {
+ beforeEach(async () => {
+ await Role.deleteMany({});
+ });
+
+ it('returns the total number of roles', async () => {
+ await Role.create([
+ { name: 'a', permissions: {} },
+ { name: 'b', permissions: {} },
+ { name: 'c', permissions: {} },
+ ]);
+
+ expect(await countRoles()).toBe(3);
+ });
+
+ it('returns 0 when no roles exist', async () => {
+ expect(await countRoles()).toBe(0);
+ });
+});
+
+describe('createRoleByName - duplicate key race', () => {
+ beforeEach(async () => {
+ await Role.deleteMany({});
+ });
+
+ it('throws RoleConflictError on concurrent insert (11000)', async () => {
+ await createRoleByName({ name: 'editor' });
+
+ const insertSpy = jest.spyOn(Role.prototype, 'save').mockImplementationOnce(() => {
+ const err = new Error('E11000 duplicate key error') as Error & { code: number };
+ err.code = 11000;
+ throw err;
+ });
+
+ await expect(createRoleByName({ name: 'editor2' })).rejects.toThrow(/already exists/);
+
+ insertSpy.mockRestore();
+ });
+});
diff --git a/packages/data-schemas/src/methods/role.ts b/packages/data-schemas/src/methods/role.ts
index 7b51e45330..442041dcde 100644
--- a/packages/data-schemas/src/methods/role.ts
+++ b/packages/data-schemas/src/methods/role.ts
@@ -5,9 +5,24 @@ import {
permissionsSchema,
removeNullishValues,
} from 'librechat-data-provider';
-import type { IRole } from '~/types';
+import type { Model } from 'mongoose';
+import type { IRole, IUser } from '~/types';
import logger from '~/config/winston';
+const systemRoleValues = new Set<string>(Object.values(SystemRoles));
+
+/** Case-insensitive check — the legacy roles route uppercases params. */
+function isSystemRoleName(name: string): boolean {
+ return systemRoleValues.has(name.toUpperCase());
+}
+
+export class RoleConflictError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = 'RoleConflictError';
+ }
+}
+
export interface RoleDeps {
/** Returns a cache store for the given key. Injected from getLogStores. */
getCache?: (key: string) => {
@@ -30,8 +45,11 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
const defaultPerms = roleDefaults[roleName].permissions;
if (!role) {
- role = new Role(roleDefaults[roleName]);
+ role = new Role({ ...roleDefaults[roleName], description: '' });
} else {
+ if (role.description == null) {
+ role.description = '';
+ }
const permissions = role.toObject()?.permissions ?? {};
role.permissions = role.permissions || {};
for (const permType of Object.keys(defaultPerms)) {
@@ -45,11 +63,26 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
}
/**
- * List all roles in the system.
+ * List all roles in the system. Returns only name and description (projected).
*/
- async function listRoles() {
+ async function listRoles(options?: {
+ limit?: number;
+ offset?: number;
+ }): Promise<Pick<IRole, '_id' | 'name' | 'description'>[]> {
const Role = mongoose.models.Role;
- return await Role.find({}).select('name permissions').lean();
+ const limit = options?.limit ?? 50;
+ const offset = options?.offset ?? 0;
+ return await Role.find({})
+ .select('name description')
+ .sort({ name: 1 })
+ .skip(offset)
+ .limit(limit)
+ .lean();
+ }
+
+ async function countRoles(): Promise<number> {
+ const Role = mongoose.models.Role;
+ return await Role.countDocuments({});
}
/**
@@ -73,7 +106,7 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
}
const role = await query.lean().exec();
- if (!role && SystemRoles[roleName as keyof typeof SystemRoles]) {
+ if (!role && systemRoleValues.has(roleName)) {
const newRole = await new Role(roleDefaults[roleName as keyof typeof roleDefaults]).save();
if (cache) {
await cache.set(roleName, newRole);
@@ -96,20 +129,24 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
const cache = deps.getCache?.(CacheKeys.ROLES);
try {
const Role = mongoose.models.Role;
- const role = await Role.findOneAndUpdate(
- { name: roleName },
- { $set: updates },
- { new: true, lean: true },
- )
+ const role = await Role.findOneAndUpdate({ name: roleName }, { $set: updates }, { new: true })
.select('-__v')
.lean()
.exec();
if (cache) {
- await cache.set(roleName, role);
+ if (updates.name && updates.name !== roleName) {
+ await Promise.all([cache.set(roleName, null), cache.set(updates.name, role)]);
+ } else {
+ await cache.set(roleName, role);
+ }
}
return role as unknown as IRole;
} catch (error) {
- throw new Error(`Failed to update role: ${(error as Error).message}`);
+ if (error && typeof error === 'object' && 'code' in error && error.code === 11000) {
+ const targetName = updates.name ?? roleName;
+ throw new RoleConflictError(`Role "${targetName}" already exists`);
+ }
+ throw new Error(`Failed to update role: ${(error as Error).message}`, { cause: error });
}
}
@@ -342,13 +379,137 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
}
}
+ /** Rejects names that match system roles. */
+ async function createRoleByName(roleData: Partial<IRole>): Promise<IRole> {
+ const { name } = roleData;
+ if (!name || typeof name !== 'string' || !name.trim()) {
+ throw new Error('Role name is required');
+ }
+ const trimmed = name.trim();
+ if (isSystemRoleName(trimmed)) {
+ throw new RoleConflictError(`Cannot create role with reserved system name: ${name}`);
+ }
+ const Role = mongoose.models.Role;
+ const existing = await Role.findOne({ name: trimmed }).lean();
+ if (existing) {
+ throw new RoleConflictError(`Role "${trimmed}" already exists`);
+ }
+ let role;
+ try {
+ role = await new Role({ ...roleData, name: trimmed }).save();
+ } catch (err) {
+ /**
+ * The compound unique index `{ name: 1, tenantId: 1 }` on the role schema
+ * (roleSchema.index in schema/role.ts) triggers error 11000 when a concurrent
+ * request races past the findOne check above. This catch converts it into
+ * the same user-facing message as the application-level duplicate check.
+ */
+ if (err && typeof err === 'object' && 'code' in err && err.code === 11000) {
+ throw new RoleConflictError(`Role "${trimmed}" already exists`);
+ }
+ throw err;
+ }
+ try {
+ const cache = deps.getCache?.(CacheKeys.ROLES);
+ if (cache) {
+ await cache.set(role.name, role.toObject());
+ }
+ } catch (cacheError) {
+ logger.error(`[createRoleByName] cache set failed for "${role.name}":`, cacheError);
+ }
+ return role.toObject() as IRole;
+ }
+
+ /**
+ * Guards against deleting system roles. Reassigns affected users back to USER.
+ *
+ * No existence pre-check is performed: for a nonexistent role the `updateMany`
+ * is a harmless no-op and `findOneAndDelete` returns null. This makes the
+ * function idempotent — a retry after a partial failure will still clean up
+ * orphaned user references and cache entries.
+ *
+ * Without a MongoDB transaction the two writes are non-atomic — if the delete
+ * fails after the reassignment, users will already have been moved to USER
+ * while the role document still exists. Recovery requires the caller to retry
+ * 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> {
+ if (isSystemRoleName(roleName)) {
+ throw new Error(`Cannot delete system role: ${roleName}`);
+ }
+ const Role = mongoose.models.Role;
+ const User = mongoose.models.User as Model<IUser>;
+ await User.updateMany({ role: roleName }, { $set: { role: SystemRoles.USER } });
+ const deleted = await Role.findOneAndDelete({ name: roleName }).lean();
+ try {
+ const cache = deps.getCache?.(CacheKeys.ROLES);
+ if (cache) {
+ // Setting null evicts the stale document. getRoleByName treats falsy cached
+ // values as a miss and falls through to the DB, so this does not provide
+ // negative caching — it only prevents serving the pre-deletion document.
+ await cache.set(roleName, null);
+ }
+ } catch (cacheError) {
+ logger.error(`[deleteRoleByName] cache invalidation failed for "${roleName}":`, cacheError);
+ }
+ return deleted as IRole | null;
+ }
+
+ async function updateUsersByRole(oldRole: string, newRole: string): Promise<void> {
+ const User = mongoose.models.User as Model<IUser>;
+ await User.updateMany({ role: oldRole }, { $set: { role: newRole } });
+ }
+
+ async function findUserIdsByRole(roleName: string): Promise<string[]> {
+ const User = mongoose.models.User as Model<IUser>;
+ const users = await User.find({ role: roleName }).select('_id').lean();
+ return users.map((u) => u._id.toString());
+ }
+
+ async function updateUsersRoleByIds(userIds: string[], newRole: string): Promise<void> {
+ if (userIds.length === 0) {
+ return;
+ }
+ const User = mongoose.models.User as Model<IUser>;
+ await User.updateMany({ _id: { $in: userIds } }, { $set: { role: newRole } });
+ }
+
+ async function listUsersByRole(
+ roleName: string,
+ options?: { limit?: number; offset?: number },
+ ): Promise<IUser[]> {
+ const User = mongoose.models.User as Model<IUser>;
+ const limit = options?.limit ?? 50;
+ const offset = options?.offset ?? 0;
+ return await User.find({ role: roleName })
+ .select('_id name email avatar')
+ .sort({ _id: 1 })
+ .skip(offset)
+ .limit(limit)
+ .lean();
+ }
+
+ async function countUsersByRole(roleName: string): Promise<number> {
+ const User = mongoose.models.User as Model<IUser>;
+ return await User.countDocuments({ role: roleName });
+ }
+
return {
listRoles,
+ countRoles,
initializeRoles,
getRoleByName,
updateRoleByName,
updateAccessPermissions,
migrateRoleSchema,
+ createRoleByName,
+ deleteRoleByName,
+ updateUsersByRole,
+ findUserIdsByRole,
+ updateUsersRoleByIds,
+ listUsersByRole,
+ countUsersByRole,
};
}
diff --git a/packages/data-schemas/src/schema/role.ts b/packages/data-schemas/src/schema/role.ts
index 1c27478ef6..ac478c2a83 100644
--- a/packages/data-schemas/src/schema/role.ts
+++ b/packages/data-schemas/src/schema/role.ts
@@ -73,6 +73,7 @@ const rolePermissionsSchema = new Schema(
const roleSchema: Schema<IRole> = new Schema({
name: { type: String, required: true, index: true },
+ description: { type: String, default: '' },
permissions: {
type: rolePermissionsSchema,
},
diff --git a/packages/data-schemas/src/schema/user.ts b/packages/data-schemas/src/schema/user.ts
index 92680415bd..f807ddd8d6 100644
--- a/packages/data-schemas/src/schema/user.ts
+++ b/packages/data-schemas/src/schema/user.ts
@@ -158,6 +158,7 @@ const userSchema = new Schema<IUser>(
);
userSchema.index({ email: 1, tenantId: 1 }, { unique: true });
+userSchema.index({ role: 1, tenantId: 1 });
const oAuthIdFields = [
'googleId',
diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.ts
index 99915f659d..9b30cdb98a 100644
--- a/packages/data-schemas/src/types/admin.ts
+++ b/packages/data-schemas/src/types/admin.ts
@@ -114,7 +114,7 @@ export type AdminMember = {
name: string;
email: string;
avatarUrl?: string;
- joinedAt: string;
+ joinedAt?: string;
};
/** Minimal user info returned by user search endpoints. */
diff --git a/packages/data-schemas/src/types/role.ts b/packages/data-schemas/src/types/role.ts
index 60a579240c..bc85284c34 100644
--- a/packages/data-schemas/src/types/role.ts
+++ b/packages/data-schemas/src/types/role.ts
@@ -5,6 +5,7 @@ import { CursorPaginationParams } from '~/common';
export interface IRole extends Document {
name: string;
+ description?: string;
permissions: {
[PermissionTypes.BOOKMARKS]?: {
[Permissions.USE]?: boolean;
@@ -74,11 +75,13 @@ export type RolePermissionsInput = DeepPartial<RolePermissions>;
export interface CreateRoleRequest {
name: string;
+ description?: string;
permissions: RolePermissionsInput;
}
export interface UpdateRoleRequest {
name?: string;
+ description?: string;
permissions?: RolePermissionsInput;
}