Skip to content

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

45.2 KB
Raw Blame
import { Types } from 'mongoose';
import { AsyncLocalStorage } from 'async_hooks';
import { CacheKeys, PrincipalType, SystemRoles } from 'librechat-data-provider';
import type { TPrincipalSearchResult } from 'librechat-data-provider';
import type { Model, ClientSession, FilterQuery } from 'mongoose';
import type { CacheStore, IGroup, IRole, IUser } from '~/types';
import { buildUserSearchFilter, scoreSearchMatch, buildGroupSearchFilter } from '~/utils/search';
import { isValidObjectIdString } from '~/utils/objectId';
import { scopedCacheKey } from '~/config/tenantContext';
import { escapeRegExp } from '~/utils/string';

export interface UserGroupDeps {
  /** Returns the USER_PRINCIPALS cache store when principal caching is enabled. From getLogStores. */
  getCache?: (key: string) => CacheStore | undefined;
  /**
   * Notified after membership caches are invalidated so access caches derived from
   * memberships (e.g. prompt group access IDs) drop their stale entries too.
   */
  onMemberGroupsInvalidated?: () => void | Promise<void>;
}

type PendingGroupLookup = { promise: Promise<Types.ObjectId[]>; markStale: () => void };

/** Same-process dedup of concurrent cache builds, keyed by scoped member cache key. */
const pendingGroupLookups = new Map<string, PendingGroupLookup>();
const GROUP_LOCK_POLL_MS = 50;
/** Above this many member keys, invalidation clears the namespace instead of fanning out deletes. */
const INVALIDATION_CLEAR_THRESHOLD = 1000;
/** Fallback delay for the second invalidation pass when the store sets none. */
const DEFAULT_STALE_EVICTION_DELAY_MS = 3000;

const isCachedGroupId = (value: unknown): value is string =>
  typeof value === 'string' && isValidObjectIdString(value);

type DeferredInvalidation = {
  /** ALS snapshot (tenant scoping) captured where the mutation ran. */
  run: (invalidate: () => Promise<void>) => Promise<void>;
  invalidate: () => Promise<void>;
};

/** One queue and one set of lifecycle hooks per session, so many mutations in one
 * transaction cannot trip the emitter's max-listeners warning. */
const sessionInvalidations = new WeakMap<ClientSession, DeferredInvalidation[]>();
const hookedSessions = new WeakSet<ClientSession>();

async function drainSessionInvalidations(session: ClientSession): Promise<void> {
  const queue = sessionInvalidations.get(session);
  if (!queue) {
    return;
  }
  sessionInvalidations.delete(session);
  await Promise.all(queue.map((entry) => entry.run(entry.invalidate).catch(() => undefined)));
}

function hookSessionLifecycle(session: ClientSession): void {
  if (hookedSessions.has(session)) {
    return;
  }
  hookedSessions.add(session);

  const commitTransaction = session.commitTransaction.bind(session);
  session.commitTransaction = async (
    ...args: Parameters<ClientSession['commitTransaction']>
  ): Promise<void> => {
    await commitTransaction(...args);
    await drainSessionInvalidations(session);
  };

  const abortTransaction = session.abortTransaction.bind(session);
  session.abortTransaction = async (
    ...args: Parameters<ClientSession['abortTransaction']>
  ): Promise<void> => {
    try {
      await abortTransaction(...args);
    } finally {
      sessionInvalidations.delete(session);
    }
  };

  session.once('ended', () => {
    sessionInvalidations.delete(session);
  });
}

/**
 * Runs cache invalidation immediately, or defers it to commit for transactional
 * writes. Mid-transaction invalidation would let concurrent readers re-cache pre-commit
 * state with no later correction; deferring keeps the existing entry serving the
 * still-committed old memberships until the transaction commits. Aborts discard the queue.
 */
export function runAfterTransaction(
  session: ClientSession | undefined,
  invalidate: () => Promise<void>,
): Promise<void> {
  if (!session?.inTransaction()) {
    return invalidate();
  }
  const deferred: DeferredInvalidation = { run: AsyncLocalStorage.snapshot(), invalidate };
  const queue = sessionInvalidations.get(session);
  if (queue) {
    queue.push(deferred);
    return Promise.resolve();
  }
  const newQueue: DeferredInvalidation[] = [deferred];
  sessionInvalidations.set(session, newQueue);
  hookSessionLifecycle(session);
  return Promise.resolve();
}

