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
import mongoose, { FilterQuery } from 'mongoose';
import { AUTH_USER_DOC_MAX_AGE_MS } from 'librechat-data-provider';
import type {
BalanceRefillMode,
RefillIntervalUnit,
StatefulCodeEnvironment,
} from 'librechat-data-provider';
import type {
IUser,
BalanceConfig,
CreateUserRequest,
UserRecord,
NewUserData,
UserDeleteResult,
CreateUserIfAbsentResult,
} from '~/types';
import type { TwoFactorEnrollmentGuard, TwoFactorEnrollmentUpdate } from '~/types';
import type { CacheStore } from '~/types';
import { scoreSearchMatch, buildUserSearchFilter } from '~/utils/search';
import { evictAuthUserDocsForUsers } from '~/utils/eviction';
import { signPayload } from '~/crypto';
import logger from '~/config/winston';
/** Default JWT session expiry: 15 minutes in milliseconds */
export const DEFAULT_SESSION_EXPIRY: number = 1000 * 60 * 15;
/** Minimum age before an explicitly offline operator may recover an abandoned deletion fence. */
export const USER_DELETION_FENCE_STALE_MS: number = 15 * 60_000;
/** Bounds concurrent bulk deletions held for one owner at any moment. */
const MAX_SUBAGENT_ADMISSION_FENCES = 32;
/** Providers whose credentials LibreChat owns, and therefore the only ones it can enroll in 2FA. */
const TWO_FACTOR_ENROLLMENT_PROVIDERS = [null, 'local', 'ldap'];
const TWO_FACTOR_ENROLLMENT_PROJECTION =
'+totpSecret +backupCodes +pendingTotpSecret +pendingBackupCodes +twoFactorAcknowledgementNonceHash +twoFactorFinalizationNonceHash';
interface UserMethodDeps {
getCache?: (key: string) => CacheStore | undefined;
/** Resolves after the given milliseconds; tests pass one that need not wait out the cache TTL. */
delay?: (ms: number) => Promise<void>;
}
const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
/** Timers can fire a millisecond early, so the wait outlasts a cached document by this much. */
const AUTH_USER_DOC_EXPIRY_MARGIN_MS = 100;
/** Cached auth documents evicted at once when a reset touches every user. */
const TERMS_RESET_EVICTION_BATCH = 100;
/** Factory function that takes mongoose instance and returns the methods */
export function createUserMethods(
mongoose: typeof import('mongoose'),
deps: UserMethodDeps = {},
): {
findUser: (
searchCriteria: FilterQuery<IUser>,
fieldsToSelect?: string | string[] | null,
) => Promise<IUser | null>;
findUsers: (
searchCriteria: FilterQuery<IUser>,
fieldsToSelect?: string | string[] | null,
options?: { limit?: number; offset?: number; sort?: Record<string, 1 | -1> },
) => Promise<IUser[]>;
findOwnerContactUsers: (
ownerIds: string[],
) => Promise<Array<Pick<IUser, '_id' | 'name' | 'username'>>>;
countUsers: (filter?: FilterQuery<IUser>) => Promise<number>;
createUser: (
data: CreateUserRequest,
balanceConfig?: BalanceConfig,
disableTTL?: boolean,
returnUser?: boolean,
) => Promise<mongoose.Types.ObjectId | Partial<IUser>>;
createUserIfAbsent: (
data: NewUserData,
balanceConfig?: BalanceConfig,
) => Promise<CreateUserIfAbsentResult>;
updateUser: (
userId: string,
updateData: Partial<IUser>,
expectedState?: FilterQuery<IUser>,
options?: { preserveExpiresAt?: boolean },
) => Promise<IUser | null>;
awaitAuthUserDocEviction: (userId: string) => Promise<void>;
consumeBackupCode: (userId: string, codeHash: string) => Promise<boolean>;
claimSamlIdentity: (
userId: string,
samlId: string,
profileData: Pick<Partial<IUser>, 'username' | 'name'>,
) => Promise<IUser | null>;
updateTwoFactorEnrollment: (
userId: string,
guard: TwoFactorEnrollmentGuard,
updateData: TwoFactorEnrollmentUpdate,
) => Promise<IUser | null>;
acceptTerms: (userId: string) => Promise<IUser | null>;
resetTermsAcceptance: () => Promise<{ modifiedCount: number }>;
searchUsers: ({
searchPattern,
limit,
fieldsToSelect,
}: {
searchPattern: string;
limit?: number;
fieldsToSelect?: string | string[] | null;
}) => Promise<
{
_id: mongoose.Types.ObjectId;
id: string;
name?: string;
username?: string;
email: string;
emailVerified: boolean;
password?: string;
avatar?: string;
provider: string;
role?: string;
googleId?: string;
facebookId?: string;
openidId?: string;
samlId?: string;
ldapId?: string;
githubId?: string;
discordId?: string;
appleId?: string;
plugins?: string[];
openidIssuer?: string;
twoFactorEnabled?: boolean;
totpSecret?: string;
backupCodes?: Array<{
codeHash: string;
used: boolean;
usedAt?: Date | null;
}>;
pendingTotpSecret?: string;
pendingBackupCodes?: Array<{
codeHash: string;
used: boolean;
usedAt?: Date | null;
}>;
twoFactorAcknowledgementNonceHash?: string | null;
twoFactorFinalizationNonceHash?: string | null;
refreshToken?: Array<{
refreshToken: string;
}>;
expiresAt?: Date;
termsAccepted?: boolean;
personalization?: {
memories?: boolean;
statefulCodeEnvironment?: import('librechat-data-provider').StatefulCodeEnvironment;
};
favorites?: import('librechat-data-provider').TUserFavorite[];
skillStates?: Record<string, boolean>;
createdAt?: Date;
updatedAt?: Date;
idOnTheSource?: string;
tenantId?: string;
federatedTokens?: import('~/types').OIDCTokens;
openidTokens?: import('~/types').OIDCTokens;
$locals: Record<string, unknown>;
$op: 'save' | 'validate' | 'remove' | null;
$where: Record<string, unknown>;
baseModelName?: string;
collection: mongoose.Collection;
db: mongoose.Connection;
errors?: mongoose.Error.ValidationError;
isNew: boolean;
schema: mongoose.Schema;
}[]
>;
getUserById: (userId: string, fieldsToSelect?: string | string[] | null) => Promise<IUser | null>;
generateToken: (user: IUser, expiresIn?: number) => Promise<string>;
beginAgentTriggerUserDeletion: (
userId: string,
startedAt: Date,
) => Promise<'acquired' | 'in_progress' | 'missing'>;
recoverStaleAgentTriggerUserDeletion: (
userId: string,
recoveredAt: Date,
) => Promise<'acquired' | 'in_progress' | 'missing'>;
cancelAgentTriggerUserDeletion: (userId: string, startedAt: Date) => Promise<boolean>;
isAgentTriggerPrincipalActive: (userId: string) => Promise<boolean>;
fenceSubagentAdmission: (userId: string, token: string, fencedUntil: Date) => Promise<void>;
renewSubagentAdmission: (userId: string, token: string, fencedUntil: Date) => Promise<boolean>;
releaseSubagentAdmission: (userId: string, token: string) => Promise<void>;
isSubagentOwnerAdmissible: (userId: string) => Promise<boolean>;
deleteUserById: (userId: string) => Promise<UserDeleteResult>;
updateUserPlugins: (
userId: string,
plugins: string[] | undefined,
pluginKey: string,
action: 'install' | 'uninstall',
) => Promise<IUser | null>;
toggleUserMemories: (userId: string, memoriesEnabled: boolean) => Promise<IUser | null>;
updateUserStatefulCodeEnvironment: (
userId: string,
environment: StatefulCodeEnvironment,
) => Promise<IUser | null>;
} {
/**
* Normalizes email fields in search criteria to lowercase and trimmed.
* Handles both direct email fields and $or arrays containing email conditions.
*/
function normalizeEmailInCriteria<T extends FilterQuery<IUser>>(criteria: T): T {
const normalized = { ...criteria };
if (typeof normalized.email === 'string') {
normalized.email = normalized.email.trim().toLowerCase();
}
if (Array.isArray(normalized.$or)) {
normalized.$or = normalized.$or.map((condition) => {
if (typeof condition.email === 'string') {
return { ...condition, email: condition.email.trim().toLowerCase() };
}
return condition;
});
}
return normalized;
}
/**
* Search for a single user based on partial data and return matching user document as plain object.
* Email fields in searchCriteria are automatically normalized to lowercase for case-insensitive matching.
*/
async function findUser(
searchCriteria: FilterQuery<IUser>,
fieldsToSelect?: string | string[] | null,
): Promise<IUser | null> {
const User = mongoose.models.User as mongoose.Model<IUser>;
const normalizedCriteria = normalizeEmailInCriteria(searchCriteria);
const query = User.findOne(normalizedCriteria);
if (fieldsToSelect) {
query.select(fieldsToSelect);
}
return await query.lean<IUser>();
}
async function findUsers(
searchCriteria: FilterQuery<IUser>,
fieldsToSelect?: string | string[] | null,
options?: { limit?: number; offset?: number; sort?: Record<string, 1 | -1> },
): Promise<IUser[]> {
const User = mongoose.models.User as mongoose.Model<IUser>;
const normalizedCriteria = normalizeEmailInCriteria(searchCriteria);
const query = User.find(normalizedCriteria);
if (fieldsToSelect) {
query.select(fieldsToSelect);
}
if (options?.sort != null) {
query.sort(options.sort);
}
if (options?.offset != null) {
query.skip(options.offset);
}
if (options?.limit != null && options.limit > 0) {
query.limit(options.limit);
}
return await query.lean<IUser[]>();
}
async function findOwnerContactUsers(
ownerIds: string[],
): Promise<Array<Pick<IUser, '_id' | 'name' | 'username'>>> {
if (ownerIds.length === 0) {
return [];
}
const User = mongoose.models.User as mongoose.Model<IUser>;
const objectIds = ownerIds.map((ownerId) => new mongoose.Types.ObjectId(ownerId));
return await User.find({ _id: { $in: objectIds } })
.select('_id name username')
.lean<Array<Pick<IUser, '_id' | 'name' | 'username'>>>();
}
/**
* Count the number of user documents in the collection based on the provided filter.
*/
async function countUsers(filter: FilterQuery<IUser> = {}): Promise<number> {
const User = mongoose.models.User;
return await User.countDocuments(filter);
}
/**
* Initializes a new user's start balance, with auto-refill settings when complete. The write is
* insert-only, so it never replaces a balance that already exists or the activity recorded on it.
*/
async function creditStartBalance(
userId: mongoose.Types.ObjectId,
balanceConfig?: BalanceConfig,
): Promise<void> {
if (!balanceConfig?.enabled || !balanceConfig?.startBalance) {
return;
}
const Balance = mongoose.models.Balance;
const initial: {
tokenCredits: number;
autoRefillEnabled?: boolean;
refillIntervalValue?: number;
refillIntervalUnit?: RefillIntervalUnit;
refillAmount?: number;
refillMode?: BalanceRefillMode;
} = { tokenCredits: balanceConfig.startBalance };
if (
balanceConfig.autoRefillEnabled &&
balanceConfig.refillIntervalValue != null &&
balanceConfig.refillIntervalUnit != null &&
balanceConfig.refillAmount != null
) {
initial.autoRefillEnabled = true;
initial.refillIntervalValue = balanceConfig.refillIntervalValue;
initial.refillIntervalUnit = balanceConfig.refillIntervalUnit;
initial.refillAmount = balanceConfig.refillAmount;
initial.refillMode = balanceConfig.refillMode ?? 'add';
}
await Balance.findOneAndUpdate(
{ _id: userId },
{ $setOnInsert: { ...initial, user: userId } },
{ upsert: true, new: true },
).lean();
}
/**
* Creates a new user, optionally with a TTL of 1 week.
*/
async function createUser(
data: CreateUserRequest,
balanceConfig?: BalanceConfig,
disableTTL: boolean = true,
returnUser: boolean = false,
): Promise<mongoose.Types.ObjectId | Partial<IUser>> {
const User = mongoose.models.User;
const userData: Partial<IUser> = {
...data,
expiresAt: disableTTL ? undefined : new Date(Date.now() + 604800 * 1000), // 1 week in milliseconds
};
if (disableTTL) {
delete userData.expiresAt;
}
const user = await User.create(userData);
await creditStartBalance(user._id, balanceConfig);
if (returnUser) {
return user.toObject() as Partial<IUser>;
}
return user._id as mongoose.Types.ObjectId;
}
/**
* Creates a user without a TTL, or reports `user_exists` when a unique email or provider
* identity index already holds the account, as when concurrent first logins race to insert it.
* The start balance is initialized under the new user's id before the user is inserted, so
* the account is never visible without it and login balance sync never initializes it first.
* A balance write that fails, or an insert a unique index rejects, removes the balance under
* the id that never became a user; any other insert failure keeps it, since an unacknowledged
* insert may still have committed.
*/
async function createUserIfAbsent(
data: NewUserData,
balanceConfig?: BalanceConfig,
): Promise<CreateUserIfAbsentResult> {
const User = mongoose.models.User as mongoose.Model<IUser>;
const userData: Partial<IUser> = { ...data };
delete userData.expiresAt;
const user = new User(userData);
await user.validate();
try {
await creditStartBalance(user._id, balanceConfig);
} catch (error) {
await discardStartBalance(user._id, balanceConfig);
throw error;
}
try {
await user.save({ validateBeforeSave: false });
} catch (error) {
if ((error as { code?: number }).code !== 11000) {
throw error;
}
await discardStartBalance(user._id, balanceConfig);
return { ok: false, error: { code: 'user_exists' } };
}
return { ok: true, value: user.toObject() as UserRecord };
}
/** Removes, best effort, the start balance initialized for an id that never became a user. */
async function discardStartBalance(
userId: mongoose.Types.ObjectId,
balanceConfig?: BalanceConfig,
): Promise<void> {
if (!balanceConfig?.enabled || !balanceConfig?.startBalance) {
return;
}
try {
await mongoose.models.Balance.deleteOne({ _id: userId });
} catch {
logger.warn(
'[createUserIfAbsent] Could not remove the start balance of a user never created',
{
userId: userId.toString(),
},
);
}
}
/**
* Update a user with new data without overwriting existing properties.
* Removes pending-account expiry unless preserveExpiresAt is requested.
*/
async function updateUser(
userId: string,
updateData: Partial<IUser>,
expectedState: FilterQuery<IUser> = {},
options: { preserveExpiresAt?: boolean } = {},
): Promise<IUser | null> {
const User = mongoose.models.User;
const updateOperation = {
$set: updateData,
...(options.preserveExpiresAt ? {} : { $unset: { expiresAt: '' } }),
};
const updated = await User.findOneAndUpdate(
{ ...expectedState, _id: userId },
updateOperation,
{
new: true,
runValidators: true,
},
).lean<IUser>();
await invalidateAuthUserDocCache(userId);
return updated;
}
/**
* The barrier a credential change passes before it is confirmed. A cached document without
* the new credentialsChangedAt keeps pre-change access tokens verifying until it expires, so
* eviction is retried and, when it still cannot remove every document, this resolves only
* after the longest a cached document can live, which a lookup that began just before the
* change may stretch to two cache TTLs. Callers revoke sessions and passkeys first: during the wait those
* could otherwise mint access tokens issued after the stamp.
*/
async function awaitAuthUserDocEviction(userId: string): Promise<void> {
if (await invalidateAuthUserDocCache(userId)) {
return;
}
logger.warn(
'[awaitAuthUserDocEviction] Cached auth documents were not evicted after a credential change; waiting for them to expire',
{ userId, waitMs: AUTH_USER_DOC_MAX_AGE_MS + AUTH_USER_DOC_EXPIRY_MARGIN_MS },
);
await (deps.delay ?? wait)(AUTH_USER_DOC_MAX_AGE_MS + AUTH_USER_DOC_EXPIRY_MARGIN_MS);
}
/** Only the request that atomically consumes an unused recovery code may authenticate. */
async function consumeBackupCode(userId: string, codeHash: string): Promise<boolean> {
const result = await mongoose.models.User.updateOne(
{ _id: userId, backupCodes: { $elemMatch: { codeHash, used: false } } },
{ $set: { 'backupCodes.$.used': true, 'backupCodes.$.usedAt': new Date() } },
);
if (result.modifiedCount !== 1) {
return false;
}
await invalidateAuthUserDocCache(userId);
return true;
}
/** Atomically updates a SAML user only when the incoming identity can claim the document. */
async function claimSamlIdentity(
userId: string,
samlId: string,
profileData: Pick<Partial<IUser>, 'username' | 'name'>,
): Promise<IUser | null> {
const User = mongoose.models.User;
const updated = await User.findOneAndUpdate(
{
_id: userId,
provider: 'saml',
$or: [{ samlId }, { samlId: { $exists: false } }, { samlId: null }, { samlId: '' }],
},
{
$set: { ...profileData, samlId },
$unset: { expiresAt: '' },
},
{ new: true, runValidators: true },
).lean<IUser>();
if (updated) {
await invalidateAuthUserDocCache(userId);
}
return updated;
}
/**
* Single compare-and-swap for every step of required two-factor enrollment. The filter always
* pins the user to an unenrolled, policy-eligible provider, and `guard` adds the exact pending
* secret, pending backup-code snapshot, or one-time nonce hash the caller observed. A step whose
* predicate has moved returns `null` instead of writing.
*/
async function updateTwoFactorEnrollment(
userId: string,
guard: TwoFactorEnrollmentGuard,
updateData: TwoFactorEnrollmentUpdate,
): Promise<IUser | null> {
const User = mongoose.models.User;
const updated = await User.findOneAndUpdate(
{
_id: userId,
twoFactorEnabled: { $ne: true },
provider: { $in: TWO_FACTOR_ENROLLMENT_PROVIDERS },
...guard,
},
{ $set: updateData, $unset: { expiresAt: '' } },
{ new: true, runValidators: true },
)
.select(TWO_FACTOR_ENROLLMENT_PROJECTION)
.lean<IUser>();
if (updated) {
await invalidateAuthUserDocCache(userId);
}
return updated;
}
/** Resolves false only when a cached document for the user may still be served. */
async function invalidateAuthUserDocCache(userId: string): Promise<boolean> {
return evictAuthUserDocsForUsers(deps.getCache, [userId]);
}
/**
* Atomically records terms acceptance for a user.
* A null-guarded claim stamps termsAcceptedAt only when no timestamp is
* already stored (explicit null from the schema default, a missing legacy
* field, or a terms reset), so the first acceptance within a terms cycle is
* preserved across concurrent or repeated requests. The repeat-acceptance
* fallback is guarded by the exact complement (a non-null timestamp) so it
* can never resurrect termsAccepted into a cycle that config/reset-terms.js
* started between the two updates; when both guards miss because a reset
* raced in, the claim retries and records a fresh stamped acceptance. Plain
* updates are used instead of an aggregation pipeline with $$NOW, which
* Amazon DocumentDB rejects.
*/
/** Withdraws every user's acceptance and evicts their cached auth documents, so a reset takes effect at once. */
async function resetTermsAcceptance(): Promise<{ modifiedCount: number }> {
const User = mongoose.models.User;
const result = await User.updateMany(
{},
{
$set: { termsAccepted: false, termsAcceptedAt: null },
$unset: { termsAcceptedSource: 1 },
},
);
/** Every user, not only those read as accepted beforehand: an acceptance racing the update may be cached. */
const cursor = User.find({}).select('_id').lean().cursor();
let evicted = true;
let batch: string[] = [];
for await (const user of cursor) {
batch.push(String(user._id));
if (batch.length === TERMS_RESET_EVICTION_BATCH) {
evicted = (await evictAuthUserDocsForUsers(deps.getCache, batch)) && evicted;
batch = [];
}
}
evicted = (await evictAuthUserDocsForUsers(deps.getCache, batch)) && evicted;
if (!evicted) {
/** The eviction fence keeps requests that read the old document from caching it, so only a failed eviction needs to outlast the TTL. */
logger.warn(
'[resetTermsAcceptance] Cached auth documents were not evicted; waiting for them to expire',
{
waitMs: AUTH_USER_DOC_MAX_AGE_MS + AUTH_USER_DOC_EXPIRY_MARGIN_MS,
},
);
await (deps.delay ?? wait)(AUTH_USER_DOC_MAX_AGE_MS + AUTH_USER_DOC_EXPIRY_MARGIN_MS);
}
return { modifiedCount: result.modifiedCount };
}
async function acceptTerms(userId: string): Promise<IUser | null> {
const User = mongoose.models.User;
const maxAttempts = 3;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const firstAcceptance = await User.findOneAndUpdate(
{ _id: userId, termsAcceptedAt: null },
{
$set: { termsAccepted: true, termsAcceptedAt: new Date() },
$unset: { termsAcceptedSource: 1 },
},
{ new: true, runValidators: true },
).lean<IUser>();
if (firstAcceptance) {
await invalidateAuthUserDocCache(userId);
return firstAcceptance;
}
const reacceptance = await User.findOneAndUpdate(
{ _id: userId, termsAcceptedAt: { $ne: null } },
{ $set: { termsAccepted: true } },
{ new: true, runValidators: true },
).lean<IUser>();
if (reacceptance) {
await invalidateAuthUserDocCache(userId);
return reacceptance;
}
const exists = await User.exists({ _id: userId });
if (!exists) {
return null;
}
}
return null;
}
/**
* Retrieve a user by ID and convert the found user document to a plain object.
*/
async function getUserById(
userId: string,
fieldsToSelect?: string | string[] | null,
): Promise<IUser | null> {
const User = mongoose.models.User;
const query = User.findById(userId);
if (fieldsToSelect) {
query.select(fieldsToSelect);
}
return await query.lean<IUser>();
}
/**
* Delete a user by their unique ID.
*/
async function deleteUserById(userId: string): Promise<UserDeleteResult> {
try {
const User = mongoose.models.User;
await mongoose.models.ToolApprovalGrant?.deleteMany({ user: userId });
const result = await User.deleteOne({ _id: userId });
if (result.deletedCount === 0) {
return { deletedCount: 0, message: 'No user found with that ID.' };
}
await invalidateAuthUserDocCache(userId);
return { deletedCount: result.deletedCount, message: 'User was deleted successfully.' };
} catch (error: unknown) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
throw new Error('Error deleting user: ' + errorMessage);
}
}
/** Establishes the durable admission fence used while account deletion drains triggers. */
async function beginAgentTriggerUserDeletion(
userId: string,
startedAt: Date,
): Promise<'acquired' | 'in_progress' | 'missing'> {
if (!(startedAt instanceof Date) || !Number.isFinite(startedAt.getTime())) {
throw new TypeError('startedAt must be a valid Date');
}
const User = mongoose.models.User;
const result = await User.updateOne(
{ _id: userId, agentTriggerDeletionStartedAt: { $exists: false } },
{ $set: { agentTriggerDeletionStartedAt: startedAt } },
);
if (result.modifiedCount === 1) {
await invalidateAuthUserDocCache(userId);
return 'acquired';
}
return (await User.exists({ _id: userId })) == null ? 'missing' : 'in_progress';
}
/** Replaces an abandoned fence only for an operator-confirmed offline deployment.
* Normal request paths must never call this: age alone cannot prove the prior owner died. */
async function recoverStaleAgentTriggerUserDeletion(
userId: string,
recoveredAt: Date,
): Promise<'acquired' | 'in_progress' | 'missing'> {
if (!(recoveredAt instanceof Date) || !Number.isFinite(recoveredAt.getTime())) {
throw new TypeError('recoveredAt must be a valid Date');
}
const User = mongoose.models.User;
const staleBefore = new Date(recoveredAt.getTime() - USER_DELETION_FENCE_STALE_MS);
const result = await User.updateOne(
{ _id: userId, agentTriggerDeletionStartedAt: { $lte: staleBefore } },
{ $set: { agentTriggerDeletionStartedAt: recoveredAt } },
);
if (result.modifiedCount === 1) {
await invalidateAuthUserDocCache(userId);
return 'acquired';
}
return (await User.exists({ _id: userId })) == null ? 'missing' : 'in_progress';
}
/** Releases only the account-deletion attempt that owns this exact fence. */
async function cancelAgentTriggerUserDeletion(userId: string, startedAt: Date): Promise<boolean> {
const User = mongoose.models.User;
const result = await User.updateOne(
{ _id: userId, agentTriggerDeletionStartedAt: startedAt },
{ $unset: { agentTriggerDeletionStartedAt: 1 } },
);
if (result.modifiedCount === 1) {
await invalidateAuthUserDocCache(userId);
return true;
}
return false;
}
async function isAgentTriggerPrincipalActive(userId: string): Promise<boolean> {
const User = mongoose.models.User;
return (
(await User.exists({ _id: userId, agentTriggerDeletionStartedAt: { $exists: false } })) !=
null
);
}
/**
* Closes subagent admission for one owner while a bulk conversation deletion drains
* its live children. Every concurrent deletion holds its own fence, so admission
* reopens only once the last one finishes, in whatever order they complete. Each
* fence expires on its own, so a process that dies mid-delete cannot lock the
* account out of running subagents, and expired fences are pruned as new ones
* arrive rather than accumulating.
*/
async function fenceSubagentAdmission(
userId: string,
token: string,
fencedUntil: Date,
): Promise<void> {
if (!(fencedUntil instanceof Date) || !Number.isFinite(fencedUntil.getTime())) {
throw new TypeError('fencedUntil must be a valid Date');
}
if (token.length === 0 || token.length > 128) {
throw new TypeError('A subagent admission fence needs a bounded owner token');
}
const User = mongoose.models.User;
/** Plain update operators only: DocumentDB rejects pipeline-form updates, and
* this runs before any deletion, so using one would fail the whole endpoint. */
await User.updateOne(
{ _id: userId },
{ $pull: { subagentAdmissionFences: { expiresAt: { $lte: new Date() } } } },
{ timestamps: false },
);
try {
/** Admitted only while the owner is under the concurrent-deletion cap. Dropping
* an active fence to make room would reopen admission for a deletion that is
* still running, so an excess deletion is refused instead. */
const fenced = await User.updateOne(
{
_id: userId,
[`subagentAdmissionFences.${MAX_SUBAGENT_ADMISSION_FENCES - 1}`]: { $exists: false },
},
{ $push: { subagentAdmissionFences: { token, expiresAt: fencedUntil } } },
{ timestamps: false },
);
if (fenced.matchedCount !== 1) {
throw new Error('Too many concurrent bulk deletions are already fencing this owner.');
}
} finally {
/** The prune above commits on its own, so a refused or failed fence still leaves
* the cached document describing entries the collection no longer holds. */
await invalidateAuthUserDocCache(userId);
}
}
/** Extends only this deletion's own fence while its work is still running. */
async function renewSubagentAdmission(
userId: string,
token: string,
fencedUntil: Date,
): Promise<boolean> {
if (!(fencedUntil instanceof Date) || !Number.isFinite(fencedUntil.getTime())) {
throw new TypeError('fencedUntil must be a valid Date');
}
const User = mongoose.models.User;
const result = await User.updateOne(
{ _id: userId, 'subagentAdmissionFences.token': token },
{ $set: { 'subagentAdmissionFences.$.expiresAt': fencedUntil } },
{ timestamps: false },
);
if (result.modifiedCount === 1) {
await invalidateAuthUserDocCache(userId);
}
return result.matchedCount === 1;
}
/** Lifts only this deletion's fence, so an overlapping one keeps admission closed. */
async function releaseSubagentAdmission(userId: string, token: string): Promise<void> {
const User = mongoose.models.User;
const result = await User.updateOne(
{ _id: userId },
{ $pull: { subagentAdmissionFences: { token } } },
{ timestamps: false },
);
if (result.modifiedCount === 1) {
await invalidateAuthUserDocCache(userId);
}
}
/** True while this owner may admit a new child: no account deletion, no live fence. */
async function isSubagentOwnerAdmissible(userId: string): Promise<boolean> {
const User = mongoose.models.User;
return (
(await User.exists({
_id: userId,
agentTriggerDeletionStartedAt: { $exists: false },
subagentAdmissionFences: { $not: { $elemMatch: { expiresAt: { $gt: new Date() } } } },
})) != null
);
}
/**
* Generates a JWT token for a given user.
* @param user - The user object
* @param expiresIn - Optional expiry time in milliseconds. Default: 15 minutes
*/
async function generateToken(user: IUser, expiresIn?: number): Promise<string> {
if (!user) {
throw new Error('No user provided');
}
const expires = expiresIn ?? DEFAULT_SESSION_EXPIRY;
return await signPayload({
payload: {
id: user._id,
username: user.username,
provider: user.provider,
email: user.email,
/** `iat` is whole seconds, too coarse to order this token against a password reset that
* lands in the same second. `isTokenRetired` reads this claim to settle that exactly. */
issuedAtMs: Date.now(),
},
secret: process.env.JWT_SECRET,
expirationTime: expires / 1000,
});
}
/**
* Update a user's personalization memories setting.
* Handles the edge case where the personalization object doesn't exist.
*/
async function toggleUserMemories(
userId: string,
memoriesEnabled: boolean,
): Promise<IUser | null> {
const User = mongoose.models.User;
/** `$set` on the nested path creates `personalization` when missing; a missing user yields null. */
const updateOperation = {
$set: {
'personalization.memories': memoriesEnabled,
},
};
const updated = await User.findByIdAndUpdate(userId, updateOperation, {
new: true,
runValidators: true,
}).lean<IUser>();
if (updated) {
await invalidateAuthUserDocCache(userId);
}
return updated;
}
async function updateUserStatefulCodeEnvironment(
userId: string,
environment: StatefulCodeEnvironment,
): Promise<IUser | null> {
const User = mongoose.models.User;
const updated = await User.findByIdAndUpdate(
userId,
{ $set: { 'personalization.statefulCodeEnvironment': environment } },
{ new: true, runValidators: true },
).lean<IUser>();
if (updated) {
await invalidateAuthUserDocCache(userId);
}
return updated;
}
/**
* Search for users by word prefix of name, email, or username (see `buildUserSearchFilter`)
* @param searchPattern - The pattern to search for
* @param limit - Maximum number of results to return
* @param fieldsToSelect - The fields to include or exclude in the returned documents
* @returns Array of matching user documents
*/
const searchUsers = async function ({
searchPattern,
limit = 20,
fieldsToSelect = null,
}: {
searchPattern: string;
limit?: number;
fieldsToSelect?: string | string[] | null;
}): Promise<
{
_id: mongoose.Types.ObjectId;
id: string;
name?: string;
username?: string;
email: string;
emailVerified: boolean;
password?: string;
avatar?: string;
provider: string;
role?: string;
googleId?: string;
facebookId?: string;
openidId?: string;
samlId?: string;
ldapId?: string;
githubId?: string;
discordId?: string;
appleId?: string;
plugins?: string[];
openidIssuer?: string;
twoFactorEnabled?: boolean;
totpSecret?: string;
backupCodes?: Array<{
codeHash: string;
used: boolean;
usedAt?: Date | null;
}>;
pendingTotpSecret?: string;
pendingBackupCodes?: Array<{
codeHash: string;
used: boolean;
usedAt?: Date | null;
}>;
twoFactorAcknowledgementNonceHash?: string | null;
twoFactorFinalizationNonceHash?: string | null;
refreshToken?: Array<{
refreshToken: string;
}>;
expiresAt?: Date;
termsAccepted?: boolean;
personalization?: {
memories?: boolean;
statefulCodeEnvironment?: import('librechat-data-provider').StatefulCodeEnvironment;
};
favorites?: import('librechat-data-provider').TUserFavorite[];
skillStates?: Record<string, boolean>;
createdAt?: Date;
updatedAt?: Date;
idOnTheSource?: string;
tenantId?: string;
federatedTokens?: import('~/types').OIDCTokens;
openidTokens?: import('~/types').OIDCTokens;
$locals: Record<string, unknown>;
$op: 'save' | 'validate' | 'remove' | null;
$where: Record<string, unknown>;
baseModelName?: string;
collection: mongoose.Collection;
db: mongoose.Connection;
errors?: mongoose.Error.ValidationError;
isNew: boolean;
schema: mongoose.Schema;
}[]
> {
if (!searchPattern || searchPattern.trim().length === 0) {
return [];
}
const trimmedPattern = searchPattern.trim();
const filter = buildUserSearchFilter(trimmedPattern);
if (!filter) {
return [];
}
const User = mongoose.models.User;
const query = User.find(filter).limit(limit * 2); // Get more results to allow for relevance sorting
if (fieldsToSelect) {
query.select(fieldsToSelect);
}
const users = await query.lean<IUser[]>();
const scoredUsers = users.map((user) => ({
...user,
_searchScore: scoreSearchMatch([user.name, user.email, user.username], trimmedPattern),
}));
/** Top results sorted by relevance */
return scoredUsers
.sort((a, b) => b._searchScore - a._searchScore)
.slice(0, limit)
.map((user) => {
const { _searchScore, ...userWithoutScore } = user;
return userWithoutScore;
});
};
/**
* Installs or uninstalls a plugin with a single atomic array operator, so concurrent
* install/uninstall requests cannot overwrite each other.
* @param userId - The user ID whose plugins are to be updated
* @param _plugins - Ignored; the caller's possibly stale snapshot, kept for signature compatibility
* @param pluginKey - The key of the plugin to install or uninstall
* @param action - The action to perform, 'install' or 'uninstall'
* @returns The updated user, or null if the action is invalid or the user is missing
*/
async function updateUserPlugins(
userId: string,
_plugins: string[] | undefined,
pluginKey: string,
action: 'install' | 'uninstall',
): Promise<IUser | null> {
let arrayOperation: Record<string, { plugins: string }>;
if (action === 'install') {
arrayOperation = { $addToSet: { plugins: pluginKey } };
} else if (action === 'uninstall') {
arrayOperation = { $pull: { plugins: pluginKey } };
} else {
return null;
}
const User = mongoose.models.User;
const updated = await User.findByIdAndUpdate(
userId,
{ ...arrayOperation, $unset: { expiresAt: '' } },
{ new: true, runValidators: true },
).lean<IUser>();
await invalidateAuthUserDocCache(userId);
return updated;
}
return {
findUser,
findUsers,
findOwnerContactUsers,
countUsers,
createUser,
createUserIfAbsent,
updateUser,
awaitAuthUserDocEviction,
consumeBackupCode,
claimSamlIdentity,
updateTwoFactorEnrollment,
acceptTerms,
resetTermsAcceptance,
searchUsers,
getUserById,
generateToken,
beginAgentTriggerUserDeletion,
recoverStaleAgentTriggerUserDeletion,
cancelAgentTriggerUserDeletion,
isAgentTriggerPrincipalActive,
fenceSubagentAdmission,
renewSubagentAdmission,
releaseSubagentAdmission,
isSubagentOwnerAdmissible,
deleteUserById,
updateUserPlugins,
toggleUserMemories,
updateUserStatefulCodeEnvironment,
};
}
export type UserMethods = ReturnType<typeof createUserMethods>;