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 Groups API Endpoints (#12387)
Dustin Healy2e3d66cfe288
diff --git a/api/server/index.js b/api/server/index.jsindex de99f06701..4ecc966476 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -144,6 +144,7 @@ const startServer = async () => {app.use('/api/auth', routes.auth);app.use('/api/admin', routes.adminAuth);app.use('/api/admin/config', routes.adminConfig);+ app.use('/api/admin/groups', routes.adminGroups);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/groups.js b/api/server/routes/admin/groups.jsnew file mode 100644index 0000000000..7ca93acaa2--- /dev/null+++ b/api/server/routes/admin/groups.js@@ -0,0 +1,41 @@+const express = require('express');+const { createAdminGroupsHandlers } = 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 requireReadGroups = requireCapability(SystemCapabilities.READ_GROUPS);+const requireManageGroups = requireCapability(SystemCapabilities.MANAGE_GROUPS);++const handlers = createAdminGroupsHandlers({+ listGroups: db.listGroups,+ countGroups: db.countGroups,+ findGroupById: db.findGroupById,+ createGroup: db.createGroup,+ updateGroupById: db.updateGroupById,+ deleteGroup: db.deleteGroup,+ addUserToGroup: db.addUserToGroup,+ removeUserFromGroup: db.removeUserFromGroup,+ removeMemberById: db.removeMemberById,+ findUsers: db.findUsers,+ deleteConfig: db.deleteConfig,+ deleteAclEntries: db.deleteAclEntries,+ deleteGrantsForPrincipal: db.deleteGrantsForPrincipal,+});++router.use(requireJwtAuth, requireAdminAccess);++router.get('/', requireReadGroups, handlers.listGroups);+router.post('/', requireManageGroups, handlers.createGroup);+router.get('/:id', requireReadGroups, handlers.getGroup);+router.patch('/:id', requireManageGroups, handlers.updateGroup);+router.delete('/:id', requireManageGroups, handlers.deleteGroup);+router.get('/:id/members', requireReadGroups, handlers.getGroupMembers);+router.post('/:id/members', requireManageGroups, handlers.addGroupMember);+router.delete('/:id/members/:userId', requireManageGroups, handlers.removeGroupMember);++module.exports = router;diff --git a/api/server/routes/index.js b/api/server/routes/index.jsindex b1f16d5e3c..f9a088649c 100644--- a/api/server/routes/index.js+++ b/api/server/routes/index.js@@ -3,6 +3,7 @@ const assistants = require('./assistants');const categories = require('./categories');const adminAuth = require('./admin/auth');const adminConfig = require('./admin/config');+const adminGroups = require('./admin/groups');const endpoints = require('./endpoints');const staticRoute = require('./static');const messages = require('./messages');@@ -33,6 +34,7 @@ module.exports = {auth,adminAuth,adminConfig,+ adminGroups,keys,apiKeys,user,diff --git a/packages/api/src/admin/groups.spec.ts b/packages/api/src/admin/groups.spec.tsnew file mode 100644index 0000000000..42e32152d9--- /dev/null+++ b/packages/api/src/admin/groups.spec.ts@@ -0,0 +1,1348 @@+import { Types } from 'mongoose';+import { PrincipalType } from 'librechat-data-provider';+import type { IGroup, IUser } from '@librechat/data-schemas';+import type { Response } from 'express';+import type { ServerRequest } from '~/types/http';+import type { AdminGroupsDeps } from './groups';+import { createAdminGroupsHandlers } from './groups';++jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),+ logger: { error: jest.fn(), warn: jest.fn() },+}));++describe('createAdminGroupsHandlers', () => {+ let validId: string;+ let validUserId: string;++ beforeEach(() => {+ validId = new Types.ObjectId().toString();+ validUserId = new Types.ObjectId().toString();+ });++ function mockGroup(overrides: Partial<IGroup> = {}): IGroup {+ return {+ _id: new Types.ObjectId(validId),+ name: 'Test Group',+ source: 'local',+ memberIds: [],+ createdAt: new Date(),+ updatedAt: new Date(),+ ...overrides,+ } as IGroup;+ }++ function mockUser(overrides: Partial<IUser> = {}): IUser {+ return {+ _id: new Types.ObjectId(validUserId),+ name: 'Test User',+ email: '[email protected]',+ avatar: 'https://example.com/avatar.png',+ ...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<AdminGroupsDeps> = {}): AdminGroupsDeps {+ return {+ listGroups: jest.fn().mockResolvedValue([]),+ countGroups: jest.fn().mockResolvedValue(0),+ findGroupById: jest.fn().mockResolvedValue(null),+ createGroup: jest.fn().mockResolvedValue(mockGroup()),+ updateGroupById: jest.fn().mockResolvedValue(mockGroup()),+ deleteGroup: jest.fn().mockResolvedValue(mockGroup()),+ addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),+ removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),+ removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ findUsers: jest.fn().mockResolvedValue([]),+ deleteConfig: jest.fn().mockResolvedValue(null),+ deleteAclEntries: jest.fn().mockResolvedValue({ deletedCount: 0 }),+ deleteGrantsForPrincipal: jest.fn().mockResolvedValue(undefined),+ ...overrides,+ };+ }++ describe('listGroups', () => {+ it('returns groups with total, limit, offset', async () => {+ const groups = [mockGroup()];+ const deps = createDeps({+ listGroups: jest.fn().mockResolvedValue(groups),+ countGroups: jest.fn().mockResolvedValue(1),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ query: {} });++ await handlers.listGroups(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ groups, total: 1, limit: 50, offset: 0 });+ });++ it('passes source and search filters with pagination', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({+ query: { source: 'entra', search: 'engineering', limit: '20', offset: '10' },+ });++ await handlers.listGroups(req, res);++ expect(deps.listGroups).toHaveBeenCalledWith({+ source: 'entra',+ search: 'engineering',+ limit: 20,+ offset: 10,+ });+ expect(deps.countGroups).toHaveBeenCalledWith({+ source: 'entra',+ search: 'engineering',+ });+ });++ it('passes search filter alone', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({ query: { search: 'eng' } });++ await handlers.listGroups(req, res);++ expect(deps.listGroups).toHaveBeenCalledWith({ search: 'eng', limit: 50, offset: 0 });+ expect(deps.countGroups).toHaveBeenCalledWith({ search: 'eng' });+ });++ it('ignores invalid source values', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({ query: { source: 'invalid' } });++ await handlers.listGroups(req, res);++ expect(deps.listGroups).toHaveBeenCalledWith({ limit: 50, offset: 0 });+ expect(deps.countGroups).toHaveBeenCalledWith({});+ });++ it('clamps limit and offset', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({ query: { limit: '999', offset: '-5' } });++ await handlers.listGroups(req, res);++ expect(deps.listGroups).toHaveBeenCalledWith({ limit: 200, offset: 0 });+ });++ it('returns 400 when search exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ query: { search: 'a'.repeat(201) },+ });++ await handlers.listGroups(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'search must not exceed 200 characters' });+ expect(deps.listGroups).not.toHaveBeenCalled();+ });++ it('returns 500 when countGroups fails', async () => {+ const deps = createDeps({+ countGroups: jest.fn().mockRejectedValue(new Error('count failed')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listGroups(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to list groups' });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({ listGroups: jest.fn().mockRejectedValue(new Error('db down')) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes();++ await handlers.listGroups(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to list groups' });+ });+ });++ describe('getGroup', () => {+ it('returns group with 200', async () => {+ const group = mockGroup();+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ group });+ });++ it('returns 400 for invalid ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: 'not-an-id' } });++ await handlers.getGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ expect(deps.findGroupById).not.toHaveBeenCalled();+ });++ it('returns 404 when group not found', async () => {+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(null) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroup(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({+ findGroupById: jest.fn().mockRejectedValue(new Error('db down')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroup(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to get group' });+ });+ });++ describe('createGroup', () => {+ it('creates group and returns 201', async () => {+ const group = mockGroup();+ const deps = createDeps({ createGroup: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'New Group', description: 'A group' },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(json).toHaveBeenCalledWith({ group });+ expect(deps.createGroup).toHaveBeenCalledWith(+ expect.objectContaining({+ name: 'New Group',+ description: 'A group',+ source: 'local',+ memberIds: [],+ }),+ );+ });++ it('normalizes memberIds to idOnTheSource values', async () => {+ const userId = new Types.ObjectId().toString();+ const user = { _id: new Types.ObjectId(userId), idOnTheSource: 'ext-norm-1' } as IUser;+ const group = mockGroup();+ const deps = createDeps({+ createGroup: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([user]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ body: { name: 'With Members', memberIds: [userId] },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(deps.findUsers).toHaveBeenCalledWith({ _id: { $in: [userId] } }, 'idOnTheSource');+ expect(deps.createGroup).toHaveBeenCalledWith(+ expect.objectContaining({ memberIds: ['ext-norm-1'] }),+ );+ });++ it('logs warning when memberIds contain non-existent user ObjectIds', async () => {+ const { logger } = jest.requireMock('@librechat/data-schemas');+ const unknownId = new Types.ObjectId().toString();+ const group = mockGroup();+ const deps = createDeps({+ createGroup: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ body: { name: 'With Unknown', memberIds: [unknownId] },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(logger.warn).toHaveBeenCalledWith(+ '[adminGroups] createGroup: memberIds contain unknown user ObjectIds:',+ [unknownId],+ );+ });++ it('passes idOnTheSource when provided', async () => {+ const group = mockGroup();+ const deps = createDeps({ createGroup: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ body: { name: 'Entra Group', source: 'entra', idOnTheSource: 'ent-abc-123' },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(201);+ expect(deps.createGroup).toHaveBeenCalledWith(+ expect.objectContaining({ idOnTheSource: 'ent-abc-123', source: 'entra' }),+ );+ });++ it('returns 400 for invalid source value', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Bad Source', source: 'azure' },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid source value' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when name exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'a'.repeat(501) },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'name must not exceed 500 characters' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when description exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Valid', description: 'x'.repeat(2001) },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({+ error: 'description must not exceed 2000 characters',+ });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when email exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Valid', email: 'x'.repeat(501) },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'email must not exceed 500 characters' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when avatar exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Valid', avatar: 'x'.repeat(2001) },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'avatar must not exceed 2000 characters' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when idOnTheSource exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Valid', idOnTheSource: 'x'.repeat(501) },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({+ error: 'idOnTheSource must not exceed 500 characters',+ });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when memberIds exceeds cap', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const memberIds = Array.from({ length: 501 }, (_, i) => `ext-${i}`);+ const { req, res, status, json } = createReqRes({+ body: { name: 'Too Many Members', memberIds },+ });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'memberIds must not exceed 500 entries' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('passes non-ObjectId memberIds through unchanged', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ body: { name: 'Ext Group', memberIds: ['ext-1', 'ext-2'] },+ });++ await handlers.createGroup(req, res);++ expect(deps.findUsers).not.toHaveBeenCalled();+ expect(deps.createGroup).toHaveBeenCalledWith(+ expect.objectContaining({ memberIds: ['ext-1', 'ext-2'] }),+ );+ expect(status).toHaveBeenCalledWith(201);+ });++ it('returns 400 when name is missing', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ body: {} });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'name is required' });+ expect(deps.createGroup).not.toHaveBeenCalled();+ });++ it('returns 400 when name is whitespace-only', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ body: { name: ' ' } });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'name is required' });+ });++ it('returns 400 on ValidationError', async () => {+ const validationError = new Error('source must be local or entra');+ validationError.name = 'ValidationError';+ const deps = createDeps({ createGroup: jest.fn().mockRejectedValue(validationError) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ body: { name: 'Test' } });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'source must be local or entra' });+ });++ it('returns 500 on unexpected error', async () => {+ const deps = createDeps({ createGroup: jest.fn().mockRejectedValue(new Error('db crash')) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ body: { name: 'Test' } });++ await handlers.createGroup(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to create group' });+ });+ });++ describe('updateGroup', () => {+ it('updates group and returns 200', async () => {+ const group = mockGroup({ name: 'Updated' });+ const deps = createDeps({+ updateGroupById: jest.fn().mockResolvedValue(group),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: 'Updated' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ group });+ });++ it('updates description only', async () => {+ const group = mockGroup({ description: 'New desc' });+ const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { id: validId },+ body: { description: 'New desc' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateGroupById).toHaveBeenCalledWith(validId, { description: 'New desc' });+ });++ it('updates email only', async () => {+ const group = mockGroup({ email: '[email protected]' });+ const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { id: validId },+ body: { email: '[email protected]' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateGroupById).toHaveBeenCalledWith(validId, { email: '[email protected]' });+ });++ it('updates avatar only', async () => {+ const group = mockGroup({ avatar: 'https://img.co/a.png' });+ const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { id: validId },+ body: { avatar: 'https://img.co/a.png' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateGroupById).toHaveBeenCalledWith(validId, {+ avatar: 'https://img.co/a.png',+ });+ });++ it('updates multiple fields at once', async () => {+ const group = mockGroup({ name: 'New', description: 'Desc', email: '[email protected]' });+ const deps = createDeps({ updateGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { id: validId },+ body: { name: ' New ', description: 'Desc', email: '[email protected]' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.updateGroupById).toHaveBeenCalledWith(validId, {+ name: 'New',+ description: 'Desc',+ email: '[email protected]',+ });+ });++ it('returns 400 for invalid ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: 'bad' },+ body: { name: 'Updated' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ });++ it('returns 400 when name is empty string', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: '' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'name must be a non-empty string' });+ });++ it('returns 400 when name is whitespace-only', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: ' ' },+ });++ await handlers.updateGroup(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 = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: 'a'.repeat(501) },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'name must not exceed 500 characters' });+ expect(deps.updateGroupById).not.toHaveBeenCalled();+ });++ it('returns 400 when description exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { description: 'x'.repeat(2001) },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({+ error: 'description must not exceed 2000 characters',+ });+ expect(deps.updateGroupById).not.toHaveBeenCalled();+ });++ it('returns 400 when email exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { email: 'x'.repeat(501) },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'email must not exceed 500 characters' });+ expect(deps.updateGroupById).not.toHaveBeenCalled();+ });++ it('returns 400 when avatar exceeds max length', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { avatar: 'x'.repeat(2001) },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'avatar must not exceed 2000 characters' });+ expect(deps.updateGroupById).not.toHaveBeenCalled();+ });++ it('returns 400 when no valid fields provided', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: {},+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'No valid fields to update' });+ expect(deps.updateGroupById).not.toHaveBeenCalled();+ });++ it('returns 404 when updateGroupById returns null', async () => {+ const deps = createDeps({+ updateGroupById: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: 'Updated' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 400 on ValidationError', async () => {+ const validationError = new Error('invalid field');+ validationError.name = 'ValidationError';+ const deps = createDeps({+ updateGroupById: jest.fn().mockRejectedValue(validationError),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: 'Updated' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'invalid field' });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({+ updateGroupById: jest.fn().mockRejectedValue(new Error('db down')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { name: 'Updated' },+ });++ await handlers.updateGroup(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to update group' });+ });+ });++ describe('deleteGroup', () => {+ it('deletes group and returns 200 with id', async () => {+ const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(mockGroup()) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.deleteGroup(req, res);++ expect(deps.deleteGroup).toHaveBeenCalledWith(validId);+ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true, id: validId });+ });++ it('returns 400 for invalid ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: 'bad-id' } });++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ });++ it('returns 404 when deleteGroup returns null', async () => {+ const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(null) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ expect(deps.deleteConfig).not.toHaveBeenCalled();+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({+ deleteGroup: jest.fn().mockRejectedValue(new Error('db down')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to delete group' });+ });++ it('returns 200 even when cascade cleanup partially fails', async () => {+ const deps = createDeps({+ deleteGroup: jest.fn().mockResolvedValue(mockGroup()),+ deleteAclEntries: jest.fn().mockRejectedValue(new Error('cleanup failed')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true, id: validId });+ expect(deps.deleteConfig).toHaveBeenCalledWith(PrincipalType.GROUP, validId);+ expect(deps.deleteAclEntries).toHaveBeenCalledWith({+ principalType: PrincipalType.GROUP,+ principalId: new Types.ObjectId(validId),+ });+ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.GROUP, validId);+ });++ it('cleans up Config, AclEntry, and SystemGrant on group delete', async () => {+ const deps = createDeps({ deleteGroup: jest.fn().mockResolvedValue(mockGroup()) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({ params: { id: validId } });++ await handlers.deleteGroup(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(deps.deleteConfig).toHaveBeenCalledWith(PrincipalType.GROUP, validId);+ expect(deps.deleteAclEntries).toHaveBeenCalledWith({+ principalType: PrincipalType.GROUP,+ principalId: new Types.ObjectId(validId),+ });+ expect(deps.deleteGrantsForPrincipal).toHaveBeenCalledWith(PrincipalType.GROUP, validId);+ });+ });++ describe('getGroupMembers', () => {+ it('fetches group with memberIds projection only', async () => {+ const group = mockGroup({ memberIds: [] });+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(deps.findGroupById).toHaveBeenCalledWith(validId, { memberIds: 1 });+ });++ it('returns empty members for group with no memberIds', async () => {+ const group = mockGroup({ memberIds: [] });+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(group) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ members: [], total: 0, limit: 50, offset: 0 });+ expect(deps.findUsers).not.toHaveBeenCalled();+ });++ it('batches member lookup with $or query', async () => {+ const user = mockUser({ idOnTheSource: 'ext-123' });+ const group = mockGroup({ memberIds: [validUserId, 'ext-123'] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([user]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(deps.findUsers).toHaveBeenCalledWith(+ {+ $or: [+ { idOnTheSource: { $in: [validUserId, 'ext-123'] } },+ { _id: { $in: [validUserId] } },+ ],+ },+ 'name email avatar idOnTheSource',+ );+ expect(status).toHaveBeenCalledWith(200);+ const members = json.mock.calls[0][0].members;+ expect(members).toHaveLength(1);+ });++ it('skips _id condition when no valid ObjectIds in memberIds', async () => {+ const group = mockGroup({ memberIds: ['ext-1', 'ext-2'] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(deps.findUsers).toHaveBeenCalledWith(+ { $or: [{ idOnTheSource: { $in: ['ext-1', 'ext-2'] } }] },+ 'name email avatar idOnTheSource',+ );+ });++ it('falls back to memberId when user not found', async () => {+ const group = mockGroup({ memberIds: ['unknown-member'] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(json.mock.calls[0][0].members).toEqual([+ { userId: 'unknown-member', name: 'unknown-member', email: '', avatarUrl: undefined },+ ]);+ });++ it('deduplicates when identical memberId appears twice', async () => {+ const user = mockUser({ idOnTheSource: validUserId });+ const group = mockGroup({ memberIds: [validUserId, validUserId] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([user]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ const result = json.mock.calls[0][0];+ expect(result.members).toHaveLength(1);+ expect(result.total).toBe(1);+ });++ it('deduplicates when objectId and idOnTheSource both present for same user', async () => {+ const extId = 'ext-dedup-123';+ const user = mockUser({ idOnTheSource: extId });+ const group = mockGroup({ memberIds: [validUserId, extId] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([user]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(json.mock.calls[0][0].members).toHaveLength(1);+ });++ it('reports deduplicated total for duplicate memberIds', async () => {+ const group = mockGroup({ memberIds: ['m1', 'm2', 'm1', 'm3', 'm2'] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ const result = json.mock.calls[0][0];+ expect(result.total).toBe(3);+ expect(result.members).toHaveLength(3);+ });++ it('paginates members with limit and offset', async () => {+ const ids = ['m1', 'm2', 'm3', 'm4', 'm5'];+ const group = mockGroup({ memberIds: ids });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({+ params: { id: validId },+ query: { limit: '2', offset: '1' },+ });++ await handlers.getGroupMembers(req, res);++ const result = json.mock.calls[0][0];+ expect(result.total).toBe(5);+ expect(result.limit).toBe(2);+ expect(result.offset).toBe(1);+ expect(result.members).toHaveLength(2);+ expect(result.members[0].userId).toBe('m2');+ expect(result.members[1].userId).toBe('m3');+ });++ it('caps limit at 200', async () => {+ const ids = Array.from({ length: 5 }, (_, i) => `m${i}`);+ const group = mockGroup({ memberIds: ids });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ findUsers: jest.fn().mockResolvedValue([]),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({+ params: { id: validId },+ query: { limit: '999' },+ });++ await handlers.getGroupMembers(req, res);++ const result = json.mock.calls[0][0];+ expect(result.limit).toBe(200);+ });++ it('returns empty when offset exceeds total', async () => {+ const group = mockGroup({ memberIds: ['m1', 'm2'] });+ const deps = createDeps({+ findGroupById: jest.fn().mockResolvedValue(group),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, json } = createReqRes({+ params: { id: validId },+ query: { offset: '10' },+ });++ await handlers.getGroupMembers(req, res);++ const result = json.mock.calls[0][0];+ expect(result.members).toHaveLength(0);+ expect(result.total).toBe(2);+ expect(deps.findUsers).not.toHaveBeenCalled();+ });++ it('returns 400 for invalid group ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: 'nope' } });++ await handlers.getGroupMembers(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ });++ it('returns 404 when group not found', async () => {+ const deps = createDeps({ findGroupById: jest.fn().mockResolvedValue(null) });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 500 on error', async () => {+ const deps = createDeps({+ findGroupById: jest.fn().mockRejectedValue(new Error('db down')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({ params: { id: validId } });++ await handlers.getGroupMembers(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to get group members' });+ });+ });++ describe('addGroupMember', () => {+ it('adds member and returns 200', async () => {+ const group = mockGroup();+ const deps = createDeps({+ addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(deps.addUserToGroup).toHaveBeenCalledWith(validUserId, validId);+ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ group });+ });++ it('returns 400 for invalid group ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: 'bad' },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ });++ it('returns 400 when userId is missing', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: {},+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'userId is required' });+ });++ it('returns 400 for non-ObjectId userId', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { userId: 'not-valid' },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({+ error: 'Only native user ObjectIds can be added via this endpoint',+ });+ });++ it('returns 404 when addUserToGroup returns null group', async () => {+ const deps = createDeps({+ addUserToGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: null }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 404 for "User not found" error', async () => {+ const deps = createDeps({+ addUserToGroup: jest.fn().mockRejectedValue(new Error('User not found')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'User not found' });+ });++ it('returns 500 for unrelated errors', async () => {+ const deps = createDeps({+ addUserToGroup: jest.fn().mockRejectedValue(new Error('connection lost')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to add member' });+ });++ it('does not misclassify errors containing "not found" substring', async () => {+ const deps = createDeps({+ addUserToGroup: jest.fn().mockRejectedValue(new Error('Permission not found in config')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status } = createReqRes({+ params: { id: validId },+ body: { userId: validUserId },+ });++ await handlers.addGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(500);+ });+ });++ describe('removeGroupMember', () => {+ it('removes member and returns 200', async () => {+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: mockGroup() }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(deps.removeUserFromGroup).toHaveBeenCalledWith(validUserId, validId);+ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true });+ });++ it('returns 400 for invalid group ID', async () => {+ const deps = createDeps();+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: 'bad', userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(400);+ expect(json).toHaveBeenCalledWith({ error: 'Invalid group ID format' });+ });++ it('removes non-ObjectId member via removeMemberById', async () => {+ const deps = createDeps({+ removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: 'ent-abc-123' },+ });++ await handlers.removeGroupMember(req, res);++ expect(deps.removeMemberById).toHaveBeenCalledWith(validId, 'ent-abc-123');+ expect(deps.removeUserFromGroup).not.toHaveBeenCalled();+ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true });+ });++ it('returns 404 when removeMemberById returns null', async () => {+ const deps = createDeps({+ removeMemberById: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: 'ent-abc-123' },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('falls back to removeMemberById when ObjectId userId not found as user', async () => {+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockRejectedValue(new Error('User not found')),+ removeMemberById: jest.fn().mockResolvedValue(mockGroup()),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(deps.removeUserFromGroup).toHaveBeenCalledWith(validUserId, validId);+ expect(deps.removeMemberById).toHaveBeenCalledWith(validId, validUserId);+ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true });+ });++ it('returns 404 when removeUserFromGroup returns null group', async () => {+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group: null }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 404 when fallback removeMemberById also returns null', async () => {+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockRejectedValue(new Error('User not found')),+ removeMemberById: jest.fn().mockResolvedValue(null),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(404);+ expect(json).toHaveBeenCalledWith({ error: 'Group not found' });+ });++ it('returns 500 for unrelated errors', async () => {+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockRejectedValue(new Error('timeout')),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(500);+ expect(json).toHaveBeenCalledWith({ error: 'Failed to remove member' });+ });++ it('returns 200 when removing ObjectId member not in group (idempotent delete)', async () => {+ const group = mockGroup({ memberIds: [] });+ const deps = createDeps({+ removeUserFromGroup: jest.fn().mockResolvedValue({ user: mockUser(), group }),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: validUserId },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true });+ });++ it('returns 200 when removing non-ObjectId member not in group (idempotent delete)', async () => {+ const group = mockGroup({ memberIds: [] });+ const deps = createDeps({+ removeMemberById: jest.fn().mockResolvedValue(group),+ });+ const handlers = createAdminGroupsHandlers(deps);+ const { req, res, status, json } = createReqRes({+ params: { id: validId, userId: 'ext-not-in-group' },+ });++ await handlers.removeGroupMember(req, res);++ expect(status).toHaveBeenCalledWith(200);+ expect(json).toHaveBeenCalledWith({ success: true });+ });+ });+});diff --git a/packages/api/src/admin/groups.ts b/packages/api/src/admin/groups.tsnew file mode 100644index 0000000000..58ff4d9782--- /dev/null+++ b/packages/api/src/admin/groups.ts@@ -0,0 +1,482 @@+import { Types } from 'mongoose';+import { PrincipalType } from 'librechat-data-provider';+import { logger, isValidObjectIdString } from '@librechat/data-schemas';+import type {+ IGroup,+ IUser,+ IConfig,+ CreateGroupRequest,+ UpdateGroupRequest,+ GroupFilterOptions,+} from '@librechat/data-schemas';+import type { FilterQuery, ClientSession, DeleteResult } from 'mongoose';+import type { Response } from 'express';+import type { ValidationError } from '~/types/error';+import type { ServerRequest } from '~/types/http';++type GroupListFilter = Pick<GroupFilterOptions, 'source' | 'search'>;++const VALID_GROUP_SOURCES: ReadonlySet<string> = new Set(['local', 'entra']);+const MAX_CREATE_MEMBER_IDS = 500;+const MAX_SEARCH_LENGTH = 200;+const MAX_NAME_LENGTH = 500;+const MAX_DESCRIPTION_LENGTH = 2000;+const MAX_EMAIL_LENGTH = 500;+const MAX_AVATAR_LENGTH = 2000;+const MAX_EXTERNAL_ID_LENGTH = 500;++interface GroupIdParams {+ id: string;+}++interface GroupMemberParams extends GroupIdParams {+ userId: string;+}++export interface AdminGroupsDeps {+ listGroups: (+ filter?: GroupListFilter & { limit?: number; offset?: number },+ session?: ClientSession,+ ) => Promise<IGroup[]>;+ countGroups: (filter?: GroupListFilter, session?: ClientSession) => Promise<number>;+ findGroupById: (+ groupId: string | Types.ObjectId,+ projection?: Record<string, 0 | 1>,+ session?: ClientSession,+ ) => Promise<IGroup | null>;+ createGroup: (groupData: Partial<IGroup>, session?: ClientSession) => Promise<IGroup>;+ updateGroupById: (+ groupId: string | Types.ObjectId,+ data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,+ session?: ClientSession,+ ) => Promise<IGroup | null>;+ deleteGroup: (+ groupId: string | Types.ObjectId,+ session?: ClientSession,+ ) => Promise<IGroup | null>;+ addUserToGroup: (+ userId: string | Types.ObjectId,+ groupId: string | Types.ObjectId,+ session?: ClientSession,+ ) => Promise<{ user: IUser; group: IGroup | null }>;+ removeUserFromGroup: (+ userId: string | Types.ObjectId,+ groupId: string | Types.ObjectId,+ session?: ClientSession,+ ) => Promise<{ user: IUser; group: IGroup | null }>;+ removeMemberById: (+ groupId: string | Types.ObjectId,+ memberId: string,+ session?: ClientSession,+ ) => Promise<IGroup | null>;+ findUsers: (+ searchCriteria: FilterQuery<IUser>,+ fieldsToSelect?: string | string[] | null,+ ) => Promise<IUser[]>;+ deleteConfig: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ ) => Promise<IConfig | null>;+ deleteAclEntries: (filter: {+ principalType: PrincipalType;+ principalId: string | Types.ObjectId;+ }) => Promise<DeleteResult>;+ deleteGrantsForPrincipal: (+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ ) => Promise<void>;+}++export function createAdminGroupsHandlers(deps: AdminGroupsDeps) {+ const {+ listGroups,+ countGroups,+ findGroupById,+ createGroup,+ updateGroupById,+ deleteGroup,+ addUserToGroup,+ removeUserFromGroup,+ removeMemberById,+ findUsers,+ deleteConfig,+ deleteAclEntries,+ deleteGrantsForPrincipal,+ } = deps;++ async function listGroupsHandler(req: ServerRequest, res: Response) {+ try {+ const { search, source } = req.query as { search?: string; source?: string };+ const filter: GroupListFilter = {};+ if (source && VALID_GROUP_SOURCES.has(source)) {+ filter.source = source as IGroup['source'];+ }+ if (search && search.length > MAX_SEARCH_LENGTH) {+ return res+ .status(400)+ .json({ error: `search must not exceed ${MAX_SEARCH_LENGTH} characters` });+ }+ 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 [groups, total] = await Promise.all([+ listGroups({ ...filter, limit, offset }),+ countGroups(filter),+ ]);+ return res.status(200).json({ groups, total, limit, offset });+ } catch (error) {+ logger.error('[adminGroups] listGroups error:', error);+ return res.status(500).json({ error: 'Failed to list groups' });+ }+ }++ async function getGroupHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as GroupIdParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }+ const group = await findGroupById(id);+ if (!group) {+ return res.status(404).json({ error: 'Group not found' });+ }+ return res.status(200).json({ group });+ } catch (error) {+ logger.error('[adminGroups] getGroup error:', error);+ return res.status(500).json({ error: 'Failed to get group' });+ }+ }++ async function createGroupHandler(req: ServerRequest, res: Response) {+ try {+ const body = req.body as CreateGroupRequest;+ if (!body.name || typeof body.name !== 'string' || !body.name.trim()) {+ return res.status(400).json({ error: 'name is required' });+ }+ if (body.name.trim().length > MAX_NAME_LENGTH) {+ return res+ .status(400)+ .json({ error: `name must not exceed ${MAX_NAME_LENGTH} characters` });+ }+ if (body.source && !VALID_GROUP_SOURCES.has(body.source)) {+ return res.status(400).json({ error: 'Invalid source value' });+ }+ if (body.description && body.description.length > MAX_DESCRIPTION_LENGTH) {+ return res+ .status(400)+ .json({ error: `description must not exceed ${MAX_DESCRIPTION_LENGTH} characters` });+ }+ if (body.email && body.email.length > MAX_EMAIL_LENGTH) {+ return res+ .status(400)+ .json({ error: `email must not exceed ${MAX_EMAIL_LENGTH} characters` });+ }+ if (body.avatar && body.avatar.length > MAX_AVATAR_LENGTH) {+ return res+ .status(400)+ .json({ error: `avatar must not exceed ${MAX_AVATAR_LENGTH} characters` });+ }+ if (body.idOnTheSource && body.idOnTheSource.length > MAX_EXTERNAL_ID_LENGTH) {+ return res+ .status(400)+ .json({ error: `idOnTheSource must not exceed ${MAX_EXTERNAL_ID_LENGTH} characters` });+ }++ const rawIds = Array.isArray(body.memberIds) ? body.memberIds : [];+ if (rawIds.length > MAX_CREATE_MEMBER_IDS) {+ return res+ .status(400)+ .json({ error: `memberIds must not exceed ${MAX_CREATE_MEMBER_IDS} entries` });+ }+ let memberIds = rawIds;+ const objectIds = rawIds.filter(isValidObjectIdString);+ if (objectIds.length > 0) {+ const users = await findUsers({ _id: { $in: objectIds } }, 'idOnTheSource');+ const idMap = new Map<string, string>();+ for (const user of users) {+ const uid = user._id?.toString() ?? '';+ idMap.set(uid, user.idOnTheSource || uid);+ }+ const unmapped = objectIds.filter((oid) => !idMap.has(oid));+ if (unmapped.length > 0) {+ logger.warn(+ '[adminGroups] createGroup: memberIds contain unknown user ObjectIds:',+ unmapped,+ );+ }+ memberIds = rawIds.map((id) => idMap.get(id) || id);+ }++ const group = await createGroup({+ name: body.name.trim(),+ description: body.description,+ email: body.email,+ avatar: body.avatar,+ source: body.source || 'local',+ memberIds,+ ...(body.idOnTheSource ? { idOnTheSource: body.idOnTheSource } : {}),+ });+ return res.status(201).json({ group });+ } catch (error) {+ if ((error as ValidationError).name === 'ValidationError') {+ return res.status(400).json({ error: (error as ValidationError).message });+ }+ logger.error('[adminGroups] createGroup error:', error);+ return res.status(500).json({ error: 'Failed to create group' });+ }+ }++ async function updateGroupHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as GroupIdParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }+ const body = req.body as UpdateGroupRequest;++ if (+ body.name !== undefined &&+ (!body.name || typeof body.name !== 'string' || !body.name.trim())+ ) {+ return res.status(400).json({ error: 'name must be a non-empty string' });+ }+ if (body.name !== undefined && body.name.trim().length > MAX_NAME_LENGTH) {+ return res+ .status(400)+ .json({ error: `name must not exceed ${MAX_NAME_LENGTH} characters` });+ }+ if (body.description !== undefined && body.description.length > MAX_DESCRIPTION_LENGTH) {+ return res+ .status(400)+ .json({ error: `description must not exceed ${MAX_DESCRIPTION_LENGTH} characters` });+ }+ if (body.email !== undefined && body.email.length > MAX_EMAIL_LENGTH) {+ return res+ .status(400)+ .json({ error: `email must not exceed ${MAX_EMAIL_LENGTH} characters` });+ }+ if (body.avatar !== undefined && body.avatar.length > MAX_AVATAR_LENGTH) {+ return res+ .status(400)+ .json({ error: `avatar must not exceed ${MAX_AVATAR_LENGTH} characters` });+ }++ const updateData: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>> = {};+ if (body.name !== undefined) {+ updateData.name = body.name.trim();+ }+ if (body.description !== undefined) {+ updateData.description = body.description;+ }+ if (body.email !== undefined) {+ updateData.email = body.email;+ }+ if (body.avatar !== undefined) {+ updateData.avatar = body.avatar;+ }++ if (Object.keys(updateData).length === 0) {+ return res.status(400).json({ error: 'No valid fields to update' });+ }++ const group = await updateGroupById(id, updateData);+ if (!group) {+ return res.status(404).json({ error: 'Group not found' });+ }+ return res.status(200).json({ group });+ } catch (error) {+ if ((error as ValidationError).name === 'ValidationError') {+ return res.status(400).json({ error: (error as ValidationError).message });+ }+ logger.error('[adminGroups] updateGroup error:', error);+ return res.status(500).json({ error: 'Failed to update group' });+ }+ }++ async function deleteGroupHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as GroupIdParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }+ const deleted = await deleteGroup(id);+ if (!deleted) {+ return res.status(404).json({ error: 'Group not found' });+ }+ /**+ * deleteAclEntries is a raw deleteMany wrapper with no type casting.+ * grantPermission stores group principalId as ObjectId, so we must+ * cast here. deleteConfig and deleteGrantsForPrincipal normalize internally.+ */+ const cleanupResults = await Promise.allSettled([+ deleteConfig(PrincipalType.GROUP, id),+ deleteAclEntries({+ principalType: PrincipalType.GROUP,+ principalId: new Types.ObjectId(id),+ }),+ deleteGrantsForPrincipal(PrincipalType.GROUP, id),+ ]);+ for (const result of cleanupResults) {+ if (result.status === 'rejected') {+ logger.error('[adminGroups] cascade cleanup step failed for group:', id, result.reason);+ }+ }+ return res.status(200).json({ success: true, id });+ } catch (error) {+ logger.error('[adminGroups] deleteGroup error:', error);+ return res.status(500).json({ error: 'Failed to delete group' });+ }+ }++ async function getGroupMembersHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as GroupIdParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }+ const group = await findGroupById(id, { memberIds: 1 });+ if (!group) {+ return res.status(404).json({ error: 'Group not found' });+ }++ /**+ * `total` counts unique raw memberId strings. After user resolution, two+ * distinct strings may map to the same user, so `members.length` can be+ * less than the page size. Write paths prevent this for well-formed data.+ */+ 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);++ if (total === 0 || offset >= total) {+ return res.status(200).json({ members: [], total, limit, offset });+ }++ const memberIds = allMemberIds.slice(offset, offset + limit);++ const validObjectIds = memberIds.filter(isValidObjectIdString);+ const conditions: FilterQuery<IUser>[] = [{ idOnTheSource: { $in: memberIds } }];+ if (validObjectIds.length > 0) {+ conditions.push({ _id: { $in: validObjectIds } });+ }+ const users = await findUsers({ $or: conditions }, 'name email avatar idOnTheSource');++ const userMap = new Map<string, IUser>();+ for (const user of users) {+ if (user.idOnTheSource) {+ userMap.set(user.idOnTheSource, user);+ }+ if (user._id) {+ userMap.set(user._id.toString(), user);+ }+ }++ const seen = new Set<string>();+ const members: { userId: string; name: string; email: string; avatarUrl?: string }[] = [];+ for (const memberId of memberIds) {+ const user = userMap.get(memberId);+ const userId = user?._id?.toString() ?? memberId;+ if (seen.has(userId)) {+ continue;+ }+ seen.add(userId);+ members.push({+ userId,+ name: user?.name ?? memberId,+ email: user?.email ?? '',+ avatarUrl: user?.avatar,+ });+ }++ return res.status(200).json({ members, total, limit, offset });+ } catch (error) {+ logger.error('[adminGroups] getGroupMembers error:', error);+ return res.status(500).json({ error: 'Failed to get group members' });+ }+ }++ async function addGroupMemberHandler(req: ServerRequest, res: Response) {+ try {+ const { id } = req.params as GroupIdParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }+ 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: 'Only native user ObjectIds can be added via this endpoint' });+ }++ const { group } = await addUserToGroup(userId, id);+ if (!group) {+ return res.status(404).json({ error: 'Group not found' });+ }+ return res.status(200).json({ group });+ } catch (error) {+ const message = error instanceof Error ? error.message : '';+ const isNotFound = message === 'User not found' || message.startsWith('User not found:');+ if (isNotFound) {+ return res.status(404).json({ error: 'User not found' });+ }+ logger.error('[adminGroups] addGroupMember error:', error);+ return res.status(500).json({ error: 'Failed to add member' });+ }+ }++ /**+ * Attempt removal of an ObjectId-format member: first via removeUserFromGroup+ * (which resolves the user), falling back to a raw $pull if the user record+ * no longer exists. Returns null only when the group itself is not found.+ */+ async function removeObjectIdMember(groupId: string, userId: string): Promise<IGroup | null> {+ try {+ const { group } = await removeUserFromGroup(userId, groupId);+ return group;+ } catch (err) {+ const msg = err instanceof Error ? err.message : '';+ if (msg === 'User not found' || msg.startsWith('User not found:')) {+ return removeMemberById(groupId, userId);+ }+ throw err;+ }+ }++ async function removeGroupMemberHandler(req: ServerRequest, res: Response) {+ try {+ const { id, userId } = req.params as GroupMemberParams;+ if (!isValidObjectIdString(id)) {+ return res.status(400).json({ error: 'Invalid group ID format' });+ }++ const group = isValidObjectIdString(userId)+ ? await removeObjectIdMember(id, userId)+ : await removeMemberById(id, userId);++ if (!group) {+ return res.status(404).json({ error: 'Group not found' });+ }+ return res.status(200).json({ success: true });+ } catch (error) {+ logger.error('[adminGroups] removeGroupMember error:', error);+ return res.status(500).json({ error: 'Failed to remove member' });+ }+ }++ return {+ listGroups: listGroupsHandler,+ getGroup: getGroupHandler,+ createGroup: createGroupHandler,+ updateGroup: updateGroupHandler,+ deleteGroup: deleteGroupHandler,+ getGroupMembers: getGroupMembersHandler,+ addGroupMember: addGroupMemberHandler,+ removeGroupMember: removeGroupMemberHandler,+ };+}diff --git a/packages/api/src/admin/index.ts b/packages/api/src/admin/index.tsindex bf48ce7345..d833c7e2b0 100644--- a/packages/api/src/admin/index.ts+++ b/packages/api/src/admin/index.ts@@ -1,2 +1,4 @@export { createAdminConfigHandlers } from './config';+export { createAdminGroupsHandlers } from './groups';export type { AdminConfigDeps } from './config';+export type { AdminGroupsDeps } from './groups';diff --git a/packages/data-schemas/src/methods/systemGrant.spec.ts b/packages/data-schemas/src/methods/systemGrant.spec.tsindex b17285c761..49b4f7269e 100644--- a/packages/data-schemas/src/methods/systemGrant.spec.ts+++ b/packages/data-schemas/src/methods/systemGrant.spec.ts@@ -702,6 +702,68 @@ describe('systemGrant methods', () => {});});+ describe('deleteGrantsForPrincipal', () => {+ it('deletes all grants for a principal', async () => {+ const groupId = new Types.ObjectId();++ await methods.grantCapability({+ principalType: PrincipalType.GROUP,+ principalId: groupId,+ capability: SystemCapabilities.READ_USERS,+ });+ await methods.grantCapability({+ principalType: PrincipalType.GROUP,+ principalId: groupId,+ capability: SystemCapabilities.READ_CONFIGS,+ });++ await methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupId);++ const remaining = await SystemGrant.countDocuments({+ principalType: PrincipalType.GROUP,+ principalId: groupId,+ });+ expect(remaining).toBe(0);+ });++ it('is a no-op for principal with no grants', async () => {+ const groupId = new Types.ObjectId();++ await expect(+ methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupId),+ ).resolves.not.toThrow();+ });++ it('does not affect other principals', async () => {+ const groupA = new Types.ObjectId();+ const groupB = new Types.ObjectId();++ await methods.grantCapability({+ principalType: PrincipalType.GROUP,+ principalId: groupA,+ capability: SystemCapabilities.READ_USERS,+ });+ await methods.grantCapability({+ principalType: PrincipalType.GROUP,+ principalId: groupB,+ capability: SystemCapabilities.READ_USERS,+ });++ await methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupA);++ const remainingA = await SystemGrant.countDocuments({+ principalType: PrincipalType.GROUP,+ principalId: groupA,+ });+ const remainingB = await SystemGrant.countDocuments({+ principalType: PrincipalType.GROUP,+ principalId: groupB,+ });+ expect(remainingA).toBe(0);+ expect(remainingB).toBe(1);+ });+ });+describe('schema validation', () => {it('rejects null tenantId at the schema level', async () => {await expect(diff --git a/packages/data-schemas/src/methods/systemGrant.ts b/packages/data-schemas/src/methods/systemGrant.tsindex 6071dd38c5..4954f50c16 100644--- a/packages/data-schemas/src/methods/systemGrant.ts+++ b/packages/data-schemas/src/methods/systemGrant.ts@@ -246,12 +246,28 @@ export function createSystemGrantMethods(mongoose: typeof import('mongoose')) {}}+ /**+ * Delete all system grants for a principal.+ * Used for cascade cleanup when a principal (group, role) is deleted.+ */+ async function deleteGrantsForPrincipal(+ principalType: PrincipalType,+ principalId: string | Types.ObjectId,+ session?: ClientSession,+ ): Promise<void> {+ const SystemGrant = mongoose.models.SystemGrant as Model<ISystemGrant>;+ const normalizedPrincipalId = normalizePrincipalId(principalId, principalType);+ const options = session ? { session } : {};+ await SystemGrant.deleteMany({ principalType, principalId: normalizedPrincipalId }, options);+ }+return {grantCapability,seedSystemGrants,revokeCapability,hasCapabilityForPrincipals,getCapabilitiesForPrincipal,+ deleteGrantsForPrincipal,};}diff --git a/packages/data-schemas/src/methods/user.ts b/packages/data-schemas/src/methods/user.tsindex 74cb4a1e1c..137c01d0cd 100644--- a/packages/data-schemas/src/methods/user.ts+++ b/packages/data-schemas/src/methods/user.ts@@ -44,6 +44,19 @@ export function createUserMethods(mongoose: typeof import('mongoose')) {return (await query.lean()) as IUser | null;}+ async function findUsers(+ searchCriteria: FilterQuery<IUser>,+ fieldsToSelect?: string | string[] | null,+ ): Promise<IUser[]> {+ const User = mongoose.models.User;+ const normalizedCriteria = normalizeEmailInCriteria(searchCriteria);+ const query = User.find(normalizedCriteria);+ if (fieldsToSelect) {+ query.select(fieldsToSelect);+ }+ return (await query.lean()) as IUser[];+ }+/*** Count the number of user documents in the collection based on the provided filter.*/@@ -323,6 +336,7 @@ export function createUserMethods(mongoose: typeof import('mongoose')) {return {findUser,+ findUsers,countUsers,createUser,updateUser,diff --git a/packages/data-schemas/src/methods/userGroup.methods.spec.ts b/packages/data-schemas/src/methods/userGroup.methods.spec.tsindex 8a31544018..51848de091 100644--- a/packages/data-schemas/src/methods/userGroup.methods.spec.ts+++ b/packages/data-schemas/src/methods/userGroup.methods.spec.ts@@ -600,6 +600,155 @@ describe('UserGroup Methods - Detailed Tests', () => {});});+ describe('listGroups', () => {+ beforeEach(async () => {+ await Group.create([+ { name: 'Beta', source: 'local', memberIds: [], email: '[email protected]' },+ { name: 'Alpha', source: 'local', memberIds: [], description: 'first group' },+ { name: 'Gamma', source: 'entra', idOnTheSource: 'ext-g', memberIds: [] },+ ]);+ });++ test('returns groups sorted by name', async () => {+ const groups = await methods.listGroups();++ expect(groups).toHaveLength(3);+ expect(groups[0].name).toBe('Alpha');+ expect(groups[1].name).toBe('Beta');+ expect(groups[2].name).toBe('Gamma');+ });++ test('filters by source', async () => {+ const groups = await methods.listGroups({ source: 'entra' });++ expect(groups).toHaveLength(1);+ expect(groups[0].name).toBe('Gamma');+ });++ test('filters by search (name)', async () => {+ const groups = await methods.listGroups({ search: 'alpha' });++ expect(groups).toHaveLength(1);+ expect(groups[0].name).toBe('Alpha');+ });++ test('filters by search (email)', async () => {+ const groups = await methods.listGroups({ search: 'beta@test' });++ expect(groups).toHaveLength(1);+ expect(groups[0].name).toBe('Beta');+ });++ test('filters by search (description)', async () => {+ const groups = await methods.listGroups({ search: 'first group' });++ expect(groups).toHaveLength(1);+ expect(groups[0].name).toBe('Alpha');+ });++ test('respects limit and offset', async () => {+ const groups = await methods.listGroups({ limit: 1, offset: 1 });++ expect(groups).toHaveLength(1);+ expect(groups[0].name).toBe('Beta');+ });++ test('returns empty for no matches', async () => {+ const groups = await methods.listGroups({ search: 'nonexistent' });++ expect(groups).toHaveLength(0);+ });+ });++ describe('countGroups', () => {+ beforeEach(async () => {+ await Group.create([+ { name: 'A', source: 'local', memberIds: [] },+ { name: 'B', source: 'local', memberIds: [] },+ { name: 'C', source: 'entra', idOnTheSource: 'ext-c', memberIds: [] },+ ]);+ });++ test('returns total count', async () => {+ const count = await methods.countGroups();++ expect(count).toBe(3);+ });++ test('respects source filter', async () => {+ const count = await methods.countGroups({ source: 'local' });++ expect(count).toBe(2);+ });++ test('respects search filter', async () => {+ const count = await methods.countGroups({ search: 'A' });++ expect(count).toBe(1);+ });+ });++ describe('deleteGroup', () => {+ test('returns deleted group', async () => {+ const group = await Group.create({ name: 'ToDelete', source: 'local', memberIds: [] });++ const deleted = await methods.deleteGroup(group._id as mongoose.Types.ObjectId);++ expect(deleted).toBeDefined();+ expect(deleted?.name).toBe('ToDelete');+ const remaining = await Group.findById(group._id);+ expect(remaining).toBeNull();+ });++ test('returns null for non-existent ID', async () => {+ const fakeId = new mongoose.Types.ObjectId();+ const result = await methods.deleteGroup(fakeId);++ expect(result).toBeNull();+ });+ });++ describe('removeMemberById', () => {+ test('removes member from memberIds array', async () => {+ const group = await Group.create({+ name: 'Test',+ source: 'local',+ memberIds: ['m1', 'm2', 'm3'],+ });++ const updated = await methods.removeMemberById(+ group._id as mongoose.Types.ObjectId,+ 'm2',+ );++ expect(updated).toBeDefined();+ expect(updated?.memberIds).toEqual(['m1', 'm3']);+ });++ test('is idempotent when memberId not present', async () => {+ const group = await Group.create({+ name: 'Test',+ source: 'local',+ memberIds: ['m1'],+ });++ const updated = await methods.removeMemberById(+ group._id as mongoose.Types.ObjectId,+ 'nonexistent',+ );++ expect(updated).toBeDefined();+ expect(updated?.memberIds).toEqual(['m1']);+ });++ test('returns null for non-existent group', async () => {+ const fakeId = new mongoose.Types.ObjectId();+ const result = await methods.removeMemberById(fakeId, 'any-id');++ expect(result).toBeNull();+ });+ });+describe('sortPrincipalsByRelevance', () => {test('should sort principals by relevance score', async () => {const principals = [diff --git a/packages/data-schemas/src/methods/userGroup.ts b/packages/data-schemas/src/methods/userGroup.tsindex a41358337c..948542e6de 100644--- a/packages/data-schemas/src/methods/userGroup.ts+++ b/packages/data-schemas/src/methods/userGroup.ts@@ -1,8 +1,9 @@import { Types } from 'mongoose';import { PrincipalType } from 'librechat-data-provider';import type { TUser, TPrincipalSearchResult } from 'librechat-data-provider';-import type { Model, ClientSession } from 'mongoose';+import type { Model, ClientSession, FilterQuery } from 'mongoose';import type { IGroup, IRole, IUser } from '~/types';+import { escapeRegExp } from '~/utils/string';export function createUserGroupMethods(mongoose: typeof import('mongoose')) {/**@@ -14,7 +15,7 @@ export function createUserGroupMethods(mongoose: typeof import('mongoose')) {*/async function findGroupById(groupId: string | Types.ObjectId,- projection: Record<string, unknown> = {},+ projection: Record<string, 0 | 1> = {},session?: ClientSession,): Promise<IGroup | null> {const Group = mongoose.models.Group as Model<IGroup>;@@ -36,7 +37,7 @@ export function createUserGroupMethods(mongoose: typeof import('mongoose')) {async function findGroupByExternalId(idOnTheSource: string,source: 'entra' | 'local' = 'entra',- projection: Record<string, unknown> = {},+ projection: Record<string, 0 | 1> = {},session?: ClientSession,): Promise<IGroup | null> {const Group = mongoose.models.Group as Model<IGroup>;@@ -658,6 +659,97 @@ export function createUserGroupMethods(mongoose: typeof import('mongoose')) {return Group.updateMany(filter, update, options || {});}+ function buildGroupQuery(filter: {+ source?: 'local' | 'entra';+ search?: string;+ }): FilterQuery<IGroup> {+ const query: FilterQuery<IGroup> = {};+ if (filter.source) {+ query.source = filter.source;+ }+ if (filter.search) {+ const regex = new RegExp(escapeRegExp(filter.search), 'i');+ query.$or = [{ name: regex }, { email: regex }, { description: regex }];+ }+ return query;+ }++ /**+ * List groups with optional source, search, and pagination filters.+ * Results are sorted by name.+ * @param filter - Optional filter with source, search, limit, and offset fields+ * @param session - Optional MongoDB session for transactions+ */+ async function listGroups(+ filter: {+ source?: 'local' | 'entra';+ search?: string;+ limit?: number;+ offset?: number;+ } = {},+ session?: ClientSession,+ ): Promise<IGroup[]> {+ const Group = mongoose.models.Group as Model<IGroup>;+ const query = buildGroupQuery(filter);+ const limit = filter.limit ?? 50;+ const offset = filter.offset ?? 0;+ return await Group.find(query)+ .sort({ name: 1 })+ .skip(offset)+ .limit(limit)+ .session(session ?? null)+ .lean();+ }++ /**+ * Count groups matching optional source and search filters.+ * @param filter - Optional filter with source and search fields+ * @param session - Optional MongoDB session for transactions+ */+ async function countGroups(+ filter: { source?: 'local' | 'entra'; search?: string } = {},+ session?: ClientSession,+ ): Promise<number> {+ const Group = mongoose.models.Group as Model<IGroup>;+ const query = buildGroupQuery(filter);+ return await Group.countDocuments(query).session(session ?? null);+ }++ /**+ * Delete a group by its ID.+ * @param groupId - The group's ObjectId+ * @param session - Optional MongoDB session for transactions+ */+ async function deleteGroup(+ groupId: string | Types.ObjectId,+ session?: ClientSession,+ ): Promise<IGroup | null> {+ const Group = mongoose.models.Group as Model<IGroup>;+ const options = session ? { session } : {};+ return await Group.findByIdAndDelete(groupId, options).lean();+ }++ /**+ * Remove a member from a group by raw memberId string ($pull from memberIds).+ * Unlike removeUserFromGroup, this does not look up the user first.+ * @param groupId - The group's ObjectId+ * @param memberId - The raw memberId string to remove (ObjectId or idOnTheSource)+ * @param session - Optional MongoDB session for transactions+ */+ async function removeMemberById(+ groupId: string | Types.ObjectId,+ memberId: string,+ session?: ClientSession,+ ): Promise<IGroup | null> {+ const Group = mongoose.models.Group as Model<IGroup>;+ const options = { new: true, ...(session ? { session } : {}) };+ return await Group.findByIdAndUpdate(+ groupId,+ { $pull: { memberIds: memberId } },+ options,+ ).lean();+ }+return {findGroupById,findGroupByExternalId,@@ -677,6 +769,10 @@ export function createUserGroupMethods(mongoose: typeof import('mongoose')) {searchPrincipals,calculateRelevanceScore,sortPrincipalsByRelevance,+ listGroups,+ countGroups,+ deleteGroup,+ removeMemberById,};}