/** Extracts member ids referenced by a group update; indeterminate when they cannot be enumerated. */
function collectMemberIdsFromGroupUpdate(update: Record<string, unknown>): {
  memberIds: string[];
  indeterminate: boolean;
} {
  if (Array.isArray(update)) {
    /** Aggregation-pipeline updates: affected members cannot be statically enumerated. */
    return { memberIds: [], indeterminate: true };
  }
  const memberIds: string[] = [];

  const collect = (value: unknown): boolean => {
    if (typeof value === 'string') {
      memberIds.push(value);
      return true;
    }
    if (value instanceof Types.ObjectId) {
      memberIds.push(value.toString());
      return true;
    }
    if (Array.isArray(value)) {
      return value.every(collect);
    }
    if (value !== null && typeof value === 'object') {
      const modifiers = value as { $each?: unknown; $in?: unknown };
      if (Array.isArray(modifiers.$each)) {
        return modifiers.$each.every(collect);
      }
      if (Array.isArray(modifiers.$in)) {
        return modifiers.$in.every(collect);
      }
    }
    return false;
  };

  let indeterminate = false;
  for (const [operator, operand] of Object.entries(update)) {
    const touchesMembers =
      operator === 'memberIds' ||
      (operand !== null &&
        typeof operand === 'object' &&
        'memberIds' in (operand as Record<string, unknown>));
    if (!touchesMembers) {
      continue;
    }
    if (operator === '$addToSet' || operator === '$push' || operator === '$pull') {
      indeterminate = !collect((operand as Record<string, unknown>).memberIds) || indeterminate;
    } else if (operator === '$pullAll') {
      const values = (operand as Record<string, unknown>).memberIds;
      indeterminate = !Array.isArray(values) || !values.every(collect) || indeterminate;
    } else {
      /** Wholesale replacement ($set, $unset, direct assignment): affected members are unknown. */
      indeterminate = true;
    }
  }

  return { memberIds, indeterminate };
}

