🔐 feat: Granular Role-based Permissions + Entra ID Group Discovery (#7804)

WIP: pre-granular-permissions commit

feat: Add category and support contact fields to Agent schema and UI components

Revert "feat: Add category and support contact fields to Agent schema and UI components"

This reverts commit c43a52b4c9.

Fix: Update import for renderHook in useAgentCategories.spec.tsx

fix: Update icon rendering in AgentCategoryDisplay tests to use empty spans

refactor: Improve category synchronization logic and clean up AgentConfig component

refactor: Remove unused UI flow translations from translation.json

feat: agent marketplace features

🔐 feat: Granular Role-based Permissions + Entra ID Group Discovery (#7804)

api/server/services/AppService.interface.spec.js

@@ -1,5 +1,6 @@
 jest.mock('~/models', () => ({
   initializeRoles: jest.fn(),
+  seedDefaultRoles: jest.fn(),
 }));
 jest.mock('~/models/Role', () => ({
   updateAccessPermissions: jest.fn(),

api/server/services/AppService.js

@@ -16,6 +16,7 @@ const {
 const { azureAssistantsDefaults, assistantsConfigSetup } = require('./start/assistants');
 const { initializeAzureBlobService } = require('./Files/Azure/initialize');
 const { initializeFirebase } = require('./Files/Firebase/initialize');
+const { seedDefaultRoles, initializeRoles } = require('~/models');
 const loadCustomConfig = require('./Config/loadCustomConfig');
 const handleRateLimits = require('./Config/handleRateLimits');
 const { loadDefaultInterface } = require('./start/interface');
@@ -25,7 +26,6 @@ const { processModelSpecs } = require('./start/modelSpecs');
 const { initializeS3 } = require('./Files/S3/initialize');
 const { loadAndFormatTools } = require('./ToolService');
 const { isEnabled } = require('~/server/utils');
-const { initializeRoles } = require('~/models');
 const { setCachedTools } = require('./Config');
 const paths = require('~/config/paths');
 
@@ -36,6 +36,7 @@ const paths = require('~/config/paths');
  */
 const AppService = async (app) => {
   await initializeRoles();
+  await seedDefaultRoles();
   /** @type {TCustomConfig} */
   const config = (await loadCustomConfig()) ?? {};
   const configDefaults = getConfigDefaults();

api/server/services/AppService.spec.js

@@ -28,6 +28,7 @@ jest.mock('./Files/Firebase/initialize', () => ({
 }));
 jest.mock('~/models', () => ({
   initializeRoles: jest.fn(),
+  seedDefaultRoles: jest.fn(),
 }));
 jest.mock('~/models/Role', () => ({
   updateAccessPermissions: jest.fn(),

api/server/services/GraphApiService.js

@@ -0,0 +1,525 @@
+const client = require('openid-client');
+const { isEnabled } = require('@librechat/api');
+const { logger } = require('@librechat/data-schemas');
+const { CacheKeys } = require('librechat-data-provider');
+const { Client } = require('@microsoft/microsoft-graph-client');
+const { getOpenIdConfig } = require('~/strategies/openidStrategy');
+const getLogStores = require('~/cache/getLogStores');
+
+/**
+ * @import { TPrincipalSearchResult, TGraphPerson, TGraphUser, TGraphGroup, TGraphPeopleResponse, TGraphUsersResponse, TGraphGroupsResponse } from 'librechat-data-provider'
+ */
+
+/**
+ * Checks if Entra ID principal search feature is enabled based on environment variables and user authentication
+ * @param {Object} user - User object from request
+ * @param {string} user.provider - Authentication provider
+ * @param {string} user.openidId - OpenID subject identifier
+ * @returns {boolean} True if Entra ID principal search is enabled and user is authenticated via OpenID
+ */
+const entraIdPrincipalFeatureEnabled = (user) => {
+  return (
+    isEnabled(process.env.USE_ENTRA_ID_FOR_PEOPLE_SEARCH) &&
+    isEnabled(process.env.OPENID_REUSE_TOKENS) &&
+    user?.provider === 'openid' &&
+    user?.openidId
+  );
+};
+
+/**
+ * Creates a Microsoft Graph client with on-behalf-of token exchange
+ * @param {string} accessToken - OpenID Connect access token from user
+ * @param {string} sub - Subject identifier from token claims
+ * @returns {Promise<Client>} Authenticated Graph API client
+ */
+const createGraphClient = async (accessToken, sub) => {
+  try {
+    // Reason: Use existing OpenID configuration and token exchange pattern from openidStrategy.js
+    const openidConfig = getOpenIdConfig();
+    const exchangedToken = await exchangeTokenForGraphAccess(openidConfig, accessToken, sub);
+
+    const graphClient = Client.init({
+      authProvider: (done) => {
+        done(null, exchangedToken);
+      },
+    });
+
+    return graphClient;
+  } catch (error) {
+    logger.error('[createGraphClient] Error creating Graph client:', error);
+    throw error;
+  }
+};
+
+/**
+ * Exchange OpenID token for Graph API access using on-behalf-of flow
+ * Similar to exchangeAccessTokenIfNeeded in openidStrategy.js but for Graph scopes
+ * @param {Configuration} config - OpenID configuration
+ * @param {string} accessToken - Original access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<string>} Graph API access token
+ */
+const exchangeTokenForGraphAccess = async (config, accessToken, sub) => {
+  try {
+    const tokensCache = getLogStores(CacheKeys.OPENID_EXCHANGED_TOKENS);
+    const cacheKey = `${sub}:graph`;
+
+    const cachedToken = await tokensCache.get(cacheKey);
+    if (cachedToken) {
+      return cachedToken.access_token;
+    }
+
+    const graphScopes = process.env.OPENID_GRAPH_SCOPES || 'User.Read,People.Read,Group.Read.All';
+    const scopeString = graphScopes
+      .split(',')
+      .map((scope) => `https://graph.microsoft.com/${scope}`)
+      .join(' ');
+
+    const grantResponse = await client.genericGrantRequest(
+      config,
+      'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      {
+        scope: scopeString,
+        assertion: accessToken,
+        requested_token_use: 'on_behalf_of',
+      },
+    );
+
+    await tokensCache.set(
+      cacheKey,
+      {
+        access_token: grantResponse.access_token,
+      },
+      grantResponse.expires_in * 1000,
+    );
+
+    return grantResponse.access_token;
+  } catch (error) {
+    logger.error('[exchangeTokenForGraphAccess] Token exchange failed:', error);
+    throw error;
+  }
+};
+
+/**
+ * Search for principals (people and groups) using Microsoft Graph API
+ * Uses searchContacts first, then searchUsers and searchGroups to fill remaining slots
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} query - Search query string
+ * @param {string} type - Type filter ('users', 'groups', or 'all')
+ * @param {number} limit - Maximum number of results
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of principal search results
+ */
+const searchEntraIdPrincipals = async (accessToken, sub, query, type = 'all', limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+    const graphClient = await createGraphClient(accessToken, sub);
+    let allResults = [];
+
+    if (type === 'users' || type === 'all') {
+      const contactResults = await searchContacts(graphClient, query, limit);
+      allResults.push(...contactResults);
+    }
+    if (allResults.length >= limit) {
+      return allResults.slice(0, limit);
+    }
+
+    if (type === 'users') {
+      const userResults = await searchUsers(graphClient, query, limit);
+      allResults.push(...userResults);
+    } else if (type === 'groups') {
+      const groupResults = await searchGroups(graphClient, query, limit);
+      allResults.push(...groupResults);
+    } else if (type === 'all') {
+      const [userResults, groupResults] = await Promise.all([
+        searchUsers(graphClient, query, limit),
+        searchGroups(graphClient, query, limit),
+      ]);
+
+      allResults.push(...userResults, ...groupResults);
+    }
+
+    const seenIds = new Set();
+    const uniqueResults = allResults.filter((result) => {
+      if (seenIds.has(result.idOnTheSource)) {
+        return false;
+      }
+      seenIds.add(result.idOnTheSource);
+      return true;
+    });
+
+    return uniqueResults.slice(0, limit);
+  } catch (error) {
+    logger.error('[searchEntraIdPrincipals] Error searching principals:', error);
+    return [];
+  }
+};
+
+/**
+ * Get current user's Entra ID group memberships from Microsoft Graph
+ * Uses /me/memberOf endpoint to get groups the user is a member of
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Array<string>>} Array of group ID strings (GUIDs)
+ */
+const getUserEntraGroups = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+
+    const groupsResponse = await graphClient.api('/me/memberOf').select('id').get();
+
+    return (groupsResponse.value || []).map((group) => group.id);
+  } catch (error) {
+    logger.error('[getUserEntraGroups] Error fetching user groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Get current user's owned Entra ID groups from Microsoft Graph
+ * Uses /me/ownedObjects/microsoft.graph.group endpoint to get groups the user owns
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Array<string>>} Array of group ID strings (GUIDs)
+ */
+const getUserOwnedEntraGroups = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+
+    const groupsResponse = await graphClient
+      .api('/me/ownedObjects/microsoft.graph.group')
+      .select('id')
+      .get();
+
+    return (groupsResponse.value || []).map((group) => group.id);
+  } catch (error) {
+    logger.error('[getUserOwnedEntraGroups] Error fetching user owned groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Get group members from Microsoft Graph API
+ * Recursively fetches all members using pagination (@odata.nextLink)
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} groupId - Entra ID group object ID
+ * @returns {Promise<Array>} Array of member IDs (idOnTheSource values)
+ */
+const getGroupMembers = async (accessToken, sub, groupId) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const allMembers = [];
+    let nextLink = `/groups/${groupId}/members`;
+
+    while (nextLink) {
+      const membersResponse = await graphClient.api(nextLink).select('id').top(999).get();
+
+      const members = membersResponse.value || [];
+      allMembers.push(...members.map((member) => member.id));
+
+      nextLink = membersResponse['@odata.nextLink']
+        ? membersResponse['@odata.nextLink'].split('/v1.0')[1]
+        : null;
+    }
+
+    return allMembers;
+  } catch (error) {
+    logger.error('[getGroupMembers] Error fetching group members:', error);
+    return [];
+  }
+};
+/**
+ * Get group owners from Microsoft Graph API
+ * Recursively fetches all owners using pagination (@odata.nextLink)
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} groupId - Entra ID group object ID
+ * @returns {Promise<Array>} Array of owner IDs (idOnTheSource values)
+ */
+const getGroupOwners = async (accessToken, sub, groupId) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const allOwners = [];
+    let nextLink = `/groups/${groupId}/owners`;
+
+    while (nextLink) {
+      const ownersResponse = await graphClient.api(nextLink).select('id').top(999).get();
+
+      const owners = ownersResponse.value || [];
+      allOwners.push(...owners.map((member) => member.id));
+
+      nextLink = ownersResponse['@odata.nextLink']
+        ? ownersResponse['@odata.nextLink'].split('/v1.0')[1]
+        : null;
+    }
+
+    return allOwners;
+  } catch (error) {
+    logger.error('[getGroupOwners] Error fetching group owners:', error);
+    return [];
+  }
+};
+/**
+ * Search for contacts (users only) using Microsoft Graph /me/people endpoint
+ * Returns mapped TPrincipalSearchResult objects for users only
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped user contact results
+ */
+const searchContacts = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+    if (
+      process.env.OPENID_GRAPH_SCOPES &&
+      !process.env.OPENID_GRAPH_SCOPES.toLowerCase().includes('people.read')
+    ) {
+      logger.warn('[searchContacts] People.Read scope is not enabled, skipping contact search');
+      return [];
+    }
+    // Reason: Search only for OrganizationUser (person) type, not groups
+    const filter = "personType/subclass eq 'OrganizationUser'";
+
+    let apiCall = graphClient
+      .api('/me/people')
+      .search(`"${query}"`)
+      .select(
+        'id,displayName,givenName,surname,userPrincipalName,jobTitle,department,companyName,scoredEmailAddresses,personType,phones',
+      )
+      .header('ConsistencyLevel', 'eventual')
+      .filter(filter)
+      .top(limit);
+
+    const contactsResponse = await apiCall.get();
+    return (contactsResponse.value || []).map(mapContactToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchContacts] Error searching contacts:', error);
+    return [];
+  }
+};
+
+/**
+ * Search for users using Microsoft Graph /users endpoint
+ * Returns mapped TPrincipalSearchResult objects
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped user results
+ */
+const searchUsers = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+
+    // Reason: Search users by display name, email, and user principal name
+    const usersResponse = await graphClient
+      .api('/users')
+      .search(
+        `"displayName:${query}" OR "userPrincipalName:${query}" OR "mail:${query}" OR "givenName:${query}" OR "surname:${query}"`,
+      )
+      .select(
+        'id,displayName,givenName,surname,userPrincipalName,jobTitle,department,companyName,mail,phones',
+      )
+      .header('ConsistencyLevel', 'eventual')
+      .top(limit)
+      .get();
+
+    return (usersResponse.value || []).map(mapUserToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchUsers] Error searching users:', error);
+    return [];
+  }
+};
+
+/**
+ * Search for groups using Microsoft Graph /groups endpoint
+ * Returns mapped TPrincipalSearchResult objects, includes all group types
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped group results
+ */
+const searchGroups = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+
+    // Reason: Search all groups by display name and email without filtering group types
+    const groupsResponse = await graphClient
+      .api('/groups')
+      .search(`"displayName:${query}" OR "mail:${query}" OR "mailNickname:${query}"`)
+      .select('id,displayName,mail,mailNickname,description,groupTypes,resourceProvisioningOptions')
+      .header('ConsistencyLevel', 'eventual')
+      .top(limit)
+      .get();
+
+    return (groupsResponse.value || []).map(mapGroupToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchGroups] Error searching groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Test Graph API connectivity and permissions
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Object>} Test results with available permissions
+ */
+const testGraphApiAccess = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const results = {
+      userAccess: false,
+      peopleAccess: false,
+      groupsAccess: false,
+      usersEndpointAccess: false,
+      groupsEndpointAccess: false,
+      errors: [],
+    };
+
+    // Test User.Read permission
+    try {
+      await graphClient.api('/me').select('id,displayName').get();
+      results.userAccess = true;
+    } catch (error) {
+      results.errors.push(`User.Read: ${error.message}`);
+    }
+
+    // Test People.Read permission with OrganizationUser filter
+    try {
+      await graphClient
+        .api('/me/people')
+        .filter("personType/subclass eq 'OrganizationUser'")
+        .top(1)
+        .get();
+      results.peopleAccess = true;
+    } catch (error) {
+      results.errors.push(`People.Read (OrganizationUser): ${error.message}`);
+    }
+
+    // Test People.Read permission with UnifiedGroup filter
+    try {
+      await graphClient
+        .api('/me/people')
+        .filter("personType/subclass eq 'UnifiedGroup'")
+        .top(1)
+        .get();
+      results.groupsAccess = true;
+    } catch (error) {
+      results.errors.push(`People.Read (UnifiedGroup): ${error.message}`);
+    }
+
+    // Test /users endpoint access (requires User.Read.All or similar)
+    try {
+      await graphClient
+        .api('/users')
+        .search('"displayName:test"')
+        .select('id,displayName,userPrincipalName')
+        .top(1)
+        .get();
+      results.usersEndpointAccess = true;
+    } catch (error) {
+      results.errors.push(`Users endpoint: ${error.message}`);
+    }
+
+    // Test /groups endpoint access (requires Group.Read.All or similar)
+    try {
+      await graphClient
+        .api('/groups')
+        .search('"displayName:test"')
+        .select('id,displayName,mail')
+        .top(1)
+        .get();
+      results.groupsEndpointAccess = true;
+    } catch (error) {
+      results.errors.push(`Groups endpoint: ${error.message}`);
+    }
+
+    return results;
+  } catch (error) {
+    logger.error('[testGraphApiAccess] Error testing Graph API access:', error);
+    return {
+      userAccess: false,
+      peopleAccess: false,
+      groupsAccess: false,
+      usersEndpointAccess: false,
+      groupsEndpointAccess: false,
+      errors: [error.message],
+    };
+  }
+};
+
+/**
+ * Map Graph API user object to TPrincipalSearchResult format
+ * @param {TGraphUser} user - Raw user object from Graph API
+ * @returns {TPrincipalSearchResult} Mapped user result
+ */
+const mapUserToTPrincipalSearchResult = (user) => {
+  return {
+    id: null,
+    type: 'user',
+    name: user.displayName,
+    email: user.mail || user.userPrincipalName,
+    username: user.userPrincipalName,
+    source: 'entra',
+    idOnTheSource: user.id,
+  };
+};
+
+/**
+ * Map Graph API group object to TPrincipalSearchResult format
+ * @param {TGraphGroup} group - Raw group object from Graph API
+ * @returns {TPrincipalSearchResult} Mapped group result
+ */
+const mapGroupToTPrincipalSearchResult = (group) => {
+  return {
+    id: null,
+    type: 'group',
+    name: group.displayName,
+    email: group.mail || group.userPrincipalName,
+    description: group.description,
+    source: 'entra',
+    idOnTheSource: group.id,
+  };
+};
+
+/**
+ * Map Graph API /me/people contact object to TPrincipalSearchResult format
+ * Handles both user and group contacts from the people endpoint
+ * @param {TGraphPerson} contact - Raw contact object from Graph API /me/people
+ * @returns {TPrincipalSearchResult} Mapped contact result
+ */
+const mapContactToTPrincipalSearchResult = (contact) => {
+  const isGroup = contact.personType?.class === 'Group';
+  const primaryEmail = contact.scoredEmailAddresses?.[0]?.address;
+
+  return {
+    id: null,
+    type: isGroup ? 'group' : 'user',
+    name: contact.displayName,
+    email: primaryEmail,
+    username: !isGroup ? contact.userPrincipalName : undefined,
+    source: 'entra',
+    idOnTheSource: contact.id,
+  };
+};
+
+module.exports = {
+  getGroupMembers,
+  getGroupOwners,
+  createGraphClient,
+  getUserEntraGroups,
+  getUserOwnedEntraGroups,
+  testGraphApiAccess,
+  searchEntraIdPrincipals,
+  exchangeTokenForGraphAccess,
+  entraIdPrincipalFeatureEnabled,
+};

