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 Users API Endpoints (#12446)
Dustin Healy3d1b883e9d13
diff --git a/api/server/index.js b/api/server/index.jsindex 79776587b5..92e730332a 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -157,6 +157,7 @@ const startServer = async () => {app.use('/api/admin/grants', routes.adminGrants);app.use('/api/admin/groups', routes.adminGroups);app.use('/api/admin/roles', routes.adminRoles);+ app.use('/api/admin/users', routes.adminUsers);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/users.js b/api/server/routes/admin/users.jsnew file mode 100644index 0000000000..46ef16e7c2--- /dev/null+++ b/api/server/routes/admin/users.js@@ -0,0 +1,29 @@+const express = require('express');+const { createAdminUsersHandlers } = 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 requireReadUsers = requireCapability(SystemCapabilities.READ_USERS);+// const requireManageUsers = requireCapability(SystemCapabilities.MANAGE_USERS);++const handlers = createAdminUsersHandlers({+ findUsers: db.findUsers,+ countUsers: db.countUsers,+ deleteUserById: db.deleteUserById,+ deleteConfig: db.deleteConfig,+ deleteAclEntries: db.deleteAclEntries,+ deleteGrantsForPrincipal: db.deleteGrantsForPrincipal,+});++router.use(requireJwtAuth, requireAdminAccess);++router.get('/', requireReadUsers, handlers.listUsers);+router.get('/search', requireReadUsers, handlers.searchUsers);+// router.delete('/:id', requireManageUsers, handlers.deleteUser);++module.exports = router;diff --git a/api/server/routes/index.js b/api/server/routes/index.jsindex 245a7db8c6..1feaf63fdb 100644--- a/api/server/routes/index.js+++ b/api/server/routes/index.js@@ -6,6 +6,7 @@ const adminConfig = require('./admin/config');const adminGrants = require('./admin/grants');const adminGroups = require('./admin/groups');const adminRoles = require('./admin/roles');+const adminUsers = require('./admin/users');const endpoints = require('./endpoints');const staticRoute = require('./static');const messages = require('./messages');@@ -39,6 +40,7 @@ module.exports = {adminGrants,adminGroups,adminRoles,+ adminUsers,keys,apiKeys,user,diff --git a/packages/api/src/admin/index.ts b/packages/api/src/admin/index.tsindex f32fb057e8..038ca23915 100644--- a/packages/api/src/admin/index.ts+++ b/packages/api/src/admin/index.ts@@ -2,7 +2,9 @@ export { createAdminConfigHandlers } from './config';export { createAdminGrantsHandlers } from './grants';export { createAdminGroupsHandlers } from './groups';export { createAdminRolesHandlers } from './roles';+export { createAdminUsersHandlers } from './users';export type { AdminConfigDeps } from './config';export type { AdminGrantsDeps, GrantPrincipalType } from './grants';export type { AdminGroupsDeps } from './groups';export type { AdminRolesDeps } from './roles';+export type { AdminUsersDeps } from './users';diff --git a/packages/api/src/admin/users.spec.ts b/packages/api/src/admin/users.spec.tsnew file mode 100644index 0000000000..d4191eafac--- /dev/null+++ b/packages/api/src/admin/users.spec.ts@@ -0,0 +1,525 @@+import { Types } from 'mongoose';+import { PrincipalType, SystemRoles } from 'librechat-data-provider';+import type { IUser, UserDeleteResult } from '@librechat/data-schemas';+import type { Response } from 'express';+import type { ServerRequest } from '~/types/http';+import type { AdminUsersDeps } from './users';+import { createAdminUsersHandlers } from './users';++jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),+ logger: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },+}));++const validUserId = new Types.ObjectId().toString();++function mockUser(overrides: Partial<IUser> = {}): IUser {+ return {+ _id: new Types.ObjectId(),+ name: 'Test User',+ username: 'testuser',+ email: '[email protected]',+ avatar: 'https://example.com/avatar.png',+ role: 'USER',+ provider: 'local',+ createdAt: new Date('2025-01-01'),+ updatedAt: new Date('2025-06-01'),+ ...overrides,+ } as IUser;+}++function createReqRes(+ overrides: {+ params?: Record<string, string>;+ query?: Record<string, string | string[]>;+ user?: { _id?: Types.ObjectId; id?: string; role?: string; tenantId?: string };+ } = {},+) {+ const req = {+ params: overrides.params ?? {},+ query: overrides.query ?? {},+ body: {},+ user: overrides.user ?? { _id: new Types.ObjectId(), role: 'admin' },+ } 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<AdminUsersDeps> = {}): AdminUsersDeps {+ return {+ findUsers: jest.fn().mockResolvedValue([]),+ countUsers: jest.fn().mockResolvedValue(0),+ deleteUserById: jest+ .fn()+ .mockResolvedValue({ deletedCount: 1, message: 'User was deleted successfully.' }),+ deleteConfig: jest.fn().mockResolvedValue(null),+ deleteAclEntries: jest.fn().mockResolvedValue(undefined),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue(undefined),+ ...overrides,+ };+}++describe('createAdminUsersHandlers', () => {+ describe('listUsers', () => {+ it('returns paginated users with total count', async () => {+ const users = [+ mockUser({ _id: new Types.ObjectId(validUserId) }),+ mockUser({ name: 'Other' }),+ ];+ const deps = createDeps({+ findUsers: jest.fn().mockResolvedValue(users),+ countUsers: jest.fn().mockResolvedValue(2),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listUsers(req, res);++ expect(status).toHaveBeenCalledWith(200);+ const response = json.mock.calls[0][0];+ expect(response.users).toHaveLength(2);+ expect(response.total).toBe(2);+ expect(response).toHaveProperty('limit');+ expect(response).toHaveProperty('offset');+ expect(response.users[0]).toHaveProperty('id');+ expect(response.users[0]).toHaveProperty('name');+ expect(response.users[0]).toHaveProperty('email');+ expect(response.users[0]).toHaveProperty('role');+ });++ it('passes pagination params to findUsers and unfiltered count', async () => {+ const findUsers = jest.fn().mockResolvedValue([]);+ const countUsers = jest.fn().mockResolvedValue(0);+ const deps = createDeps({ findUsers, countUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { limit: '10', offset: '20' } });++ await handlers.listUsers(req, res);++ expect(findUsers).toHaveBeenCalledWith({}, expect.any(String), {+ limit: 10,+ offset: 20,+ sort: { createdAt: -1 },+ });+ expect(countUsers).toHaveBeenCalledWith();+ });++ it('returns empty list when no users', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listUsers(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json.mock.calls[0][0].users).toEqual([]);+ expect(json.mock.calls[0][0].total).toBe(0);+ });++ it('returns 500 when findUsers throws', async () => {+ const deps = createDeps({ findUsers: jest.fn().mockRejectedValue(new Error('db down')) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listUsers(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to list users' });+ });++ it('returns 500 when countUsers throws', async () => {+ const deps = createDeps({+ countUsers: jest.fn().mockRejectedValue(new Error('count failed')),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listUsers(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to list users' });+ });+ });++ describe('searchUsers', () => {+ it('returns matching users with total and capped flag', async () => {+ const users = [mockUser()];+ const deps = createDeps({ findUsers: jest.fn().mockResolvedValue(users) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: 'test' } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(200);+ const response = json.mock.calls[0][0];+ expect(response.users).toHaveLength(1);+ expect(response.total).toBe(1);+ expect(response.capped).toBe(false);+ expect(response.users[0]).toHaveProperty('id');+ expect(response.users[0]).toHaveProperty('name');+ expect(response.users[0]).toHaveProperty('email');+ expect(response.users[0]).toHaveProperty('username');+ });++ it('sets capped to true when results hit the limit', async () => {+ const users = Array.from({ length: 20 }, () => mockUser());+ const deps = createDeps({ findUsers: jest.fn().mockResolvedValue(users) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, json } = createReqRes({ query: { q: 'test', limit: '20' } });++ await handlers.searchUsers(req, res);++ const response = json.mock.calls[0][0];+ expect(response.total).toBe(20);+ expect(response.capped).toBe(true);+ });++ it('searches name, email, and username with anchored prefix regex', async () => {+ const findUsers = jest.fn().mockResolvedValue([]);+ const deps = createDeps({ findUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { q: 'test' } });++ await handlers.searchUsers(req, res);++ const filter = findUsers.mock.calls[0][0];+ expect(filter.$or).toHaveLength(3);+ expect(filter.$or[0]).toHaveProperty('name');+ expect(filter.$or[1]).toHaveProperty('email');+ expect(filter.$or[2]).toHaveProperty('username');+ expect(filter.$or[0].name.source).toBe('^test');+ });++ it('projects username in the field selection', async () => {+ const findUsers = jest.fn().mockResolvedValue([]);+ const deps = createDeps({ findUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { q: 'test' } });++ await handlers.searchUsers(req, res);++ const projection = findUsers.mock.calls[0][1];+ expect(projection).toContain('username');+ });++ it('escapes regex special characters in query', async () => {+ const findUsers = jest.fn().mockResolvedValue([]);+ const deps = createDeps({ findUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { q: 'test.user+1' } });++ await handlers.searchUsers(req, res);++ const filter = findUsers.mock.calls[0][0];+ expect(filter.$or[0].name).toBeInstanceOf(RegExp);+ expect(filter.$or[0].name.source).toBe('^test\\.user\\+1');+ });++ it('returns 400 when query is missing', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: {} });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Query parameter "q" is required' });+ });++ it('returns 400 when query is empty string', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: '' } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Query parameter "q" is required' });+ });++ it('returns 400 when query is whitespace-only', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: ' ' } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Query parameter "q" is required' });+ });++ it('returns 400 when query is too short', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: 'a' } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Query must be at least 2 characters' });+ });++ it('returns 400 when query exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: 'a'.repeat(201) } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith(+ expect.objectContaining({ error: expect.stringContaining('200') }),+ );+ });++ it('treats array query param as missing', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: ['foo', 'bar'] } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Query parameter "q" is required' });+ });++ it('passes limit to findUsers', async () => {+ const findUsers = jest.fn().mockResolvedValue([mockUser()]);+ const deps = createDeps({ findUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { q: 'User', limit: '3' } });++ await handlers.searchUsers(req, res);++ expect(findUsers).toHaveBeenCalledWith(expect.any(Object), expect.any(String), {+ limit: 3,+ sort: { name: 1 },+ });+ });++ it('caps limit at 50', async () => {+ const findUsers = jest.fn().mockResolvedValue([]);+ const deps = createDeps({ findUsers });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({ query: { q: 'User', limit: '100' } });++ await handlers.searchUsers(req, res);++ expect(findUsers).toHaveBeenCalledWith(expect.any(Object), expect.any(String), {+ limit: 50,+ sort: { name: 1 },+ });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({ findUsers: jest.fn().mockRejectedValue(new Error('db down')) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: { q: 'test' } });++ await handlers.searchUsers(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to search users' });+ });+ });++ describe('deleteUser', () => {+ it('deletes user and returns 200', async () => {+ const result: UserDeleteResult = {+ deletedCount: 1,+ message: 'User was deleted successfully.',+ };+ const deps = createDeps({ deleteUserById: jest.fn().mockResolvedValue(result) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ message: 'User was deleted successfully.' });+ });++ it('returns fallback message when result.message is empty', async () => {+ const result: UserDeleteResult = { deletedCount: 1, message: '' };+ const deps = createDeps({ deleteUserById: jest.fn().mockResolvedValue(result) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ message: 'User deleted successfully' });+ });++ it('returns 403 when deleting own account', async () => {+ const userId = new Types.ObjectId();+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: userId.toString() },+ user: { _id: userId, role: 'admin' },+ });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(403);+ expect(json).toHaveBeenCalledWith({ error: 'Cannot delete your own account' });+ expect(deps.deleteUserById).not.toHaveBeenCalled();+ });++ it('returns 400 when deleting the last admin', async () => {+ const targetId = new Types.ObjectId().toString();+ const deps = createDeps({+ findUsers: jest.fn().mockResolvedValue([mockUser({ role: SystemRoles.ADMIN })]),+ countUsers: jest.fn().mockResolvedValue(1),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: targetId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Cannot delete the last admin user' });+ expect(deps.deleteUserById).not.toHaveBeenCalled();+ expect(deps.countUsers).toHaveBeenCalledWith({ role: SystemRoles.ADMIN });+ });++ it('allows deleting an admin when other admins exist', async () => {+ const targetId = new Types.ObjectId().toString();+ const deps = createDeps({+ findUsers: jest.fn().mockResolvedValue([mockUser({ role: SystemRoles.ADMIN })]),+ countUsers: jest.fn().mockResolvedValue(3),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status } = createReqRes({ params: { id: targetId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.deleteUserById).toHaveBeenCalledWith(targetId);+ });++ it('does not check admin count when target is a regular user', async () => {+ const targetId = new Types.ObjectId().toString();+ const deps = createDeps({+ findUsers: jest.fn().mockResolvedValue([mockUser({ role: 'USER' })]),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status } = createReqRes({ params: { id: targetId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.countUsers).not.toHaveBeenCalled();+ });++ it('cascades cleanup of Config, AclEntries, and SystemGrants', async () => {+ const result: UserDeleteResult = {+ deletedCount: 1,+ message: 'User was deleted successfully.',+ };+ const deps = createDeps({ deleteUserById: jest.fn().mockResolvedValue(result) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.deleteConfig).toHaveBeenCalledWith(PrincipalType.USER, validUserId);+ expect(deps.deleteAclEntries).toHaveBeenCalledWith({+ principalType: PrincipalType.USER,+ principalId: expect.any(Types.ObjectId),+ });+ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.USER, validUserId, {+ tenantId: undefined,+ });+ });++ it('scopes grant cleanup to the caller tenantId', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res } = createReqRes({+ params: { id: validUserId },+ user: { _id: new Types.ObjectId(), role: 'admin', tenantId: 'tenant-xyz' },+ });++ await handlers.deleteUser(req, res);++ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.USER, validUserId, {+ tenantId: 'tenant-xyz',+ });+ });++ it('returns success even when cascade cleanup partially fails', async () => {+ const result: UserDeleteResult = {+ deletedCount: 1,+ message: 'User was deleted successfully.',+ };+ const deps = createDeps({+ deleteUserById: jest.fn().mockResolvedValue(result),+ deleteConfig: jest.fn().mockRejectedValue(new Error('cleanup failed')),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ message: 'User was deleted successfully.' });+ });++ it('does not cascade when user is not found', async () => {+ const result: UserDeleteResult = { deletedCount: 0, message: '' };+ const deps = createDeps({ deleteUserById: jest.fn().mockResolvedValue(result) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(deps.deleteConfig).not.toHaveBeenCalled();+ expect(deps.deleteAclEntries).not.toHaveBeenCalled();+ expect(deps.deleteGrantsForPrincipal).not.toHaveBeenCalled();+ });++ it('returns 400 for invalid ObjectId', async () => {+ const deps = createDeps();+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: 'not-valid' } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid user ID format' });+ });++ it('returns 404 when user not found', async () => {+ const result: UserDeleteResult = { deletedCount: 0, message: '' };+ const deps = createDeps({ deleteUserById: jest.fn().mockResolvedValue(result) });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'User not found' });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({+ deleteUserById: jest.fn().mockRejectedValue(new Error('db crash')),+ });+ const handlers = createAdminUsersHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validUserId } });++ await handlers.deleteUser(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to delete user' });+ });+ });+});diff --git a/packages/api/src/admin/users.ts b/packages/api/src/admin/users.tsnew file mode 100644index 0000000000..8679b0dbcf--- /dev/null+++ b/packages/api/src/admin/users.ts@@ -0,0 +1,198 @@+import { Types } from 'mongoose';+import { PrincipalType, SystemRoles } from 'librechat-data-provider';+import { logger, isValidObjectIdString } from '@librechat/data-schemas';+import type {+ IUser,+ IConfig,+ AdminUserListItem,+ AdminUserSearchResult,+ UserDeleteResult,+} from '@librechat/data-schemas';+import type { FilterQuery } from 'mongoose';+import type { Response } from 'express';+import type { ServerRequest } from '~/types/http';+import { parsePagination } from './pagination';++const MAX_SEARCH_LENGTH = 200;++const USER_LIST_FIELDS = '_id name username email avatar role provider createdAt updatedAt';++export interface AdminUsersDeps {+ findUsers: (+ searchCriteria: FilterQuery<IUser>,+ fieldsToSelect?: string | string[] | null,+ options?: { limit?: number; offset?: number; sort?: Record<string, 1 | -1> },+ ) => Promise<IUser[]>;+ countUsers: (filter?: FilterQuery<IUser>) => Promise<number>;+ /**+ * Thin data-layer delete — removes the User document only.+ * Full cascade of user-owned resources (conversations, messages, files, tokens, etc.)+ * is handled by `UserController.deleteUserController` in the self-delete flow.+ * This admin endpoint currently cascades Config, AclEntries, and SystemGrants.+ * A future iteration should consolidate the full cascade into a shared service function.+ */+ deleteUserById: (userId: string) => Promise<UserDeleteResult>;+ deleteConfig: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ ) => Promise<IConfig | null>;+ deleteAclEntries: (filter: {+ principalType: PrincipalType;+ principalId: string | Types.ObjectId;+ }) => Promise<void>;+ deleteGrantsForPrincipal: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ options?: { tenantId?: string },+ ) => Promise<void>;+}++export function createAdminUsersHandlers(deps: AdminUsersDeps) {+ const {+ findUsers,+ countUsers,+ deleteUserById,+ deleteConfig,+ deleteAclEntries,+ deleteGrantsForPrincipal,+ } = deps;++ async function listUsersHandler(req: ServerRequest, res: Response) {+ try {+ const { limit, offset } = parsePagination(req.query);+ const [users, total] = await Promise.all([+ findUsers({}, USER_LIST_FIELDS, { limit, offset, sort: { createdAt: -1 } }),+ countUsers(),+ ]);++ const mapped: AdminUserListItem[] = users.map((u) => ({+ id: u._id?.toString() ?? '',+ name: u.name ?? '',+ username: u.username ?? '',+ email: u.email ?? '',+ avatar: u.avatar ?? '',+ role: u.role ?? 'USER',+ provider: u.provider ?? 'local',+ createdAt: u.createdAt?.toISOString(),+ updatedAt: u.updatedAt?.toISOString(),+ }));++ return res.status(200).json({ users: mapped, total, limit, offset });+ } catch (error) {+ logger.error('[adminUsers] listUsers error:', error);+ return res.status(500).json({ error: 'Failed to list users' });+ }+ }++ async function searchUsersHandler(req: ServerRequest, res: Response) {+ try {+ const rawQ = req.query.q;+ const rawLimit = req.query.limit;+ const query = typeof rawQ === 'string' ? rawQ : undefined;+ const limitStr = typeof rawLimit === 'string' ? rawLimit : '20';+ const trimmed = query?.trim() ?? '';++ if (!trimmed) {+ return res.status(400).json({ error: 'Query parameter "q" is required' });+ }++ if (trimmed.length < 2) {+ return res.status(400).json({ error: 'Query must be at least 2 characters' });+ }++ if (trimmed.length > MAX_SEARCH_LENGTH) {+ return res+ .status(400)+ .json({ error: `Query must not exceed ${MAX_SEARCH_LENGTH} characters` });+ }++ const searchLimit = Math.min(Math.max(1, parseInt(limitStr, 10) || 20), 50);+ const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ const regex = new RegExp(`^${escaped}`, 'i');++ const users = await findUsers(+ { $or: [{ name: regex }, { email: regex }, { username: regex }] },+ '_id name email username avatar',+ { limit: searchLimit, sort: { name: 1 } },+ );++ const results: AdminUserSearchResult[] = users.map((u) => ({+ id: u._id?.toString() ?? '',+ name: u.name ?? '',+ email: u.email ?? '',+ username: u.username,+ avatarUrl: u.avatar,+ }));++ return res+ .status(200)+ .json({ users: results, total: results.length, capped: results.length >= searchLimit });+ } catch (error) {+ logger.error('[adminUsers] searchUsers error:', error);+ return res.status(500).json({ error: 'Failed to search users' });+ }+ }++ async function deleteUserHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as { id: string };++ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid user ID format' });+ }++ const callerId = req.user?._id?.toString() ?? req.user?.id;+ if (callerId === id) {+ return res.status(403).json({ error: 'Cannot delete your own account' });+ }++ const [targetUser] = await findUsers({ _id: id }, 'role', { limit: 1 });+ if (targetUser?.role === SystemRoles.ADMIN) {+ const adminCount = await countUsers({ role: SystemRoles.ADMIN });+ if (adminCount <= 1) {+ return res.status(400).json({ error: 'Cannot delete the last admin user' });+ }+ }++ const result = await deleteUserById(id);++ if (result.deletedCount === 0) {+ return res.status(404).json({ error: 'User not found' });+ }++ if (targetUser?.role === SystemRoles.ADMIN) {+ const remaining = await countUsers({ role: SystemRoles.ADMIN });+ if (remaining === 0) {+ logger.error(+ `[adminUsers] CRITICAL: last admin deleted via race condition, user: ${id}. ` ++ 'Manual DB intervention required to restore an ADMIN user.',+ );+ }+ }++ const objectId = new Types.ObjectId(id);+ const tenantId = req.user?.tenantId;+ const cleanupResults = await Promise.allSettled([+ deleteConfig(PrincipalType.USER, id),+ deleteAclEntries({ principalType: PrincipalType.USER, principalId: objectId }),+ deleteGrantsForPrincipal(PrincipalType.USER, id, { tenantId }),+ ]);+ for (const r of cleanupResults) {+ if (r.status === 'rejected') {+ logger.error('[adminUsers] cascade cleanup failed for user:', id, r.reason);+ }+ }++ return res.status(200).json({ message: result.message || 'User deleted successfully' });+ } catch (error) {+ logger.error('[adminUsers] deleteUser error:', error);+ return res.status(500).json({ error: 'Failed to delete user' });+ }+ }++ return {+ listUsers: listUsersHandler,+ searchUsers: searchUsersHandler,+ deleteUser: deleteUserHandler,+ };+}diff --git a/packages/api/src/middleware/capabilities.spec.ts b/packages/api/src/middleware/capabilities.spec.tsindex 75d3142369..bfcc43f43d 100644--- a/packages/api/src/middleware/capabilities.spec.ts+++ b/packages/api/src/middleware/capabilities.spec.ts@@ -11,6 +11,7 @@ import { generateCapabilityCheck } from './capabilities';jest.mock('@librechat/data-schemas', () => ({...jest.requireActual('@librechat/data-schemas'),logger: {+ warn: jest.fn(),error: jest.fn(),},}));diff --git a/packages/api/src/middleware/capabilities.ts b/packages/api/src/middleware/capabilities.tsindex 6e784a9aa7..7be93888c7 100644--- a/packages/api/src/middleware/capabilities.ts+++ b/packages/api/src/middleware/capabilities.ts@@ -191,6 +191,7 @@ export function generateCapabilityCheck(deps: CapabilityDeps): {return;}+ logger.warn(`[requireCapability] Forbidden: user ${id} missing capability '${capability}'`);res.status(403).json({ message: 'Forbidden' });} catch (err) {logger.error(`[requireCapability] Error checking capability: ${capability}`, err);diff --git a/packages/data-schemas/src/methods/user.methods.spec.ts b/packages/data-schemas/src/methods/user.methods.spec.tsindex 9fd33c5031..90f9100d1d 100644--- a/packages/data-schemas/src/methods/user.methods.spec.ts+++ b/packages/data-schemas/src/methods/user.methods.spec.ts@@ -620,4 +620,62 @@ describe('User Methods - Database Tests', () => {expect(found?.provider).toBe('saml');});});++ describe('findUsers with options', () => {+ beforeEach(async () => {+ await User.create([+ { name: 'Alice', email: '[email protected]', provider: 'local' },+ { name: 'Bob', email: '[email protected]', provider: 'local' },+ { name: 'Charlie', email: '[email protected]', provider: 'local' },+ { name: 'Diana', email: '[email protected]', provider: 'local' },+ { name: 'Eve', email: '[email protected]', provider: 'local' },+ ]);+ });++ test('limit restricts the number of returned documents', async () => {+ const users = await methods.findUsers({}, null, { limit: 2 });+ expect(users).toHaveLength(2);+ });++ test('offset skips the first N documents', async () => {+ const all = await methods.findUsers({}, 'name', { sort: { name: 1 } });+ const skipped = await methods.findUsers({}, 'name', { offset: 2, sort: { name: 1 } });++ expect(skipped).toHaveLength(3);+ expect(skipped[0].name).toBe(all[2].name);+ });++ test('sort orders results by the specified field', async () => {+ const asc = await methods.findUsers({}, 'name', { sort: { name: 1 } });+ const desc = await methods.findUsers({}, 'name', { sort: { name: -1 } });++ expect(asc[0].name).toBe('Alice');+ expect(asc[4].name).toBe('Eve');+ expect(desc[0].name).toBe('Eve');+ expect(desc[4].name).toBe('Alice');+ });++ test('limit + offset returns the correct page', async () => {+ const sorted = await methods.findUsers({}, 'name', { sort: { name: 1 } });+ const page2 = await methods.findUsers({}, 'name', {+ limit: 2,+ offset: 2,+ sort: { name: 1 },+ });++ expect(page2).toHaveLength(2);+ expect(page2[0].name).toBe(sorted[2].name);+ expect(page2[1].name).toBe(sorted[3].name);+ });++ test('limit of 0 does not restrict results', async () => {+ const users = await methods.findUsers({}, null, { limit: 0 });+ expect(users).toHaveLength(5);+ });++ test('returns all documents when no options provided', async () => {+ const users = await methods.findUsers({});+ expect(users).toHaveLength(5);+ });+ });});diff --git a/packages/data-schemas/src/methods/user.ts b/packages/data-schemas/src/methods/user.tsindex 0b630e49b3..3c886f8b16 100644--- a/packages/data-schemas/src/methods/user.ts+++ b/packages/data-schemas/src/methods/user.ts@@ -47,6 +47,7 @@ export function createUserMethods(mongoose: typeof import('mongoose')) {async function findUsers(searchCriteria: FilterQuery<IUser>,fieldsToSelect?: string | string[] | null,+ options?: { limit?: number; offset?: number; sort?: Record<string, 1 | -1> },): Promise<IUser[]> {const User = mongoose.models.User as mongoose.Model<IUser>;const normalizedCriteria = normalizeEmailInCriteria(searchCriteria);@@ -54,7 +55,16 @@ export function createUserMethods(mongoose: typeof import('mongoose')) {if (fieldsToSelect) {query.select(fieldsToSelect);}- return await query.lean();+ if (options?.sort != null) {+ query.sort(options.sort);+ }+ if (options?.offset != null) {+ query.skip(options.offset);+ }+ if (options?.limit != null && options.limit > 0) {+ query.limit(options.limit);+ }+ return (await query.lean()) as IUser[];}/**diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.tsindex a16f68ae9c..755bb7a2e6 100644--- a/packages/data-schemas/src/types/admin.ts+++ b/packages/data-schemas/src/types/admin.ts@@ -111,10 +111,24 @@ export type AdminMember = {joinedAt?: string;};+/** Full user info returned by the admin user list endpoint. */+export type AdminUserListItem = {+ id: string;+ name: string;+ username: string;+ email: string;+ avatar: string;+ role: string;+ provider: string;+ createdAt?: string;+ updatedAt?: string;+};+/** Minimal user info returned by user search endpoints. */export type AdminUserSearchResult = {- userId: string;+ id: string;name: string;email: string;+ username?: string;avatarUrl?: string;};