import { Types } from 'mongoose'; import { PrincipalType } from 'librechat-data-provider'; import { logger, isValidObjectIdString } from '@librechat/data-schemas'; import type { IGroup, IUser, ConfigRecord, 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'; import type { RecordAuditEntry } from './audit'; import { cascadeStep, runCascade, invalidatingConfigStore } from './cascade'; import { getSafeErrorMetadata } from '~/utils/errors'; import { createAdminAuditEmitter } from './audit'; import { parsePagination } from './pagination'; type GroupListFilter = Pick; const VALID_GROUP_SOURCES: ReadonlySet = new Set(['local', 'entra']); const MAX_CREATE_MEMBER_IDS = 500; /** Member ids per audit entry, so group creation writes a few ordered entries. */ const AUDIT_MEMBER_CHUNK = 100; 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; countGroups: (filter?: GroupListFilter, session?: ClientSession) => Promise; findGroupById: ( groupId: string | Types.ObjectId, projection?: Record, session?: ClientSession, ) => Promise; createGroup: (groupData: Partial, session?: ClientSession) => Promise; /** Sets the fields and reports, from the write itself, whether any value changed. */ updateGroupFieldsTracked: ( groupId: string | Types.ObjectId, data: Partial>, ) => Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null>; deleteGroup: ( groupId: string | Types.ObjectId, session?: ClientSession, ) => Promise; /** `changed` is decided by the write itself: true only when the membership was altered. */ addUserToGroup: ( userId: string | Types.ObjectId, groupId: string | Types.ObjectId, session?: ClientSession, ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>; removeUserFromGroup: ( userId: string | Types.ObjectId, groupId: string | Types.ObjectId, session?: ClientSession, ) => Promise<{ user: IUser; group: IGroup | null; changed: boolean }>; removeMemberByIdTracked: ( groupId: string | Types.ObjectId, memberId: string, session?: ClientSession, ) => Promise<{ group: IGroup | null; changed: boolean }>; findUsers: ( searchCriteria: FilterQuery, fieldsToSelect?: string | string[] | null, ) => Promise; deleteConfig: ( principalType: PrincipalType, principalId: string | Types.ObjectId, ) => Promise; deleteAclEntries: (filter: { principalType: PrincipalType; principalId: string | Types.ObjectId; }) => Promise; /** Re-creates a removed config override in full, only if none exists, when the group * deletion cannot finish. ACL entries are never restored. Resolves to whether it inserted. */ restoreConfig?: (snapshot: ConfigRecord) => Promise; /** Reads the override before it is removed, so a rejected removal whose commit was * lost in transit can still be put back. */ findConfigByPrincipal?: ( principalType: PrincipalType, principalId: string, options?: { includeInactive?: boolean }, ) => Promise; /** Clears the merged-config caches (on every instance, with Redis) after the deletion removes * or restores the group's config override, before the response, as config writes do. */ invalidateConfigCaches?: (tenantId?: string) => Promise; /** Optional audit emission for group mutations; fail-open unless `auditFailClosed`. */ recordAuditEntry?: RecordAuditEntry; /** When true, a failed audit write surfaces as a 5xx after the mutation has * been persisted. Defaults to fail-open. */ auditFailClosed?: boolean; } function groupTarget(group: Pick & { _id?: unknown }, id?: string) { return { type: 'group', id: id ?? String(group._id ?? ''), name: group.name }; } export function createAdminGroupsHandlers(deps: AdminGroupsDeps): { listGroups: (req: ServerRequest, res: Response) => Promise; getGroup: (req: ServerRequest, res: Response) => Promise; createGroup: (req: ServerRequest, res: Response) => Promise; updateGroup: (req: ServerRequest, res: Response) => Promise; deleteGroup: (req: ServerRequest, res: Response) => Promise; getGroupMembers: (req: ServerRequest, res: Response) => Promise; addGroupMember: (req: ServerRequest, res: Response) => Promise; removeGroupMember: (req: ServerRequest, res: Response) => Promise; } { const { listGroups, countGroups, findGroupById, createGroup, updateGroupFieldsTracked, deleteGroup, addUserToGroup, removeUserFromGroup, removeMemberByIdTracked, findUsers, deleteConfig, deleteAclEntries, restoreConfig, findConfigByPrincipal, invalidateConfigCaches, recordAuditEntry, auditFailClosed, } = deps; const emitRevocationAudit = createAdminAuditEmitter({ recordAuditEntry, logPrefix: '[adminGroups]', }); const emitAudit = createAdminAuditEmitter({ recordAuditEntry, failClosed: auditFailClosed, logPrefix: '[adminGroups]', }); 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, offset } = parsePagination(req.query); 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:', getSafeErrorMetadata(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:', getSafeErrorMetadata(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(); 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 } : {}), }); await emitAudit(req, { action: 'group.created', target: groupTarget(group), metadata: { source: group.source ?? null, memberCount: memberIds.length }, }); /** The initial members gain group-scoped access, so each is recorded like a member add * (bounded by MAX_CREATE_MEMBER_IDS; sequential to keep the audit chain ordered). */ const unique = [...new Set(memberIds)]; for (let i = 0; i < unique.length; i += AUDIT_MEMBER_CHUNK) { const chunk = unique.slice(i, i + AUDIT_MEMBER_CHUNK); await emitAudit(req, { action: 'group.member_added', severity: 'warning', target: groupTarget(group), metadata: { userIds: chunk.join(','), count: chunk.length }, }); } 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:', getSafeErrorMetadata(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> = {}; 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' }); } /** The write itself reports whether it changed a value, so overlapping identical * requests record one entry. */ const result = await updateGroupFieldsTracked(id, updateData); if (!result) { return res.status(404).json({ error: 'Group not found' }); } const { group, changed, changedFields } = result; if (changed) { await emitAudit(req, { action: 'group.updated', target: groupTarget(group, id), metadata: { fields: [...changedFields].sort().join(',') }, }); } 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:', getSafeErrorMetadata(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 existing = await findGroupById(id); if (!existing) { return res.status(404).json({ error: 'Group not found' }); } const target = groupTarget(existing, id); const { deleteConfig: removeProfile, restoreConfig: restoreProfile } = invalidatingConfigStore( { deleteConfig, restoreConfig }, { invalidateConfigCaches, tenantId: req.user?.tenantId, logPrefix: '[adminGroups]' }, ); /** * The attempt is recorded as `pending` before any removal so a crash mid-cascade * still leaves a trail, but the write is started without being awaited: deleting a * group revokes access, so audit latency must not delay the cleanup. Every * later entry waits for it to settle to keep the chain ordered. * A `success` or `failure` entry is appended once the outcome is known. */ const attempt = emitRevocationAudit(req, { action: 'group.deleted', outcome: 'pending', severity: 'warning', target, }); const record = async (outcome: 'success' | 'failure', code?: string) => { await attempt; return emitRevocationAudit(req, { action: 'group.deleted', outcome, severity: 'warning', target, ...(code ? { metadata: { code } } : {}), }); }; const recordFailure = (code: string) => record('failure', code); /** * Config overrides and ACL entries are keyed by group id, so they are * removed before the group itself: if any removal fails the group stays * and the admin can retry, instead of leaving orphaned entries that a later * principal could inherit. Only the config override is put back (insert-only, * so one written since is kept): removing it can widen what members may do, * while ACL entries stay removed because that only narrows access and * re-inserting them could resurrect a grant revoked in the meantime. * deleteAclEntries is a raw deleteMany wrapper with no type casting. * grantPermission stores group principalId as ObjectId, so we must * cast here. deleteConfig normalizes internally. */ let restoreFailed = false; const cascade = await runCascade( [ cascadeStep( 'config', () => removeProfile(PrincipalType.GROUP, id), restoreProfile ? async (config) => { if (!config) { return; } let restored: boolean; try { restored = await restoreProfile(config); restoreFailed = false; } catch (error) { restoreFailed = true; throw error; } if (!restored) { logger.warn('[adminGroups] config restore skipped, override exists:', id); } } : undefined, findConfigByPrincipal ? () => findConfigByPrincipal(PrincipalType.GROUP, id, { includeInactive: true }) : undefined, ), cascadeStep('acl', () => deleteAclEntries({ principalType: PrincipalType.GROUP, principalId: new Types.ObjectId(id), }), ), ], '[adminGroups]', ); /** * Puts the config override back. When that restore itself fails the group would live on * without its restriction, so the deletion is completed instead of retaining it. */ const compensate = async (): Promise<'restored' | 'stuck' | 'missing' | IGroup> => { await cascade.compensate(); if (!restoreFailed) { return 'restored'; } logger.error('[adminGroups] config restore failed, completing the deletion:', id); let removed: IGroup | null = null; try { removed = await deleteGroup(id); if (!removed) { /** Another request deleted the group first; this one removed nothing. */ return 'missing'; } } catch (error) { /** The delete may have committed before it threw (post-delete cache work); a confirmed * absence is a completed deletion. */ const absent = await findGroupById(id).then( (group) => group == null, () => false, ); if (!absent) { logger.error( '[adminGroups] group left without its config override:', id, getSafeErrorMetadata(error), ); return 'stuck'; } removed = existing; } /** The group is gone for good, so a leftover ACL entry is orphaned: retry its removal once. */ await deleteAclEntries({ principalType: PrincipalType.GROUP, principalId: new Types.ObjectId(id), }).catch((aclError) => logger.error( '[adminGroups] acl cleanup retry failed after group deletion:', getSafeErrorMetadata(aclError), ), ); return removed; }; /** Every member loses group-scoped access, so the affected accounts are recorded (chunked). */ const recordMemberRemovals = async (group: IGroup) => { /** Keeps the chain causal: the pending attempt precedes the member entries. */ await attempt; const revoked = [...new Set(group.memberIds ?? [])]; for (let i = 0; i < revoked.length; i += AUDIT_MEMBER_CHUNK) { const chunk = revoked.slice(i, i + AUDIT_MEMBER_CHUNK); await emitRevocationAudit(req, { action: 'group.member_removed', severity: 'warning', target: groupTarget(group, id), metadata: { userIds: chunk.join(','), count: chunk.length, cause: 'group_deleted' }, }); } }; const compensatedResponse = async (outcome: 'stuck' | 'missing' | IGroup) => { if (outcome === 'missing') { await recordFailure('not_found'); return res.status(404).json({ error: 'Group not found' }); } if (outcome !== 'stuck') { await recordMemberRemovals(outcome); res.status(200).json({ success: true, id }); await record('success'); return res; } await recordFailure('GROUP_RESTORE_FAILED'); return res.status(500).json({ error: 'Failed to delete group and its config override could not be restored', code: 'GROUP_RESTORE_FAILED', }); }; const cleanupFailedResponse = async () => { await recordFailure('GROUP_CLEANUP_FAILED'); return res.status(500).json({ error: 'Failed to remove the group permissions and config; the group was not deleted', code: 'GROUP_CLEANUP_FAILED', }); }; if (cascade.failed.length > 0) { /** A concurrent delete may have removed the group meanwhile; restoring its config would * orphan it. When the lookup itself fails the group state is unknown, and putting the * override back is the safe side: a leftover override only restricts, a lost one widens. */ const gone = await findGroupById(id).then( (group) => group == null, () => false, ); if (!gone) { const outcome = await compensate(); if (outcome !== 'restored') { return compensatedResponse(outcome); } } return cleanupFailedResponse(); } let deleted: IGroup | null; try { deleted = await deleteGroup(id); } catch (error) { logger.error( '[adminGroups] deleteGroup failed after cascade cleanup:', getSafeErrorMetadata(error), ); /** The delete may have committed before it threw. Restoring dependents for a * group that is gone would orphan them. */ const lookup = await findGroupById(id).then( (group) => ({ known: true, group }), () => ({ known: false, group: null }), ); if (lookup.known && lookup.group) { const outcome = await compensate(); if (outcome !== 'restored') { return compensatedResponse(outcome); } await recordFailure('GROUP_CLEANUP_FAILED'); return res.status(500).json({ error: 'Failed to delete group' }); } if (!lookup.known) { /** Unknown state favors the restriction: a leftover override narrows access, a lost one widens it. */ const outcome = await compensate(); if (outcome !== 'restored') { return compensatedResponse(outcome); } logger.error('[adminGroups] group state unverifiable after delete failure:', id); await recordFailure('GROUP_STATE_UNVERIFIABLE'); return res.status(500).json({ error: 'Failed to delete group' }); } /** Confirmed absent: the deletion did commit. */ deleted = existing; } if (!deleted) { await recordFailure('not_found'); return res.status(404).json({ error: 'Group not found' }); } await recordMemberRemovals(deleted); res.status(200).json({ success: true, id }); await record('success'); return res; } catch (error) { logger.error('[adminGroups] deleteGroup error:', getSafeErrorMetadata(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, offset } = parsePagination(req.query); 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[] = [{ 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(); 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(); 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:', getSafeErrorMetadata(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, changed } = await addUserToGroup(userId, id); if (!group) { return res.status(404).json({ error: 'Group not found' }); } if (changed) { await emitAudit(req, { action: 'group.member_added', severity: 'warning', target: groupTarget(group, id), metadata: { userId }, }); } 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:', getSafeErrorMetadata(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<{ group: IGroup | null; changed: boolean }> { try { const { group, changed } = await removeUserFromGroup(userId, groupId); return { group, changed }; } catch (err) { const msg = err instanceof Error ? err.message : ''; if (msg === 'User not found' || msg.startsWith('User not found:')) { return removeMemberByIdTracked(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, changed } = isValidObjectIdString(userId) ? await removeObjectIdMember(id, userId) : await removeMemberByIdTracked(id, userId); if (!group) { return res.status(404).json({ error: 'Group not found' }); } if (changed) { await emitAudit(req, { action: 'group.member_removed', severity: 'warning', target: groupTarget(group, id), metadata: { userId }, }); } return res.status(200).json({ success: true }); } catch (error) { logger.error('[adminGroups] removeGroupMember error:', getSafeErrorMetadata(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, }; }