api/server/services/GraphApiService.spec.js

@@ -0,0 +1,720 @@
+jest.mock('@microsoft/microsoft-graph-client');
+jest.mock('~/strategies/openidStrategy');
+jest.mock('~/cache/getLogStores');
+jest.mock('@librechat/data-schemas', () => ({
+  ...jest.requireActual('@librechat/data-schemas'),
+  logger: {
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+jest.mock('~/config', () => ({
+  logger: {
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+  createAxiosInstance: jest.fn(() => ({
+    create: jest.fn(),
+    defaults: {},
+  })),
+}));
+jest.mock('~/utils', () => ({
+  logAxiosError: jest.fn(),
+}));
+
+jest.mock('~/server/services/Config', () => ({}));
+jest.mock('~/server/services/Files/strategies', () => ({
+  getStrategyFunctions: jest.fn(),
+}));
+
+const mongoose = require('mongoose');
+const client = require('openid-client');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+const { Client } = require('@microsoft/microsoft-graph-client');
+const { getOpenIdConfig } = require('~/strategies/openidStrategy');
+const getLogStores = require('~/cache/getLogStores');
+const GraphApiService = require('./GraphApiService');
+
+describe('GraphApiService', () => {
+  let mongoServer;
+  let mockGraphClient;
+  let mockTokensCache;
+  let mockOpenIdConfig;
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create();
+    const mongoUri = mongoServer.getUri();
+    await mongoose.connect(mongoUri);
+  });
+
+  afterAll(async () => {
+    await mongoose.disconnect();
+    await mongoServer.stop();
+  });
+
+  afterEach(() => {
+    // Clean up environment variables
+    delete process.env.OPENID_GRAPH_SCOPES;
+  });
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    await mongoose.connection.dropDatabase();
+
+    // Set up environment variable for People.Read scope
+    process.env.OPENID_GRAPH_SCOPES = 'User.Read,People.Read,Group.Read.All';
+
+    // Mock Graph client
+    mockGraphClient = {
+      api: jest.fn().mockReturnThis(),
+      search: jest.fn().mockReturnThis(),
+      filter: jest.fn().mockReturnThis(),
+      select: jest.fn().mockReturnThis(),
+      header: jest.fn().mockReturnThis(),
+      top: jest.fn().mockReturnThis(),
+      get: jest.fn(),
+    };
+
+    Client.init.mockReturnValue(mockGraphClient);
+
+    // Mock tokens cache
+    mockTokensCache = {
+      get: jest.fn(),
+      set: jest.fn(),
+    };
+    getLogStores.mockReturnValue(mockTokensCache);
+
+    // Mock OpenID config
+    mockOpenIdConfig = {
+      client_id: 'test-client-id',
+      issuer: 'https://test-issuer.com',
+    };
+    getOpenIdConfig.mockReturnValue(mockOpenIdConfig);
+
+    // Mock openid-client (using the existing jest mock configuration)
+    if (client.genericGrantRequest) {
+      client.genericGrantRequest.mockResolvedValue({
+        access_token: 'mocked-graph-token',
+        expires_in: 3600,
+      });
+    }
+  });
+
+  describe('Dependency Contract Tests', () => {
+    it('should fail if getOpenIdConfig interface changes', () => {
+      // Reason: Ensure getOpenIdConfig returns expected structure
+      const config = getOpenIdConfig();
+
+      expect(config).toBeDefined();
+      expect(typeof config).toBe('object');
+      // Add specific property checks that GraphApiService depends on
+      expect(config).toHaveProperty('client_id');
+      expect(config).toHaveProperty('issuer');
+
+      // Ensure the function is callable
+      expect(typeof getOpenIdConfig).toBe('function');
+    });
+
+    it('should fail if openid-client.genericGrantRequest interface changes', () => {
+      // Reason: Ensure client.genericGrantRequest maintains expected signature
+      if (client.genericGrantRequest) {
+        expect(typeof client.genericGrantRequest).toBe('function');
+
+        // Test that it accepts the expected parameters
+        const mockCall = client.genericGrantRequest(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope: 'test-scope',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+
+        expect(mockCall).toBeDefined();
+      }
+    });
+
+    it('should fail if Microsoft Graph Client interface changes', () => {
+      // Reason: Ensure Graph Client maintains expected fluent API
+      expect(typeof Client.init).toBe('function');
+
+      const client = Client.init({ authProvider: jest.fn() });
+      expect(client).toHaveProperty('api');
+      expect(typeof client.api).toBe('function');
+    });
+  });
+
+  describe('createGraphClient', () => {
+    it('should create graph client with exchanged token', async () => {
+      const accessToken = 'test-access-token';
+      const sub = 'test-user-id';
+
+      const result = await GraphApiService.createGraphClient(accessToken, sub);
+
+      expect(getOpenIdConfig).toHaveBeenCalled();
+      expect(Client.init).toHaveBeenCalledWith({
+        authProvider: expect.any(Function),
+      });
+      expect(result).toBe(mockGraphClient);
+    });
+
+    it('should handle token exchange errors gracefully', async () => {
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockRejectedValue(new Error('Token exchange failed'));
+      }
+
+      await expect(GraphApiService.createGraphClient('invalid-token', 'test-user')).rejects.toThrow(
+        'Token exchange failed',
+      );
+    });
+  });
+
+  describe('exchangeTokenForGraphAccess', () => {
+    it('should return cached token if available', async () => {
+      const cachedToken = { access_token: 'cached-token' };
+      mockTokensCache.get.mockResolvedValue(cachedToken);
+
+      const result = await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      expect(result).toBe('cached-token');
+      expect(mockTokensCache.get).toHaveBeenCalledWith('test-user:graph');
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).not.toHaveBeenCalled();
+      }
+    });
+
+    it('should exchange token and cache result', async () => {
+      mockTokensCache.get.mockResolvedValue(null);
+
+      const result = await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).toHaveBeenCalledWith(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope:
+              'https://graph.microsoft.com/User.Read https://graph.microsoft.com/People.Read https://graph.microsoft.com/Group.Read.All',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+      }
+
+      expect(mockTokensCache.set).toHaveBeenCalledWith(
+        'test-user:graph',
+        { access_token: 'mocked-graph-token' },
+        3600000,
+      );
+
+      expect(result).toBe('mocked-graph-token');
+    });
+
+    it('should use custom scopes from environment', async () => {
+      const originalEnv = process.env.OPENID_GRAPH_SCOPES;
+      process.env.OPENID_GRAPH_SCOPES = 'Custom.Read,Custom.Write';
+
+      mockTokensCache.get.mockResolvedValue(null);
+
+      await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).toHaveBeenCalledWith(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope:
+              'https://graph.microsoft.com/Custom.Read https://graph.microsoft.com/Custom.Write',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+      }
+
+      process.env.OPENID_GRAPH_SCOPES = originalEnv;
+    });
+  });
+
+  describe('searchEntraIdPrincipals', () => {
+    // Mock data used by multiple tests
+    const mockContactsResponse = {
+      value: [
+        {
+          id: 'contact-user-1',
+          displayName: 'John Doe',
+          userPrincipalName: 'john@company.com',
+          mail: 'john@company.com',
+          personType: { class: 'Person', subclass: 'OrganizationUser' },
+          scoredEmailAddresses: [{ address: 'john@company.com', relevanceScore: 0.9 }],
+        },
+        {
+          id: 'contact-group-1',
+          displayName: 'Marketing Team',
+          mail: 'marketing@company.com',
+          personType: { class: 'Group', subclass: 'UnifiedGroup' },
+          scoredEmailAddresses: [{ address: 'marketing@company.com', relevanceScore: 0.8 }],
+        },
+      ],
+    };
+
+    const mockUsersResponse = {
+      value: [
+        {
+          id: 'dir-user-1',
+          displayName: 'Jane Smith',
+          userPrincipalName: 'jane@company.com',
+          mail: 'jane@company.com',
+        },
+      ],
+    };
+
+    const mockGroupsResponse = {
+      value: [
+        {
+          id: 'dir-group-1',
+          displayName: 'Development Team',
+          mail: 'dev@company.com',
+        },
+      ],
+    };
+
+    beforeEach(() => {
+      // Reset mock call history for each test
+      jest.clearAllMocks();
+
+      // Re-apply the Client.init mock after clearAllMocks
+      Client.init.mockReturnValue(mockGraphClient);
+
+      // Re-apply openid-client mock
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockResolvedValue({
+          access_token: 'mocked-graph-token',
+          expires_in: 3600,
+        });
+      }
+
+      // Re-apply cache mock
+      mockTokensCache.get.mockResolvedValue(null); // Force token exchange
+      mockTokensCache.set.mockResolvedValue();
+      getLogStores.mockReturnValue(mockTokensCache);
+      getOpenIdConfig.mockReturnValue(mockOpenIdConfig);
+    });
+
+    it('should return empty results for short queries', async () => {
+      const result = await GraphApiService.searchEntraIdPrincipals('token', 'user', 'a', 'all', 10);
+
+      expect(result).toEqual([]);
+      expect(mockGraphClient.api).not.toHaveBeenCalled();
+    });
+
+    it('should search contacts first and additional users for users type', async () => {
+      // Mock responses for this specific test
+      const contactsFilteredResponse = {
+        value: [
+          {
+            id: 'contact-user-1',
+            displayName: 'John Doe',
+            userPrincipalName: 'john@company.com',
+            mail: 'john@company.com',
+            personType: { class: 'Person', subclass: 'OrganizationUser' },
+            scoredEmailAddresses: [{ address: 'john@company.com', relevanceScore: 0.9 }],
+          },
+        ],
+      };
+
+      mockGraphClient.get
+        .mockResolvedValueOnce(contactsFilteredResponse) // contacts call
+        .mockResolvedValueOnce(mockUsersResponse); // users call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'john',
+        'users',
+        10,
+      );
+
+      // Should call contacts first with user filter
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"john"');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+
+      // Should call users endpoint for additional results
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.search).toHaveBeenCalledWith(
+        '"displayName:john" OR "userPrincipalName:john" OR "mail:john" OR "givenName:john" OR "surname:john"',
+      );
+
+      // Should return TPrincipalSearchResult array
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(2); // 1 from contacts + 1 from users
+      expect(result[0]).toMatchObject({
+        id: null,
+        type: 'user',
+        name: 'John Doe',
+        email: 'john@company.com',
+        source: 'entra',
+        idOnTheSource: 'contact-user-1',
+      });
+    });
+
+    it('should search groups endpoint only for groups type', async () => {
+      // Mock responses for this specific test - only groups endpoint called
+      mockGraphClient.get.mockResolvedValueOnce(mockGroupsResponse); // only groups call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'team',
+        'groups',
+        10,
+      );
+
+      // Should NOT call contacts for groups type
+      expect(mockGraphClient.api).not.toHaveBeenCalledWith('/me/people');
+
+      // Should call groups endpoint only
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.search).toHaveBeenCalledWith(
+        '"displayName:team" OR "mail:team" OR "mailNickname:team"',
+      );
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(1); // 1 from groups only
+    });
+
+    it('should search all endpoints for all type', async () => {
+      // Mock responses for this specific test
+      mockGraphClient.get
+        .mockResolvedValueOnce(mockContactsResponse) // contacts call (both user and group)
+        .mockResolvedValueOnce(mockUsersResponse) // users call
+        .mockResolvedValueOnce(mockGroupsResponse); // groups call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      // Should call contacts first with user filter
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"test"');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+
+      // Should call both users and groups endpoints
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(4); // 2 from contacts + 1 from users + 1 from groups
+    });
+
+    it('should early exit if contacts reach limit', async () => {
+      // Mock contacts to return exactly the limit
+      const limitedContactsResponse = {
+        value: Array(10).fill({
+          id: 'contact-1',
+          displayName: 'Contact User',
+          mail: 'contact@company.com',
+          personType: { class: 'Person', subclass: 'OrganizationUser' },
+        }),
+      };
+
+      mockGraphClient.get.mockResolvedValueOnce(limitedContactsResponse);
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      // Should call contacts first
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"test"');
+      // Should not call users endpoint since limit was reached
+      expect(mockGraphClient.api).not.toHaveBeenCalledWith('/users');
+
+      expect(result).toHaveLength(10);
+    });
+
+    it('should deduplicate results based on idOnTheSource', async () => {
+      // Mock responses with duplicate IDs
+      const duplicateContactsResponse = {
+        value: [
+          {
+            id: 'duplicate-id',
+            displayName: 'John Doe',
+            mail: 'john@company.com',
+            personType: { class: 'Person', subclass: 'OrganizationUser' },
+          },
+        ],
+      };
+
+      const duplicateUsersResponse = {
+        value: [
+          {
+            id: 'duplicate-id', // Same ID as contact
+            displayName: 'John Doe',
+            mail: 'john@company.com',
+          },
+        ],
+      };
+
+      mockGraphClient.get
+        .mockResolvedValueOnce(duplicateContactsResponse)
+        .mockResolvedValueOnce(duplicateUsersResponse);
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'john',
+        'users',
+        10,
+      );
+
+      // Should only return one result despite duplicate IDs
+      expect(result).toHaveLength(1);
+      expect(result[0].idOnTheSource).toBe('duplicate-id');
+    });
+
+    it('should handle Graph API errors gracefully', async () => {
+      mockGraphClient.get.mockRejectedValue(new Error('Graph API error'));
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getUserEntraGroups', () => {
+    it('should fetch user groups from memberOf endpoint', async () => {
+      const mockGroupsResponse = {
+        value: [
+          {
+            id: 'group-1',
+          },
+          {
+            id: 'group-2',
+          },
+        ],
+      };
+
+      mockGraphClient.get.mockResolvedValue(mockGroupsResponse);
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/memberOf');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id');
+
+      expect(result).toHaveLength(2);
+      expect(result).toEqual(['group-1', 'group-2']);
+    });
+
+    it('should return empty array on error', async () => {
+      mockGraphClient.get.mockRejectedValue(new Error('API error'));
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty response', async () => {
+      const mockGroupsResponse = {
+        value: [],
+      };
+
+      mockGraphClient.get.mockResolvedValue(mockGroupsResponse);
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle missing value property', async () => {
+      mockGraphClient.get.mockResolvedValue({});
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('testGraphApiAccess', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('should test all permissions and return success results', async () => {
+      // Mock successful responses for all tests
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me test
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser test
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup test
+        .mockResolvedValueOnce({ value: [] }) // /users endpoint test
+        .mockResolvedValueOnce({ value: [] }); // /groups endpoint test
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: true,
+        groupsAccess: true,
+        usersEndpointAccess: true,
+        groupsEndpointAccess: true,
+        errors: [],
+      });
+
+      // Verify all endpoints were tested
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+      expect(mockGraphClient.filter).toHaveBeenCalledWith("personType/subclass eq 'UnifiedGroup'");
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"displayName:test"');
+    });
+
+    it('should handle partial failures and record errors', async () => {
+      // Mock mixed success/failure responses
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me success
+        .mockRejectedValueOnce(new Error('People access denied')) // people OrganizationUser fail
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup success
+        .mockRejectedValueOnce(new Error('Users endpoint access denied')) // /users fail
+        .mockResolvedValueOnce({ value: [] }); // /groups success
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: false,
+        groupsAccess: true,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: true,
+        errors: [
+          'People.Read (OrganizationUser): People access denied',
+          'Users endpoint: Users endpoint access denied',
+        ],
+      });
+    });
+
+    it('should handle complete Graph client creation failure', async () => {
+      // Mock token exchange failure to test error handling
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockRejectedValue(new Error('Token exchange failed'));
+      }
+
+      const result = await GraphApiService.testGraphApiAccess('invalid-token', 'user');
+
+      expect(result).toEqual({
+        userAccess: false,
+        peopleAccess: false,
+        groupsAccess: false,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: ['Token exchange failed'],
+      });
+    });
+
+    it('should record all permission errors', async () => {
+      // Mock all requests to fail
+      mockGraphClient.get
+        .mockRejectedValueOnce(new Error('User.Read denied'))
+        .mockRejectedValueOnce(new Error('People.Read OrganizationUser denied'))
+        .mockRejectedValueOnce(new Error('People.Read UnifiedGroup denied'))
+        .mockRejectedValueOnce(new Error('Users directory access denied'))
+        .mockRejectedValueOnce(new Error('Groups directory access denied'));
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: false,
+        peopleAccess: false,
+        groupsAccess: false,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: [
+          'User.Read: User.Read denied',
+          'People.Read (OrganizationUser): People.Read OrganizationUser denied',
+          'People.Read (UnifiedGroup): People.Read UnifiedGroup denied',
+          'Users endpoint: Users directory access denied',
+          'Groups endpoint: Groups directory access denied',
+        ],
+      });
+    });
+
+    it('should test new endpoints with correct search patterns', async () => {
+      // Mock successful responses for endpoint testing
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup
+        .mockResolvedValueOnce({ value: [] }) // /users
+        .mockResolvedValueOnce({ value: [] }); // /groups
+
+      await GraphApiService.testGraphApiAccess('token', 'user');
+
+      // Verify /users endpoint test
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"displayName:test"');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id,displayName,userPrincipalName');
+
+      // Verify /groups endpoint test
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id,displayName,mail');
+    });
+
+    it('should handle endpoint-specific permission failures', async () => {
+      // Mock specific endpoint failures
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me success
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser success
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup success
+        .mockRejectedValueOnce(new Error('Insufficient privileges')) // /users fail (User.Read.All needed)
+        .mockRejectedValueOnce(new Error('Access denied to groups')); // /groups fail (Group.Read.All needed)
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: true,
+        groupsAccess: true,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: [
+          'Users endpoint: Insufficient privileges',
+          'Groups endpoint: Access denied to groups',
+        ],
+      });
+    });
+  });
+});