export function createUserGroupMethods(
  mongoose: typeof import('mongoose'),
  deps: UserGroupDeps = {},
): {
  findGroupById: (
    groupId: string | Types.ObjectId,
    projection?: Record<string, 0 | 1>,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  findGroupByExternalId: (
    idOnTheSource: string,
    source?: 'entra' | 'local',
    projection?: Record<string, 0 | 1>,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  findGroupsByExternalIds: (
    idsOnTheSource: string[],
    source?: 'entra' | 'local',
    session?: ClientSession,
  ) => Promise<IGroup[]>;
  findGroupsByNamePattern: (
    namePattern: string,
    source?: 'entra' | 'local' | null,
    limit?: number,
    session?: ClientSession,
  ) => Promise<IGroup[]>;
  createGroup: (groupData: Partial<IGroup>, session?: ClientSession) => Promise<IGroup>;
  upsertGroupByExternalId: (
    idOnTheSource: string,
    source: 'entra' | 'local',
    updateData: Partial<IGroup>,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  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 }>;
  removeUserFromAllGroups: (userId: string | Types.ObjectId) => Promise<void>;
  findGroupByQuery: (
    filter: Record<string, unknown>,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  /** Sets scalar fields and reports atomically whether any value actually changed. */
  updateGroupFieldsTracked: (
    groupId: string | Types.ObjectId,
    data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,
  ) => Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null>;
  updateGroupById: (
    groupId: string | Types.ObjectId,
    data: Record<string, unknown>,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  bulkUpdateGroups: (
    filter: Record<string, unknown>,
    update: Record<string, unknown>,
    options?: { session?: ClientSession },
  ) => Promise<import('mongoose').UpdateWriteOpResult>;
  getUserPrincipals: (
    params: {
      userId: string | Types.ObjectId;
      role?: string | null;
      idOnTheSource?: string | null;
    },
    session?: ClientSession,
  ) => Promise<Array<{ principalType: PrincipalType; principalId?: string | Types.ObjectId }>>;
  searchPrincipals: (
    searchPattern: string,
    limitPerType?: number,
    typeFilter?: Array<PrincipalType.USER | PrincipalType.GROUP | PrincipalType.ROLE> | null,
    session?: ClientSession,
  ) => Promise<TPrincipalSearchResult[]>;
  calculateRelevanceScore: (item: TPrincipalSearchResult, searchPattern: string) => number;
  sortPrincipalsByRelevance: <
    T extends { _searchScore?: number; type: string; name?: string; email?: string },
  >(
    results: T[],
  ) => T[];
  listGroups: (
    filter?: {
      source?: 'local' | 'entra';
      search?: string;
      limit?: number;
      offset?: number;
    },
    session?: ClientSession,
  ) => Promise<IGroup[]>;
  countGroups: (
    filter?: { source?: 'local' | 'entra'; search?: string },
    session?: ClientSession,
  ) => Promise<number>;
  deleteGroup: (
    groupId: string | Types.ObjectId,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  removeMemberById: (
    groupId: string | Types.ObjectId,
    memberId: string,
    session?: ClientSession,
  ) => Promise<IGroup | null>;
  removeMemberByIdTracked: (
    groupId: string | Types.ObjectId,
    memberId: string,
    session?: ClientSession,
  ) => Promise<{ group: IGroup | null; changed: boolean }>;
} {
  const getPrincipalsCache = (): CacheStore | undefined =>
    deps.getCache?.(CacheKeys.USER_PRINCIPALS);

  async function queryGroupIds(
    memberId: string,
    session?: ClientSession,
    readPrimary = false,
  ): Promise<Types.ObjectId[]> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const groupsQuery = Group.find({ memberIds: memberId }, { _id: 1 });
    if (session) {
      groupsQuery.session(session);
    }
    if (readPrimary && !session) {
      /**
       * Cache builds must not capture a lagging secondary's pre-mutation state for the
       * full TTL (`secondaryPreferred` deployments); uncached reads keep the connection
       * default, where staleness is bounded by replication lag as before.
       */
      groupsQuery.read('primary');
    }
    const groups = await groupsQuery.lean<Array<Pick<IGroup, '_id'>>>();
    return groups.map((group) => group._id);
  }

  async function readCachedGroupIds(
    cache: CacheStore,
    cacheKey: string,
  ): Promise<Types.ObjectId[] | undefined> {
    try {
      const cached = await cache.get(cacheKey);
      if (Array.isArray(cached) && cached.every(isCachedGroupId)) {
        return cached.map((groupId) => new Types.ObjectId(groupId));
      }
    } catch {
      /** Cache failures must not block permission checks. */
    }
    return undefined;
  }

  /**
   * Resolves group ids for a member key (`idOnTheSource` for external users, else the
   * raw user id), cached per member. Concurrent same-process misses share one build;
   * Redis-backed stores also dedupe cross-process builds via a short-lived lock.
   * Session-scoped reads bypass the cache entirely.
   */
  async function getMemberGroupIds(
    memberId: string,
    session?: ClientSession,
  ): Promise<Types.ObjectId[]> {
    const cache = session ? undefined : getPrincipalsCache();
    if (!cache) {
      return queryGroupIds(memberId, session);
    }

    const cacheKey = scopedCacheKey(memberId);
    const fastPath = await readCachedGroupIds(cache, cacheKey);
    if (fastPath) {
      return fastPath;
    }

    const pending = pendingGroupLookups.get(cacheKey);
    if (pending) {
      return pending.promise;
    }

    /** Invalidation flips this so an in-flight build skips its now-stale cache write. */
    let stale = false;
    /**
     * The `_LOCK` prefix keeps raw lock keys disjoint from Keyv data keys
     * (always `USER_PRINCIPALS:<key>`), even for member ids ending in `:lock`.
     */
    const lockKey = `${CacheKeys.USER_PRINCIPALS}_LOCK:${cacheKey}`;
    const lookup = (async (): Promise<Types.ObjectId[]> => {
      let lockToken: string | null | undefined;
      try {
        if (cache.acquireLock) {
          let lockFailed = false;
          try {
            lockToken = await cache.acquireLock(lockKey);
          } catch {
            lockFailed = true;
          }
          if (!lockToken && !lockFailed) {
            const waitUntil = Date.now() + Math.max(cache.lockWaitMs ?? 0, 0);
            while (Date.now() < waitUntil) {
              await new Promise((resolve) => setTimeout(resolve, GROUP_LOCK_POLL_MS));
              const cached = await readCachedGroupIds(cache, cacheKey);
              if (cached) {
                return cached;
              }
              /**
               * Re-attempt the lock each tick: a holder whose write was invalidated away
               * (or that crashed) never fills the key, so take over the build as soon as
               * the lock frees instead of sleeping out the full wait budget.
               */
              try {
                lockToken = await cache.acquireLock(lockKey);
              } catch {
                break;
              }
              if (lockToken) {
                break;
              }
            }
          }
          if (lockToken) {
            /** Another process may have filled the key between the fast-path miss and the lock. */
            const cached = await readCachedGroupIds(cache, cacheKey);
            if (cached) {
              return cached;
            }
          }
        }

        const groupIds = await queryGroupIds(memberId, undefined, true);
        if (!stale) {
          try {
            await cache.set(
              cacheKey,
              groupIds.map((groupId) => groupId.toString()),
            );
          } catch {
            /** Cache failures must not block permission checks. */
          }
        }
        return groupIds;
      } finally {
        if (lockToken) {
          try {
            await cache.releaseLock?.(lockKey, lockToken);
          } catch {
            /** Lock cleanup failures expire via the lock TTL. */
          }
        }
      }
    })();

    /**
     * Registered synchronously (no await between the pending check and this set) so every
     * concurrent same-process caller attaches to this single flow instead of starting its own.
     */
    pendingGroupLookups.set(cacheKey, {
      promise: lookup,
      markStale: () => {
        stale = true;
      },
    });
    try {
      return await lookup;
    } finally {
      if (pendingGroupLookups.get(cacheKey)?.promise === lookup) {
        pendingGroupLookups.delete(cacheKey);
      }
    }
  }

  async function dropMemberKeys(cache: CacheStore, cacheKeys: Set<string>): Promise<void> {
    for (const cacheKey of cacheKeys) {
      const pending = pendingGroupLookups.get(cacheKey);
      if (pending) {
        pending.markStale();
        pendingGroupLookups.delete(cacheKey);
      }
    }
    try {
      await Promise.all([...cacheKeys].map((cacheKey) => cache.delete?.(cacheKey)));
    } catch {
      /** Cache failures must not block membership updates. */
    }
  }

  /**
   * Cross-process builds cannot see this process's stale flags, so a build in another
   * container that read pre-mutation state can re-cache it after the first delete.
   * A delayed second pass evicts such rewrites on stores shared across processes,
   * independent of build locking; the store supplies the delay budget.
   */
  function scheduleSecondInvalidation(cache: CacheStore, secondPass: () => Promise<void>): void {
    if (!cache.crossProcess) {
      return;
    }
    const graceMs = Math.max(cache.staleEvictionDelayMs ?? DEFAULT_STALE_EVICTION_DELAY_MS, 0);
    const timer = setTimeout(() => {
      secondPass().catch(() => undefined);
    }, graceMs);
    timer.unref?.();
  }

  /**
   * Drops cached group memberships for the given member keys (both base and
   * tenant-scoped variants) after a membership mutation. In-flight builds are
   * marked stale (skipping their cache write) and unregistered so later reads
   * start a fresh build instead of joining a pre-mutation one. Failures are
   * non-fatal; the cache TTL bounds any residual staleness (e.g. mutations
   * running under a different tenant context than the member's reads).
   */
  /**
   * Notifies dependent access caches after memberships have been evicted, never
   * before: a dependent rebuild that runs first would read the stale membership
   * and cache its derived IDs under the freshly bumped generation, surviving
   * the membership eviction that should have prevented them.
   */
  const notifyMemberGroupsInvalidated = async (): Promise<void> => {
    try {
      await deps.onMemberGroupsInvalidated?.();
    } catch {
      /** Dependent cache invalidation must not block membership updates. */
    }
  };

  async function invalidateMemberGroupsCache(
    memberIds: Array<string | Types.ObjectId | undefined | null>,
  ): Promise<void> {
    const cache = getPrincipalsCache();
    if (!cache?.delete) {
      await notifyMemberGroupsInvalidated();
      return;
    }
    const cacheKeys = new Set<string>();
    for (const memberId of memberIds) {
      if (!memberId) {
        continue;
      }
      const baseKey = memberId.toString();
      cacheKeys.add(baseKey);
      cacheKeys.add(scopedCacheKey(baseKey));
    }
    if (cacheKeys.size === 0) {
      return;
    }
    if (cacheKeys.size > INVALIDATION_CLEAR_THRESHOLD && cache.clear) {
      return clearMemberGroupsCache();
    }
    const evict = async (): Promise<void> => {
      await dropMemberKeys(cache, cacheKeys);
      await notifyMemberGroupsInvalidated();
    };
    await evict();
    scheduleSecondInvalidation(cache, evict);
  }

  /** Clears the whole membership cache when affected members cannot be enumerated. */
  async function clearMemberGroupsCache(): Promise<void> {
    const cache = getPrincipalsCache();
    if (!cache?.clear) {
      await notifyMemberGroupsInvalidated();
      return;
    }
    const clearAll = async (): Promise<void> => {
      for (const pending of pendingGroupLookups.values()) {
        pending.markStale();
      }
      pendingGroupLookups.clear();
      try {
        await cache.clear?.();
      } catch {
        /** Cache failures must not block membership updates. */
      }
      await notifyMemberGroupsInvalidated();
    };
    await clearAll();
    scheduleSecondInvalidation(cache, clearAll);
  }

  /**
   * Find a group by its ID
   * @param groupId - The group ID
   * @param projection - Optional projection of fields to return
   * @param session - Optional MongoDB session for transactions
   * @returns The group document or null if not found
   */
  async function findGroupById(
    groupId: string | Types.ObjectId,
    projection: Record<string, 0 | 1> = {},
    session?: ClientSession,
  ): Promise<IGroup | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const query = Group.findOne({ _id: groupId }, projection);
    if (session) {
      query.session(session);
    }
    return await query.lean<IGroup>();
  }

  /**
   * Find a group by its external ID (e.g., Entra ID)
   * @param idOnTheSource - The external ID
   * @param source - The source ('entra' or 'local')
   * @param projection - Optional projection of fields to return
   * @param session - Optional MongoDB session for transactions
   * @returns The group document or null if not found
   */
  async function findGroupByExternalId(
    idOnTheSource: string,
    source: 'entra' | 'local' = 'entra',
    projection: Record<string, 0 | 1> = {},
    session?: ClientSession,
  ): Promise<IGroup | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const query = Group.findOne({ idOnTheSource, source }, projection);
    if (session) {
      query.session(session);
    }
    return await query.lean<IGroup>();
  }

  /**
   * Find multiple groups by their external IDs (e.g., Entra IDs) in a single query
   * @param idsOnTheSource - Array of external IDs
   * @param source - The source ('entra' or 'local')
   * @param session - Optional MongoDB session for transactions
   * @returns Array of group documents
   */
  async function findGroupsByExternalIds(
    idsOnTheSource: string[],
    source: 'entra' | 'local' = 'entra',
    session?: ClientSession,
  ): Promise<IGroup[]> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const query = Group.find(
      { idOnTheSource: { $in: idsOnTheSource }, source },
      { idOnTheSource: 1, _id: 0 },
    );
    if (session) {
      query.session(session);
    }
    return await query.lean<IGroup[]>();
  }

  /**
   * Find groups by word prefix of name or email (see `buildGroupSearchFilter`)
   * @param namePattern - The name pattern to search for
   * @param source - Optional source filter ('entra', 'local', or null for all)
   * @param limit - Maximum number of results to return
   * @param session - Optional MongoDB session for transactions
   * @returns Array of matching groups
   */
  async function findGroupsByNamePattern(
    namePattern: string,
    source: 'entra' | 'local' | null = null,
    limit: number = 20,
    session?: ClientSession,
  ): Promise<IGroup[]> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const filter = buildGroupSearchFilter(namePattern);
    if (!filter) {
      return [];
    }
    const query: Record<string, unknown> = { ...filter };

    if (source) {
      query.source = source;
    }

    const dbQuery = Group.find(query).limit(limit);
    if (session) {
      dbQuery.session(session);
    }
    return await dbQuery.lean<IGroup[]>();
  }

  /**
   * Create a new group
   * @param groupData - Group data including name, source, and optional idOnTheSource
   * @param session - Optional MongoDB session for transactions
   * @returns The created group
   */
  async function createGroup(groupData: Partial<IGroup>, session?: ClientSession): Promise<IGroup> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const options = session ? { session } : {};
    const group = await Group.create([groupData], options).then((groups) => groups[0]);
    await runAfterTransaction(session, () =>
      invalidateMemberGroupsCache(groupData.memberIds ?? []),
    );
    return group;
  }

  /**
   * Update or create a group by external ID
   * @param idOnTheSource - The external ID
   * @param source - The source ('entra' or 'local')
   * @param updateData - Data to update or set if creating
   * @param session - Optional MongoDB session for transactions
   * @returns The updated or created group
   */
  async function upsertGroupByExternalId(
    idOnTheSource: string,
    source: 'entra' | 'local',
    updateData: Partial<IGroup>,
    session?: ClientSession,
  ): Promise<IGroup | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const options = {
      new: true,
      upsert: true,
      ...(session ? { session } : {}),
    };

    if (updateData.memberIds === undefined) {
      return await Group.findOneAndUpdate({ idOnTheSource, source }, { $set: updateData }, options);
    }
    /** Atomic pre-image (`new: false`) so members added concurrently before the $set are invalidated too. */
    const previous = await Group.findOneAndUpdate(
      { idOnTheSource, source },
      { $set: updateData },
      { ...options, new: false },
    ).lean<IGroup>();
    await runAfterTransaction(session, () =>
      invalidateMemberGroupsCache([
        ...(previous?.memberIds ?? []),
        ...(updateData.memberIds ?? []),
      ]),
    );
    return await findGroupByExternalId(idOnTheSource, source, {}, session);
  }

  /**
   * Add a user to a group
   * Only updates Group.memberIds (one-way relationship)
   * Note: memberIds stores idOnTheSource values, not ObjectIds
   *
   * @param userId - The user ID
   * @param groupId - The group ID to add
   * @param session - Optional MongoDB session for transactions
   * @returns The user and updated group documents
   */
  async function addUserToGroup(
    userId: string | Types.ObjectId,
    groupId: string | Types.ObjectId,
    session?: ClientSession,
  ): Promise<{ user: IUser; group: IGroup | null; changed: boolean }> {
    const User = mongoose.models.User as Model<IUser>;
    const Group = mongoose.models.Group as Model<IGroup>;

    const options = { new: true, ...(session ? { session } : {}) };

    const user = await User.findById(userId, 'idOnTheSource', options).lean<{
      idOnTheSource?: string;
      _id: Types.ObjectId;
    }>();
    if (!user) {
      throw new Error(`User not found: ${userId}`);
    }

    const userIdOnTheSource = user.idOnTheSource || userId.toString();
    /** The filter makes the update match only when the member is absent, so a match
     * is exactly one real change even when identical requests overlap. */
    const changedGroup = await Group.findOneAndUpdate(
      { _id: groupId, memberIds: { $ne: userIdOnTheSource } },
      { $addToSet: { memberIds: userIdOnTheSource } },
      options,
    ).lean<IGroup>();
    const updatedGroup =
      changedGroup ??
      (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());
    await runAfterTransaction(session, () => invalidateMemberGroupsCache([userIdOnTheSource]));

    return { user: user as IUser, group: updatedGroup, changed: changedGroup != null };
  }

  /**
   * Remove a user from a group
   * Only updates Group.memberIds (one-way relationship)
   * Note: memberIds stores idOnTheSource values, not ObjectIds
   *
   * @param userId - The user ID
   * @param groupId - The group ID to remove
   * @param session - Optional MongoDB session for transactions
   * @returns The user and updated group documents
   */
  async function removeUserFromGroup(
    userId: string | Types.ObjectId,
    groupId: string | Types.ObjectId,
    session?: ClientSession,
  ): Promise<{ user: IUser; group: IGroup | null; changed: boolean }> {
    const User = mongoose.models.User as Model<IUser>;
    const Group = mongoose.models.Group as Model<IGroup>;

    const options = { new: true, ...(session ? { session } : {}) };

    const user = await User.findById(userId, 'idOnTheSource', options).lean<{
      idOnTheSource?: string;
      _id: Types.ObjectId;
    }>();
    if (!user) {
      throw new Error(`User not found: ${userId}`);
    }

    const userIdOnTheSource = user.idOnTheSource || userId.toString();
    const changedGroup = await Group.findOneAndUpdate(
      { _id: groupId, memberIds: userIdOnTheSource },
      { $pullAll: { memberIds: [userIdOnTheSource] } },
      options,
    ).lean<IGroup>();
    const updatedGroup =
      changedGroup ??
      (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());
    await runAfterTransaction(session, () => invalidateMemberGroupsCache([userIdOnTheSource]));

    return { user: user as IUser, group: updatedGroup, changed: changedGroup != null };
  }

  /**
   * Get a list of all principal identifiers for a user (user ID + group IDs + public).
   * For use in permission checks.
   *
   * Tenant filtering for group memberships is handled automatically by the
   * `applyTenantIsolation` Mongoose plugin on the Group schema. The
   * `tenantContextMiddleware` (chained by `requireJwtAuth` after passport auth)
   * sets the ALS context, so the `memberIds` group query below is scoped to the
   * requesting tenant. No explicit tenantId parameter is needed.
   *
   * IMPORTANT: This relies on the ALS tenant context being active. If this
   * function is called outside a request context (e.g. startup, background jobs),
   * group queries will be unscoped. In strict mode, the Mongoose plugin will
   * reject such queries.
   *
   * Ref: #12091 (resolved by tenant context middleware in requireJwtAuth)
   *
   * Pass `role` and `idOnTheSource` from the already-loaded request user to skip
   * the fallback user lookup entirely, reducing the hot path to a single indexed,
   * `_id`-projected group query. `idOnTheSource: null` means "known to be absent"
   * (local user) and also avoids the lookup; only `undefined` triggers it.
   *
   * Group memberships are additionally cached per member key (USER_PRINCIPALS
   * namespace) when a cache is injected; membership mutations in this module
   * invalidate the affected keys. Role resolution is never cached.
   *
   * @param params - Parameters object
   * @param params.userId - The user ID
   * @param params.role - Optional user role (looked up when `undefined`)
   * @param params.idOnTheSource - Optional external member id (looked up when `undefined`)
   * @param session - Optional MongoDB session for transactions
   * @returns Array of principal objects with type and id
   */
  async function getUserPrincipals(
    params: {
      userId: string | Types.ObjectId;
      role?: string | null;
      idOnTheSource?: string | null;
    },
    session?: ClientSession,
  ): Promise<Array<{ principalType: PrincipalType; principalId?: string | Types.ObjectId }>> {
    const { userId, role, idOnTheSource } = params;
    /** `userId` must be an `ObjectId` for USER principal since ACL entries store `ObjectId`s */
    const userObjectId = typeof userId === 'string' ? new Types.ObjectId(userId) : userId;
    const principals: Array<{
      principalType: PrincipalType;
      principalId?: string | Types.ObjectId;
    }> = [{ principalType: PrincipalType.USER, principalId: userObjectId }];

    let userRole = role;
    let memberIdOnTheSource = idOnTheSource;

    /** Single fallback lookup, only for whichever identity fields the caller omitted. */
    if (userRole === undefined || memberIdOnTheSource === undefined) {
      const User = mongoose.models.User as Model<IUser>;
      const query = User.findById(userId).select('role idOnTheSource');
      if (session) {
        query.session(session);
      }
      const user = await query.lean<Pick<IUser, 'role' | 'idOnTheSource'>>();
      if (userRole === undefined) {
        userRole = user?.role;
      }
      if (memberIdOnTheSource === undefined) {
        memberIdOnTheSource = user?.idOnTheSource ?? null;
      }
    }

    if (userRole && userRole.trim()) {
      principals.push({ principalType: PrincipalType.ROLE, principalId: userRole });
    }

    /** `memberIds` stores `idOnTheSource` for external users, else the raw user id. */
    const memberId = memberIdOnTheSource || userId.toString();
    const groupIds = await getMemberGroupIds(memberId, session);
    for (const groupId of groupIds) {
      principals.push({ principalType: PrincipalType.GROUP, principalId: groupId });
    }

    principals.push({ principalType: PrincipalType.PUBLIC });

    return principals;
  }

  /**
   * Calculate relevance score for a search result
   * @param item - The search result item
   * @param searchPattern - The search pattern
   * @returns Relevance score (0-100)
   */
  function calculateRelevanceScore(item: TPrincipalSearchResult, searchPattern: string): number {
    /** The fields each search matches on; a group's description is not one of them */
    const values =
      item.type === PrincipalType.USER
        ? [item.name, item.email, item.username]
        : [item.name, item.email];
    return scoreSearchMatch(values, searchPattern);
  }

  /**
   * Sort principals by relevance score and type priority
   * @param results - Array of results with _searchScore property
   * @returns Sorted array
   */
  function sortPrincipalsByRelevance<
    T extends { _searchScore?: number; type: string; name?: string; email?: string },
  >(results: T[]): T[] {
    return results.sort((a, b) => {
      if (b._searchScore !== a._searchScore) {
        return (b._searchScore || 0) - (a._searchScore || 0);
      }
      if (a.type !== b.type) {
        return a.type === PrincipalType.USER ? -1 : 1;
      }
      const aName = a.name || a.email || '';
      const bName = b.name || b.email || '';
      return aName.localeCompare(bName);
    });
  }

  /**
   * Transform user object to TPrincipalSearchResult format
   * @param user - User object from database
   * @returns Transformed user result
   */
  function transformUserToTPrincipalSearchResult(
    user: Pick<
      IUser,
      'id' | 'name' | 'email' | 'username' | 'avatar' | 'provider' | 'idOnTheSource' | 'role'
    >,
  ): TPrincipalSearchResult {
    return {
      id: user.id,
      type: PrincipalType.USER,
      name: user.name || user.email,
      email: user.email,
      username: user.username,
      avatar: user.avatar,
      provider: user.provider,
      source: 'local',
      idOnTheSource: user.idOnTheSource || user.id,
      isAdmin: user.role === SystemRoles.ADMIN,
    };
  }

  /**
   * Transform group object to TPrincipalSearchResult format
   * @param group - Group object from database
   * @returns Transformed group result
   */
  function transformGroupToTPrincipalSearchResult(group: IGroup): TPrincipalSearchResult {
    return {
      id: group._id?.toString(),
      type: PrincipalType.GROUP,
      name: group.name,
      email: group.email,
      avatar: group.avatar,
      description: group.description,
      source: group.source || 'local',
      memberCount: group.memberIds ? group.memberIds.length : 0,
      idOnTheSource: group.idOnTheSource || group._id?.toString(),
    };
  }

  /**
   * Search for principals: users and groups by word prefix (see `buildSearchTokenFilter`),
   * roles by name
   * Returns combined results in TPrincipalSearchResult format without sorting
   * @param searchPattern - The pattern to search for
   * @param limitPerType - Maximum number of results to return
   * @param typeFilter - Optional array of types to filter by, or null for all types
   * @param session - Optional MongoDB session for transactions
   * @returns Array of principals in TPrincipalSearchResult format
   */
  async function searchPrincipals(
    searchPattern: string,
    limitPerType: number = 10,
    typeFilter: Array<PrincipalType.USER | PrincipalType.GROUP | PrincipalType.ROLE> | null = null,
    session?: ClientSession,
  ): Promise<TPrincipalSearchResult[]> {
    if (!searchPattern || searchPattern.trim().length === 0) {
      return [];
    }

    const trimmedPattern = searchPattern.trim();
    const escapedPattern = escapeRegExp(trimmedPattern);
    const promises: Promise<TPrincipalSearchResult[]>[] = [];

    const userFilter = buildUserSearchFilter(trimmedPattern);
    if (userFilter && (!typeFilter || typeFilter.includes(PrincipalType.USER))) {
      const userFields = 'name email username avatar provider idOnTheSource role';
      const User = mongoose.models.User as Model<IUser>;
      const userQuery = User.find(userFilter).select(userFields).limit(limitPerType);

      if (session) {
        userQuery.session(session);
      }

      promises.push(
        userQuery.lean<IUser[]>().then((users) =>
          users.map((user) =>
            transformUserToTPrincipalSearchResult({
              id: user._id?.toString() || '',
              name: user.name,
              email: user.email,
              username: user.username,
              avatar: user.avatar,
              provider: user.provider,
              idOnTheSource: user.idOnTheSource,
              role: user.role,
            }),
          ),
        ),
      );
    } else {
      promises.push(Promise.resolve([]));
    }

    if (!typeFilter || typeFilter.includes(PrincipalType.GROUP)) {
      promises.push(
        findGroupsByNamePattern(trimmedPattern, null, limitPerType, session).then((groups) =>
          groups.map(transformGroupToTPrincipalSearchResult),
        ),
      );
    } else {
      promises.push(Promise.resolve([]));
    }

    if (!typeFilter || typeFilter.includes(PrincipalType.ROLE)) {
      const Role = mongoose.models.Role as Model<IRole>;
      if (Role) {
        const regex = new RegExp(escapedPattern, 'i');
        const roleQuery = Role.find({ name: regex }).select('name').limit(limitPerType);

        if (session) {
          roleQuery.session(session);
        }

        promises.push(
          roleQuery.lean<Array<{ name: string }>>().then((roles) =>
            roles.map((role) => ({
              /** Role name as ID */
              id: role.name,
              type: PrincipalType.ROLE,
              name: role.name,
              source: 'local' as const,
              idOnTheSource: role.name,
              isAdmin: role.name === SystemRoles.ADMIN,
            })),
          ),
        );
      }
    } else {
      promises.push(Promise.resolve([]));
    }

    const results = await Promise.all(promises);
    const combined = results.flat();
    return combined;
  }

  /**
   * Removes a user from all groups they belong to.
   * @param userId - The user ID (or ObjectId) of the member to remove
   */
  async function removeUserFromAllGroups(userId: string | Types.ObjectId): Promise<void> {
    const Group = mongoose.models.Group as Model<IGroup>;
    await Group.updateMany({ memberIds: userId }, { $pullAll: { memberIds: [userId] } });
    await invalidateMemberGroupsCache([userId]);
  }

  /**
   * Finds a single group matching the given filter.
   * @param filter - MongoDB filter query
   */
  async function findGroupByQuery(
    filter: Record<string, unknown>,
    session?: ClientSession,
  ): Promise<IGroup | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const query = Group.findOne(filter);
    if (session) {
      query.session(session);
    }
    return query.lean<IGroup>();
  }

  /**
   * Updates a group by its ID.
   * @param groupId - The group's ObjectId
   * @param data - Fields to set via $set
   */
  async function updateGroupFieldsTracked(
    groupId: string | Types.ObjectId,
    data: Partial<Pick<IGroup, 'name' | 'description' | 'email' | 'avatar'>>,
  ): Promise<{ group: IGroup; changed: boolean; changedFields: string[] } | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const entries = Object.entries(data);
    const unchanged = async () => {
      const current = await Group.findById(groupId).lean<IGroup>();
      return current ? { group: current, changed: false, changedFields: [] as string[] } : null;
    };
    if (entries.length === 0) {
      return unchanged();
    }
    /** The filter matches only a group that differs, and the pre-image names exactly the fields
     * this write changed, so overlapping identical requests record one change. */
    const previous = await Group.findOneAndUpdate(
      { _id: groupId, $or: entries.map(([key, value]) => ({ [key]: { $ne: value } })) },
      { $set: data },
      { new: false },
    ).lean<IGroup>();
    if (!previous) {
      return unchanged();
    }
    const changedFields = entries
      .filter(([key, value]) => (previous as unknown as Record<string, unknown>)[key] !== value)
      .map(([key]) => key);
    const group = (await Group.findById(groupId).lean<IGroup>()) ?? previous;
    return { group, changed: true, changedFields };
  }

  async function updateGroupById(
    groupId: string | Types.ObjectId,
    data: Record<string, unknown>,
    session?: ClientSession,
  ): Promise<IGroup | null> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const options = { new: true, ...(session ? { session } : {}) };
    if (data.memberIds === undefined) {
      return Group.findByIdAndUpdate(groupId, { $set: data }, options).lean<IGroup>();
    }
    /** Atomic pre-image (`new: false`) so members added concurrently before the $set are invalidated too. */
    const previous = await Group.findByIdAndUpdate(
      groupId,
      { $set: data },
      {
        ...options,
        new: false,
      },
    ).lean<IGroup>();
    const nextMemberIds = Array.isArray(data.memberIds)
      ? data.memberIds.filter(
          (memberId): memberId is string | Types.ObjectId =>
            typeof memberId === 'string' || memberId instanceof Types.ObjectId,
        )
      : [];
    await runAfterTransaction(session, () =>
      invalidateMemberGroupsCache([...(previous?.memberIds ?? []), ...nextMemberIds]),
    );
    return previous ? await findGroupById(groupId, {}, session) : null;
  }

  /**
   * Bulk-updates groups matching a filter.
   * @param filter - MongoDB filter query
   * @param update - Update operations
   * @param options - Optional query options (e.g., { session })
   */
  async function bulkUpdateGroups(
    filter: Record<string, unknown>,
    update: Record<string, unknown>,
    options?: { session?: ClientSession },
  ): Promise<import('mongoose').UpdateWriteOpResult> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const result = await Group.updateMany(filter, update, options || {});
    if (result.modifiedCount === 0 && result.upsertedCount === 0) {
      return result;
    }
    const { memberIds, indeterminate } = collectMemberIdsFromGroupUpdate(update);
    if (indeterminate) {
      await runAfterTransaction(options?.session, () => clearMemberGroupsCache());
    } else if (memberIds.length > 0) {
      await runAfterTransaction(options?.session, () => invalidateMemberGroupsCache(memberIds));
    }
    return result;
  }

  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<IGroup[]>();
  }

  /**
   * 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 } : {};
    const group = await Group.findByIdAndDelete(groupId, options).lean<IGroup>();
    await runAfterTransaction(session, () => invalidateMemberGroupsCache(group?.memberIds ?? []));
    return group;
  }

  /**
   * 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 removeMemberByIdTracked(
    groupId: string | Types.ObjectId,
    memberId: string,
    session?: ClientSession,
  ): Promise<{ group: IGroup | null; changed: boolean }> {
    const Group = mongoose.models.Group as Model<IGroup>;
    const options = { new: true, ...(session ? { session } : {}) };
    const changedGroup = await Group.findOneAndUpdate(
      { _id: groupId, memberIds: memberId },
      { $pull: { memberIds: memberId } },
      options,
    ).lean<IGroup>();
    const group =
      changedGroup ??
      (await Group.findById(groupId, null, session ? { session } : {}).lean<IGroup>());
    await runAfterTransaction(session, () => invalidateMemberGroupsCache([memberId]));
    return { group, changed: changedGroup != null };
  }

  async function removeMemberById(
    groupId: string | Types.ObjectId,
    memberId: string,
    session?: ClientSession,
  ): Promise<IGroup | null> {
    return (await removeMemberByIdTracked(groupId, memberId, session)).group;
  }

  return {
    findGroupById,
    findGroupByExternalId,
    findGroupsByExternalIds,
    findGroupsByNamePattern,
    createGroup,
    upsertGroupByExternalId,
    addUserToGroup,
    removeUserFromGroup,
    removeUserFromAllGroups,
    findGroupByQuery,
    updateGroupById,
    updateGroupFieldsTracked,
    bulkUpdateGroups,
    getUserPrincipals,
    searchPrincipals,
    calculateRelevanceScore,
    sortPrincipalsByRelevance,
    listGroups,
    countGroups,
    deleteGroup,
    removeMemberById,
    removeMemberByIdTracked,
  };
}

export type UserGroupMethods = ReturnType<typeof createUserGroupMethods>;