LibreChat/packages/api/src/admin/users.ts
Marco Beretta 20d2c0d43d
🧹 fix: Run the Full Erasure Cascade When an Admin Deletes a User (#17050)
* fix: Run the Erasure Cascade in Admin User Deletion

* refactor: Share Generation Stop Logic Between Self-Service and Admin Deletion

* refactor: Move Admin Erasure Dependency Assembly Into packages/api

* fix: Bind getCleanupJob When Waiting for Generation Persistence

* test: Pin the Deletion Fence Before Admin Generation Stop

* fix: Resolve the Erasure Target Config Fail Closed

* fix: Carry the Target Profile Into Admin Erasure Storage Cleanup

* fix: Keep the Erasure Target Contract Storage Neutral and Reuse the Loaded Identity

* fix: Refuse New Generations Once Account Deletion Has Begun

* fix: Enforce Account Deletion Admission Once in createJob and Narrow the Erasure File Type

* fix: Install the Admission Guard in Every Entrypoint and Purge Refused Jobs

* fix: Guarantee Refused Job Purge and Sanitize Admission Failures

* fix: Route Remote Admission Through createJob and Keep Refusal Cleanup Sanitized

* fix: Log Admission Cleanup Failures With Safe Error Metadata

* refactor: Check Account Deletion Before Creating a Generation and Drain Twice

* refactor: Order Admission Against the Deletion Marker Without a Grace Period

* fix: Sanitize Post-Commit Admission Retirement Failures

* fix: Wire Shared-Server MCP OAuth Cleanup Into Admin Erasure

* fix: Scope Admin Erasure Lookups to the Target Tenant and Await Shared-Link Cleanup

* fix: Resolve the Erasure Target Config Under the Target Tenant

* fix: Run Admin Erasure OAuth Fencing in the Target Tenant

* fix: Match the Split OAuth Invalidate and Disconnect Hooks in Admin Erasure

* refactor: Inject the Tenant Executor Into the Erasure Resolver
2026-10-14 23:54:32 +02:00

363 lines
14 KiB
TypeScript

import { Types } from 'mongoose';
import { randomUUID } from 'node:crypto';
import { PrincipalType, SystemRoles } from 'librechat-data-provider';
import { logger, isValidObjectIdString } from '@librechat/data-schemas';
import type {
IUser,
IConfig,
AdminUserListItem,
AdminUserSearchResult,
UserDeleteResult,
} from '@librechat/data-schemas';
import type { TCheckpointerConfig } from 'librechat-data-provider';
import type { FilterQuery } from 'mongoose';
import type { Response } from 'express';
import type { UserGenerationControl } from '~/user/generations';
import type { UserErasureDeps } from '~/user/erasure';
import type { ServerRequest } from '~/types/http';
import { stopUserGenerations } from '~/user/generations';
import { parsePagination } from './pagination';
import { eraseUserData } from '~/user/erasure';
const MAX_SEARCH_LENGTH = 200;
const ERASURE_PROFILE_KEYS = [
'name',
'username',
'email',
'provider',
'googleId',
'facebookId',
'openidId',
'samlId',
'ldapId',
'githubId',
'discordId',
'appleId',
'emailVerified',
'twoFactorEnabled',
'termsAccepted',
'termsAcceptedAt',
] as const;
const ERASURE_TARGET_FIELDS = ['role', 'tenantId', 'idOnTheSource', ...ERASURE_PROFILE_KEYS].join(
' ',
);
/** The target's plain profile fields, which storage header templates such as the user email read. */
export type ErasureTargetProfile = Partial<Pick<IUser, (typeof ERASURE_PROFILE_KEYS)[number]>>;
const USER_LIST_FIELDS = '_id name username email avatar role provider createdAt updatedAt';
/** The target account's identity, from which the caller builds storage and MCP cleanup. */
export interface AdminErasureTarget {
id: string;
role?: string;
tenantId?: string;
/** External identity key, so principal resolution reuses the loaded user instead of re-reading it. */
idOnTheSource?: string | null;
profile?: ErasureTargetProfile;
}
export interface AdminErasureContext {
deps: UserErasureDeps;
checkpointer?: TCheckpointerConfig;
}
export interface AdminUsersDeps {
findUsers: (
searchCriteria: FilterQuery<IUser>,
fieldsToSelect?: string | string[] | null,
options?: { limit?: number; offset?: number; sort?: Record<string, 1 | -1> },
) => Promise<IUser[]>;
countUsers: (filter?: FilterQuery<IUser>) => Promise<number>;
beginAgentTriggerUserDeletion: (
userId: string,
startedAt: Date,
) => Promise<'acquired' | 'in_progress' | 'missing'>;
cancelAgentTriggerUserDeletion: (userId: string, startedAt: Date) => Promise<boolean>;
drainAgentTriggerDeliveriesForUser: (userId: string) => Promise<void>;
prepareAgentTriggerUserPurge: (
userId: string,
fenceStartedAt: Date,
tenantId?: string,
) => Promise<void>;
cancelAgentTriggerUserPurge: (userId: string, fenceStartedAt: Date) => Promise<boolean>;
purgeAgentTriggerDeliveriesForUser: (userId: string) => Promise<void>;
revokeUserCodeEnvironmentWorkers?: (userId: string) => Promise<number>;
/** Cancels and drains the account's subagent thread tasks. */
cancelSubagentTasks?: (userId: string, tenantId?: string) => Promise<unknown>;
/**
* Reversibly suspends the account's schedules under a per-attempt token; false means the
* executions could not be confirmed stopped. Restored if the deletion fails.
*/
quiesceUserSchedules: (userId: string, token: string) => Promise<boolean>;
restoreUserSchedulesFromDeletion: (userId: string, token: string) => Promise<unknown>;
generationJobs: UserGenerationControl;
/**
* Resolves the dependencies of the shared `eraseUserData` cascade for the account being
* deleted, the same set the self-service controller and the delete-user CLI pass. Storage
* cleanup must run as the target user, not the calling admin.
*/
resolveErasure: (target: AdminErasureTarget) => Promise<AdminErasureContext>;
/** Thin data-layer delete: removes the User document after the erasure cascade has run. */
deleteUserById: (userId: string) => Promise<UserDeleteResult>;
deleteUserCodeEnvironments: (userId: string | Types.ObjectId) => Promise<number>;
invalidateCodeEnvironmentConfigCache: (tenantId?: string) => Promise<void>;
deleteConfig: (
principalType: PrincipalType,
principalId: string | Types.ObjectId,
) => Promise<IConfig | null>;
deleteAclEntries: (filter: {
principalType: PrincipalType;
principalId: string | Types.ObjectId;
}) => Promise<void>;
/**
* Credential IDs are globally unique, so passkeys left behind by a deleted user
* keep authentication material and can collide with a later registration.
*/
deletePasskeysByUser: (userId: string) => Promise<number>;
}
export function createAdminUsersHandlers(deps: AdminUsersDeps): {
listUsers: (req: ServerRequest, res: Response) => Promise<Response>;
searchUsers: (req: ServerRequest, res: Response) => Promise<Response>;
deleteUser: (req: ServerRequest, res: Response) => Promise<Response>;
} {
const {
findUsers,
countUsers,
beginAgentTriggerUserDeletion,
cancelAgentTriggerUserDeletion,
drainAgentTriggerDeliveriesForUser,
prepareAgentTriggerUserPurge,
cancelAgentTriggerUserPurge,
purgeAgentTriggerDeliveriesForUser,
revokeUserCodeEnvironmentWorkers,
deleteUserCodeEnvironments,
deleteUserById,
invalidateCodeEnvironmentConfigCache,
deleteConfig,
deleteAclEntries,
deletePasskeysByUser,
resolveErasure,
cancelSubagentTasks,
quiesceUserSchedules,
restoreUserSchedulesFromDeletion,
generationJobs,
} = deps;
async function listUsersHandler(req: ServerRequest, res: Response) {
try {
const { limit, offset } = parsePagination(req.query);
const [users, total] = await Promise.all([
findUsers({}, USER_LIST_FIELDS, { limit, offset, sort: { createdAt: -1 } }),
countUsers(),
]);
const mapped: AdminUserListItem[] = users.map((u) => ({
id: u._id?.toString() ?? '',
name: u.name ?? '',
username: u.username ?? '',
email: u.email ?? '',
avatar: u.avatar ?? '',
role: u.role ?? 'USER',
provider: u.provider ?? 'local',
createdAt: u.createdAt?.toISOString(),
updatedAt: u.updatedAt?.toISOString(),
}));
return res.status(200).json({ users: mapped, total, limit, offset });
} catch (error) {
logger.error('[adminUsers] listUsers error:', error);
return res.status(500).json({ error: 'Failed to list users' });
}
}
async function searchUsersHandler(req: ServerRequest, res: Response) {
try {
const rawQ = req.query.q;
const rawLimit = req.query.limit;
const query = typeof rawQ === 'string' ? rawQ : undefined;
const limitStr = typeof rawLimit === 'string' ? rawLimit : '20';
const trimmed = query?.trim() ?? '';
if (!trimmed) {
return res.status(400).json({ error: 'Query parameter "q" is required' });
}
if (trimmed.length < 2) {
return res.status(400).json({ error: 'Query must be at least 2 characters' });
}
if (trimmed.length > MAX_SEARCH_LENGTH) {
return res
.status(400)
.json({ error: `Query must not exceed ${MAX_SEARCH_LENGTH} characters` });
}
const searchLimit = Math.min(Math.max(1, parseInt(limitStr, 10) || 20), 50);
const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const regex = new RegExp(`^${escaped}`, 'i');
const users = await findUsers(
{ $or: [{ name: regex }, { email: regex }, { username: regex }] },
'_id name email username avatar',
{ limit: searchLimit, sort: { name: 1 } },
);
const results: AdminUserSearchResult[] = users.map((u) => ({
id: u._id?.toString() ?? '',
name: u.name ?? '',
email: u.email ?? '',
username: u.username,
avatarUrl: u.avatar,
}));
return res
.status(200)
.json({ users: results, total: results.length, capped: results.length >= searchLimit });
} catch (error) {
logger.error('[adminUsers] searchUsers error:', error);
return res.status(500).json({ error: 'Failed to search users' });
}
}
async function deleteUserHandler(req: ServerRequest, res: Response) {
let targetUserId: string | undefined;
let triggerDeletionFence: Date | undefined;
let scheduleSuspensionToken: string | undefined;
let userDeleted = false;
try {
const { id } = req.params as { id: string };
targetUserId = id;
if (!isValidObjectIdString(id)) {
return res.status(400).json({ error: 'Invalid user ID format' });
}
const callerId = req.user?._id?.toString() ?? req.user?.id;
if (callerId === id) {
return res.status(403).json({ error: 'Cannot delete your own account' });
}
const [targetUser] = await findUsers({ _id: id }, ERASURE_TARGET_FIELDS, { limit: 1 });
if (targetUser?.role === SystemRoles.ADMIN) {
const adminCount = await countUsers({ role: SystemRoles.ADMIN });
if (adminCount <= 1) {
return res.status(400).json({ error: 'Cannot delete the last admin user' });
}
}
triggerDeletionFence = new Date();
const fenceState = await beginAgentTriggerUserDeletion(id, triggerDeletionFence);
if (fenceState === 'in_progress') {
triggerDeletionFence = undefined;
return res.status(409).json({ error: 'User deletion is already in progress' });
}
if (fenceState === 'missing') {
triggerDeletionFence = undefined;
return res.status(404).json({ error: 'User not found' });
}
await prepareAgentTriggerUserPurge(id, triggerDeletionFence, targetUser?.tenantId);
await drainAgentTriggerDeliveriesForUser(id);
await cancelSubagentTasks?.(id, targetUser?.tenantId);
scheduleSuspensionToken = randomUUID();
if (!(await quiesceUserSchedules(id, scheduleSuspensionToken))) {
throw new Error('Scheduled executions could not be confirmed stopped');
}
await stopUserGenerations(id, targetUser?.tenantId, generationJobs);
const { deps: erasureDeps, checkpointer } = await resolveErasure({
id,
role: targetUser?.role,
tenantId: targetUser?.tenantId,
idOnTheSource: targetUser?.idOnTheSource ?? null,
profile: targetUser,
});
await eraseUserData(
{ userId: id, tenantId: targetUser?.tenantId, checkpointer },
erasureDeps,
);
const result = await deleteUserById(id);
if (result.deletedCount === 0) {
await cancelAgentTriggerUserPurge(id, triggerDeletionFence);
await cancelAgentTriggerUserDeletion(id, triggerDeletionFence);
triggerDeletionFence = undefined;
return res.status(404).json({ error: 'User not found' });
}
userDeleted = true;
let codeEnvironmentCleanupSafe = true;
try {
await revokeUserCodeEnvironmentWorkers?.(id);
} catch (error) {
codeEnvironmentCleanupSafe = false;
logger.error('[adminUsers] failed to revoke code environment workers:', id, error);
}
await purgeAgentTriggerDeliveriesForUser(id);
if (targetUser?.role === SystemRoles.ADMIN) {
const remaining = await countUsers({ role: SystemRoles.ADMIN });
if (remaining === 0) {
logger.error(
`[adminUsers] CRITICAL: last admin deleted via race condition, user: ${id}. ` +
'Manual DB intervention required to restore an ADMIN user.',
);
}
}
const objectId = new Types.ObjectId(id);
const cleanupResults = await Promise.allSettled([
deleteConfig(PrincipalType.USER, id),
...(codeEnvironmentCleanupSafe ? [deleteUserCodeEnvironments(objectId)] : []),
deleteAclEntries({ principalType: PrincipalType.USER, principalId: objectId }),
deletePasskeysByUser(id),
]);
for (const r of cleanupResults) {
if (r.status === 'rejected') {
logger.error('[adminUsers] cascade cleanup failed for user:', id, r.reason);
}
}
await invalidateCodeEnvironmentConfigCache(targetUser?.tenantId).catch((error: unknown) => {
logger.error('[adminUsers] code environment cache invalidation failed:', id, error);
});
return res.status(200).json({ message: result.message || 'User deleted successfully' });
} catch (error) {
/** Restore before releasing the fence, as the self-service flow does. */
if (targetUserId != null && scheduleSuspensionToken != null && !userDeleted) {
try {
await restoreUserSchedulesFromDeletion(targetUserId, scheduleSuspensionToken);
} catch (restoreError) {
logger.error(
`[adminUsers] failed to restore suspended schedules for user ${targetUserId} under token ${scheduleSuspensionToken}:`,
restoreError,
);
}
}
if (targetUserId != null && triggerDeletionFence != null && !userDeleted) {
try {
await cancelAgentTriggerUserPurge(targetUserId, triggerDeletionFence);
} catch (purgeFenceError) {
logger.error('[adminUsers] failed to disarm trigger purge recovery:', purgeFenceError);
}
try {
await cancelAgentTriggerUserDeletion(targetUserId, triggerDeletionFence);
} catch (fenceError) {
logger.error('[adminUsers] failed to release trigger deletion fence:', fenceError);
}
}
logger.error('[adminUsers] deleteUser error:', error);
return res.status(500).json({ error: 'Failed to delete user' });
}
}
return {
listUsers: listUsersHandler,
searchUsers: searchUsersHandler,
deleteUser: deleteUserHandler,
};
}