api/server/services/PermissionService.js

@@ -0,0 +1,721 @@
+const mongoose = require('mongoose');
+const { getTransactionSupport, logger } = require('@librechat/data-schemas');
+const { isEnabled } = require('~/server/utils');
+const {
+  entraIdPrincipalFeatureEnabled,
+  getUserEntraGroups,
+  getUserOwnedEntraGroups,
+  getGroupMembers,
+  getGroupOwners,
+} = require('~/server/services/GraphApiService');
+const {
+  findGroupByExternalId,
+  findRoleByIdentifier,
+  getUserPrincipals,
+  createGroup,
+  createUser,
+  updateUser,
+  findUser,
+  grantPermission: grantPermissionACL,
+  findAccessibleResources: findAccessibleResourcesACL,
+  hasPermission,
+  getEffectivePermissions: getEffectivePermissionsACL,
+  findEntriesByPrincipalsAndResource,
+} = require('~/models');
+const { AclEntry, AccessRole, Group } = require('~/db/models');
+
+/** @type {boolean|null} */
+let transactionSupportCache = null;
+
+/**
+ * @import { TPrincipal } from 'librechat-data-provider'
+ */
+/**
+ * Grant a permission to a principal for a resource using a role
+ * @param {Object} params - Parameters for granting role-based permission
+ * @param {string} params.principalType - 'user', 'group', or 'public'
+ * @param {string|mongoose.Types.ObjectId|null} params.principalId - The ID of the principal (null for 'public')
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {string} params.accessRoleId - The ID of the role (e.g., 'agent_viewer', 'agent_editor')
+ * @param {string|mongoose.Types.ObjectId} params.grantedBy - User ID granting the permission
+ * @param {mongoose.ClientSession} [params.session] - Optional MongoDB session for transactions
+ * @returns {Promise<Object>} The created or updated ACL entry
+ */
+const grantPermission = async ({
+  principalType,
+  principalId,
+  resourceType,
+  resourceId,
+  accessRoleId,
+  grantedBy,
+  session,
+}) => {
+  try {
+    if (!['user', 'group', 'public'].includes(principalType)) {
+      throw new Error(`Invalid principal type: ${principalType}`);
+    }
+
+    if (principalType !== 'public' && !principalId) {
+      throw new Error('Principal ID is required for user and group principals');
+    }
+
+    if (principalId && !mongoose.Types.ObjectId.isValid(principalId)) {
+      throw new Error(`Invalid principal ID: ${principalId}`);
+    }
+
+    if (!resourceId || !mongoose.Types.ObjectId.isValid(resourceId)) {
+      throw new Error(`Invalid resource ID: ${resourceId}`);
+    }
+
+    // Get the role to determine permission bits
+    const role = await findRoleByIdentifier(accessRoleId);
+    if (!role) {
+      throw new Error(`Role ${accessRoleId} not found`);
+    }
+
+    // Ensure the role is for the correct resource type
+    if (role.resourceType !== resourceType) {
+      throw new Error(
+        `Role ${accessRoleId} is for ${role.resourceType} resources, not ${resourceType}`,
+      );
+    }
+    return await grantPermissionACL(
+      principalType,
+      principalId,
+      resourceType,
+      resourceId,
+      role.permBits,
+      grantedBy,
+      session,
+      role._id,
+    );
+  } catch (error) {
+    logger.error(`[PermissionService.grantPermission] Error: ${error.message}`);
+    throw error;
+  }
+};
+
+/**
+ * Check if a user has specific permission bits on a resource
+ * @param {Object} params - Parameters for checking permissions
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {number} params.requiredPermissions - The permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<boolean>} Whether the user has the required permission bits
+ */
+const checkPermission = async ({ userId, resourceType, resourceId, requiredPermission }) => {
+  try {
+    if (typeof requiredPermission !== 'number' || requiredPermission < 1) {
+      throw new Error('requiredPermission must be a positive number');
+    }
+
+    // Get all principals for the user (user + groups + public)
+    const principals = await getUserPrincipals(userId);
+
+    if (principals.length === 0) {
+      return false;
+    }
+
+    return await hasPermission(principals, resourceType, resourceId, requiredPermission);
+  } catch (error) {
+    logger.error(`[PermissionService.checkPermission] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermission must be')) {
+      throw error;
+    }
+    return false;
+  }
+};
+
+/**
+ * Get effective permission bitmask for a user on a resource
+ * @param {Object} params - Parameters for getting effective permissions
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @returns {Promise<number>} Effective permission bitmask
+ */
+const getEffectivePermissions = async ({ userId, resourceType, resourceId }) => {
+  try {
+    // Get all principals for the user (user + groups + public)
+    const principals = await getUserPrincipals(userId);
+
+    if (principals.length === 0) {
+      return 0;
+    }
+    return await getEffectivePermissionsACL(principals, resourceType, resourceId);
+  } catch (error) {
+    logger.error(`[PermissionService.getEffectivePermissions] Error: ${error.message}`);
+    return 0;
+  }
+};
+
+/**
+ * Find all resources of a specific type that a user has access to with specific permission bits
+ * @param {Object} params - Parameters for finding accessible resources
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<Array>} Array of resource IDs
+ */
+const findAccessibleResources = async ({ userId, resourceType, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Get all principals for the user (user + groups + public)
+    const principalsList = await getUserPrincipals(userId);
+
+    if (principalsList.length === 0) {
+      return [];
+    }
+    return await findAccessibleResourcesACL(principalsList, resourceType, requiredPermissions);
+  } catch (error) {
+    logger.error(`[PermissionService.findAccessibleResources] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return [];
+  }
+};
+
+/**
+ * Find all publicly accessible resources of a specific type
+ * @param {Object} params - Parameters for finding publicly accessible resources
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<Array>} Array of resource IDs
+ */
+const findPubliclyAccessibleResources = async ({ resourceType, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Find all public ACL entries where the public principal has at least the required permission bits
+    const entries = await AclEntry.find({
+      principalType: 'public',
+      resourceType,
+      permBits: { $bitsAllSet: requiredPermissions },
+    }).distinct('resourceId');
+
+    return entries;
+  } catch (error) {
+    logger.error(`[PermissionService.findPubliclyAccessibleResources] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return [];
+  }
+};
+
+/**
+ * Get available roles for a resource type
+ * @param {Object} params - Parameters for getting available roles
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @returns {Promise<Array>} Array of role definitions
+ */
+const getAvailableRoles = async ({ resourceType }) => {
+  try {
+    return await AccessRole.find({ resourceType }).lean();
+  } catch (error) {
+    logger.error(`[PermissionService.getAvailableRoles] Error: ${error.message}`);
+    return [];
+  }
+};
+
+/**
+ * Ensures a principal exists in the database based on TPrincipal data
+ * Creates user if it doesn't exist locally (for Entra ID users)
+ * @param {Object} principal - TPrincipal object from frontend
+ * @param {string} principal.type - 'user', 'group', or 'public'
+ * @param {string} [principal.id] - Local database ID (null for Entra ID principals not yet synced)
+ * @param {string} principal.name - Display name
+ * @param {string} [principal.email] - Email address
+ * @param {string} [principal.source] - 'local' or 'entra'
+ * @param {string} [principal.idOnTheSource] - Entra ID object ID for external principals
+ * @returns {Promise<string|null>} Returns the principalId for database operations, null for public
+ */
+const ensurePrincipalExists = async function (principal) {
+  if (principal.type === 'public') {
+    return null;
+  }
+
+  if (principal.id) {
+    return principal.id;
+  }
+
+  if (principal.type === 'user' && principal.source === 'entra') {
+    if (!principal.email || !principal.idOnTheSource) {
+      throw new Error('Entra ID user principals must have email and idOnTheSource');
+    }
+
+    let existingUser = await findUser({ idOnTheSource: principal.idOnTheSource });
+
+    if (!existingUser) {
+      existingUser = await findUser({ email: principal.email.toLowerCase() });
+    }
+
+    if (existingUser) {
+      if (!existingUser.idOnTheSource && principal.idOnTheSource) {
+        await updateUser(existingUser._id, {
+          idOnTheSource: principal.idOnTheSource,
+          provider: 'openid',
+        });
+      }
+      return existingUser._id.toString();
+    }
+
+    const userData = {
+      name: principal.name,
+      email: principal.email.toLowerCase(),
+      emailVerified: false,
+      provider: 'openid',
+      idOnTheSource: principal.idOnTheSource,
+    };
+
+    const userId = await createUser(userData, true, false);
+    return userId.toString();
+  }
+
+  if (principal.type === 'group') {
+    throw new Error('Group principals should be handled by group-specific methods');
+  }
+
+  throw new Error(`Unsupported principal type: ${principal.type}`);
+};
+
+/**
+ * Ensures a group principal exists in the database based on TPrincipal data
+ * Creates group if it doesn't exist locally (for Entra ID groups)
+ * For Entra ID groups, always synchronizes member IDs when authentication context is provided
+ * @param {Object} principal - TPrincipal object from frontend
+ * @param {string} principal.type - Must be 'group'
+ * @param {string} [principal.id] - Local database ID (null for Entra ID principals not yet synced)
+ * @param {string} principal.name - Display name
+ * @param {string} [principal.email] - Email address
+ * @param {string} [principal.description] - Group description
+ * @param {string} [principal.source] - 'local' or 'entra'
+ * @param {string} [principal.idOnTheSource] - Entra ID object ID for external principals
+ * @param {Object} [authContext] - Optional authentication context for fetching member data
+ * @param {string} [authContext.accessToken] - Access token for Graph API calls
+ * @param {string} [authContext.sub] - Subject identifier
+ * @returns {Promise<string>} Returns the groupId for database operations
+ */
+const ensureGroupPrincipalExists = async function (principal, authContext = null) {
+  if (principal.type !== 'group') {
+    throw new Error(`Invalid principal type: ${principal.type}. Expected 'group'`);
+  }
+
+  if (principal.source === 'entra') {
+    if (!principal.name || !principal.idOnTheSource) {
+      throw new Error('Entra ID group principals must have name and idOnTheSource');
+    }
+
+    let memberIds = [];
+    if (authContext && authContext.accessToken && authContext.sub) {
+      try {
+        memberIds = await getGroupMembers(
+          authContext.accessToken,
+          authContext.sub,
+          principal.idOnTheSource,
+        );
+
+        // Include group owners as members if feature is enabled
+        if (isEnabled(process.env.ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS)) {
+          const ownerIds = await getGroupOwners(
+            authContext.accessToken,
+            authContext.sub,
+            principal.idOnTheSource,
+          );
+          if (ownerIds && ownerIds.length > 0) {
+            memberIds.push(...ownerIds);
+            // Remove duplicates
+            memberIds = [...new Set(memberIds)];
+          }
+        }
+      } catch (error) {
+        logger.error('Failed to fetch group members from Graph API:', error);
+      }
+    }
+
+    let existingGroup = await findGroupByExternalId(principal.idOnTheSource, 'entra');
+
+    if (!existingGroup && principal.email) {
+      existingGroup = await Group.findOne({ email: principal.email.toLowerCase() }).lean();
+    }
+
+    if (existingGroup) {
+      const updateData = {};
+      let needsUpdate = false;
+
+      if (!existingGroup.idOnTheSource && principal.idOnTheSource) {
+        updateData.idOnTheSource = principal.idOnTheSource;
+        updateData.source = 'entra';
+        needsUpdate = true;
+      }
+
+      if (principal.description && existingGroup.description !== principal.description) {
+        updateData.description = principal.description;
+        needsUpdate = true;
+      }
+
+      if (principal.email && existingGroup.email !== principal.email.toLowerCase()) {
+        updateData.email = principal.email.toLowerCase();
+        needsUpdate = true;
+      }
+
+      if (authContext && authContext.accessToken && authContext.sub) {
+        updateData.memberIds = memberIds;
+        needsUpdate = true;
+      }
+
+      if (needsUpdate) {
+        await Group.findByIdAndUpdate(existingGroup._id, { $set: updateData }, { new: true });
+      }
+
+      return existingGroup._id.toString();
+    }
+
+    const groupData = {
+      name: principal.name,
+      source: 'entra',
+      idOnTheSource: principal.idOnTheSource,
+      memberIds: memberIds, // Store idOnTheSource values of group members (empty if no auth context)
+    };
+
+    if (principal.email) {
+      groupData.email = principal.email.toLowerCase();
+    }
+
+    if (principal.description) {
+      groupData.description = principal.description;
+    }
+
+    const newGroup = await createGroup(groupData);
+    return newGroup._id.toString();
+  }
+  if (principal.id && authContext == null) {
+    return principal.id;
+  }
+
+  throw new Error(`Unsupported group principal source: ${principal.source}`);
+};
+
+/**
+ * Synchronize user's Entra ID group memberships on sign-in
+ * Gets user's group IDs from GraphAPI and updates memberships only for existing groups in database
+ * Optionally includes groups the user owns if ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS is enabled
+ * @param {Object} user - User object with authentication context
+ * @param {string} user.openidId - User's OpenID subject identifier
+ * @param {string} user.idOnTheSource - User's Entra ID (oid from token claims)
+ * @param {string} user.provider - Authentication provider ('openid')
+ * @param {string} accessToken - Access token for Graph API calls
+ * @param {mongoose.ClientSession} [session] - Optional MongoDB session for transactions
+ * @returns {Promise<void>}
+ */
+const syncUserEntraGroupMemberships = async (user, accessToken, session = null) => {
+  try {
+    if (!entraIdPrincipalFeatureEnabled(user) || !accessToken || !user.idOnTheSource) {
+      return;
+    }
+
+    const memberGroupIds = await getUserEntraGroups(accessToken, user.openidId);
+    let allGroupIds = [...(memberGroupIds || [])];
+
+    // Include owned groups if feature is enabled
+    if (isEnabled(process.env.ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS)) {
+      const ownedGroupIds = await getUserOwnedEntraGroups(accessToken, user.openidId);
+      if (ownedGroupIds && ownedGroupIds.length > 0) {
+        allGroupIds.push(...ownedGroupIds);
+        // Remove duplicates
+        allGroupIds = [...new Set(allGroupIds)];
+      }
+    }
+
+    if (!allGroupIds || allGroupIds.length === 0) {
+      return;
+    }
+
+    const sessionOptions = session ? { session } : {};
+
+    await Group.updateMany(
+      {
+        idOnTheSource: { $in: allGroupIds },
+        source: 'entra',
+        memberIds: { $ne: user.idOnTheSource },
+      },
+      { $addToSet: { memberIds: user.idOnTheSource } },
+      sessionOptions,
+    );
+
+    await Group.updateMany(
+      {
+        source: 'entra',
+        memberIds: user.idOnTheSource,
+        idOnTheSource: { $nin: allGroupIds },
+      },
+      { $pull: { memberIds: user.idOnTheSource } },
+      sessionOptions,
+    );
+  } catch (error) {
+    logger.error(`[PermissionService.syncUserEntraGroupMemberships] Error syncing groups:`, error);
+  }
+};
+
+/**
+ * Check if public has a specific permission on a resource
+ * @param {Object} params - Parameters for checking public permission
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {number} params.requiredPermissions - The permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<boolean>} Whether public has the required permission bits
+ */
+const hasPublicPermission = async ({ resourceType, resourceId, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Use public principal to check permissions
+    const publicPrincipal = [{ principalType: 'public' }];
+
+    const entries = await findEntriesByPrincipalsAndResource(
+      publicPrincipal,
+      resourceType,
+      resourceId,
+    );
+
+    // Check if any entry has the required permission bits
+    return entries.some((entry) => (entry.permBits & requiredPermissions) === requiredPermissions);
+  } catch (error) {
+    logger.error(`[PermissionService.hasPublicPermission] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return false;
+  }
+};
+
+/**
+ * Bulk update permissions for a resource (grant, update, revoke)
+ * Efficiently handles multiple permission changes in a single transaction
+ *
+ * @param {Object} params - Parameters for bulk permission update
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {Array<TPrincipal>} params.updatedPrincipals - Array of principals to grant/update permissions for
+ * @param {Array<TPrincipal>} params.revokedPrincipals - Array of principals to revoke permissions from
+ * @param {string|mongoose.Types.ObjectId} params.grantedBy - User ID making the changes
+ * @param {mongoose.ClientSession} [params.session] - Optional MongoDB session for transactions
+ * @returns {Promise<Object>} Results object with granted, updated, revoked arrays and error details
+ */
+const bulkUpdateResourcePermissions = async ({
+  resourceType,
+  resourceId,
+  updatedPrincipals = [],
+  revokedPrincipals = [],
+  grantedBy,
+  session,
+}) => {
+  const supportsTransactions = await getTransactionSupport(mongoose, transactionSupportCache);
+  transactionSupportCache = supportsTransactions;
+  let localSession = session;
+  let shouldEndSession = false;
+
+  try {
+    if (!Array.isArray(updatedPrincipals)) {
+      throw new Error('updatedPrincipals must be an array');
+    }
+
+    if (!Array.isArray(revokedPrincipals)) {
+      throw new Error('revokedPrincipals must be an array');
+    }
+
+    if (!resourceId || !mongoose.Types.ObjectId.isValid(resourceId)) {
+      throw new Error(`Invalid resource ID: ${resourceId}`);
+    }
+
+    if (!localSession && supportsTransactions) {
+      localSession = await mongoose.startSession();
+      localSession.startTransaction();
+      shouldEndSession = true;
+    }
+
+    const sessionOptions = localSession ? { session: localSession } : {};
+
+    const roles = await AccessRole.find({ resourceType }).lean();
+    const rolesMap = new Map();
+    roles.forEach((role) => {
+      rolesMap.set(role.accessRoleId, role);
+    });
+
+    const results = {
+      granted: [],
+      updated: [],
+      revoked: [],
+      errors: [],
+    };
+
+    const bulkWrites = [];
+
+    for (const principal of updatedPrincipals) {
+      try {
+        if (!principal.accessRoleId) {
+          results.errors.push({
+            principal,
+            error: 'accessRoleId is required for updated principals',
+          });
+          continue;
+        }
+
+        const role = rolesMap.get(principal.accessRoleId);
+        if (!role) {
+          results.errors.push({
+            principal,
+            error: `Role ${principal.accessRoleId} not found`,
+          });
+          continue;
+        }
+
+        const query = {
+          principalType: principal.type,
+          resourceType,
+          resourceId,
+        };
+
+        if (principal.type !== 'public') {
+          query.principalId = principal.id;
+        }
+
+        const update = {
+          $set: {
+            permBits: role.permBits,
+            roleId: role._id,
+            grantedBy,
+            grantedAt: new Date(),
+          },
+          $setOnInsert: {
+            principalType: principal.type,
+            resourceType,
+            resourceId,
+            ...(principal.type !== 'public' && {
+              principalId: principal.id,
+              principalModel: principal.type === 'user' ? 'User' : 'Group',
+            }),
+          },
+        };
+
+        bulkWrites.push({
+          updateOne: {
+            filter: query,
+            update: update,
+            upsert: true,
+          },
+        });
+
+        results.granted.push({
+          type: principal.type,
+          id: principal.id,
+          name: principal.name,
+          email: principal.email,
+          source: principal.source,
+          avatar: principal.avatar,
+          description: principal.description,
+          idOnTheSource: principal.idOnTheSource,
+          accessRoleId: principal.accessRoleId,
+          memberCount: principal.memberCount,
+          memberIds: principal.memberIds,
+        });
+      } catch (error) {
+        results.errors.push({
+          principal,
+          error: error.message,
+        });
+      }
+    }
+
+    if (bulkWrites.length > 0) {
+      await AclEntry.bulkWrite(bulkWrites, sessionOptions);
+    }
+
+    const deleteQueries = [];
+    for (const principal of revokedPrincipals) {
+      try {
+        const query = {
+          principalType: principal.type,
+          resourceType,
+          resourceId,
+        };
+
+        if (principal.type !== 'public') {
+          query.principalId = principal.id;
+        }
+
+        deleteQueries.push(query);
+
+        results.revoked.push({
+          type: principal.type,
+          id: principal.id,
+          name: principal.name,
+          email: principal.email,
+          source: principal.source,
+          avatar: principal.avatar,
+          description: principal.description,
+          idOnTheSource: principal.idOnTheSource,
+          memberCount: principal.memberCount,
+        });
+      } catch (error) {
+        results.errors.push({
+          principal,
+          error: error.message,
+        });
+      }
+    }
+
+    if (deleteQueries.length > 0) {
+      await AclEntry.deleteMany(
+        {
+          $or: deleteQueries,
+        },
+        sessionOptions,
+      );
+    }
+
+    if (shouldEndSession && supportsTransactions) {
+      await localSession.commitTransaction();
+    }
+
+    return results;
+  } catch (error) {
+    if (shouldEndSession && supportsTransactions) {
+      await localSession.abortTransaction();
+    }
+    logger.error(`[PermissionService.bulkUpdateResourcePermissions] Error: ${error.message}`);
+    throw error;
+  } finally {
+    if (shouldEndSession && localSession) {
+      localSession.endSession();
+    }
+  }
+};
+
+module.exports = {
+  grantPermission,
+  checkPermission,
+  getEffectivePermissions,
+  findAccessibleResources,
+  findPubliclyAccessibleResources,
+  hasPublicPermission,
+  getAvailableRoles,
+  bulkUpdateResourcePermissions,
+  ensurePrincipalExists,
+  ensureGroupPrincipalExists,
+  syncUserEntraGroupMemberships,
+};