Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪪 feat: Admin Roles API Endpoints (#12400)
Dustin Healy5972a21479e6
diff --git a/api/server/index.js b/api/server/index.jsindex 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.jsnew file mode 100644index 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.jsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: Rolconst 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: Rolconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;}