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

* feat: Add granular role-based permissions system with Entra ID integration

      - Implement RBAC with viewer/editor/owner roles using bitwise permissions
      - Add AccessRole, AclEntry, and Group models for permission management
      - Create PermissionService for core permission logic and validation
      - Integrate Microsoft Graph API for Entra ID user/group search
      - Add middleware for resource access validation with custom ID resolvers
      - Implement bulk permission updates with transaction support
      - Create permission management UI with people picker and role selection
      - Add public sharing capabilities for resources
      - Include database migration for existing agent ownership
      - Support hybrid local/Entra ID identity management
      - Add comprehensive test coverage for all new services

chore: Update @librechat/data-schemas to version 0.0.9 and export common module in index.ts

fix: Update userGroup tests to mock logger correctly and change principalId expectation from null to undefined

* fix(data-schemas): use partial index for group idOnTheSource uniqueness

Replace sparse index with partial filter expression to allow multiple local groups
while maintaining unique constraint for external source IDs. The sparse option
on compound indexes doesn't work as expected when one field is always present.

* fix: imports in migrate-agent-permissions.js

* chore(data-schemas): add comprehensive README for data schemas package

- Introduced a detailed README.md file outlining the structure, architecture patterns, and best practices for the LibreChat Data Schemas package.
- Included guidelines for creating new entities, type definitions, schema files, model factory functions, and database methods.
- Added examples and common patterns to enhance understanding and usage of the package.

* chore: remove unused translation keys from localization file

* ci: fix existing tests based off new permission handling

- Renamed test cases to reflect changes in permission checks being handled at the route level.
- Updated assertions to verify that agents are returned regardless of user permissions due to the new permission system.
- Adjusted mocks in AppService and PermissionService tests to ensure proper functionality without relying on actual implementations.

* ci: add unit tests for access control middleware

- Introduced tests for the `canAccessAgentResource` middleware to validate permission checks for agent resources.
- Implemented tests for various scenarios including user roles, ACL entries, and permission levels.
- Added tests for the `checkAccess` function to ensure proper permission handling based on user roles and permissions.
- Utilized MongoDB in-memory server for isolated test environments.

* refactor: remove unused mocks from GraphApiService tests

* ci: enhance AgentFooter tests with improved mocks and permission handling

- Updated mocks for `useWatch`, `useAuthContext`, `useHasAccess`, and `useResourcePermissions` to streamline test setup.
- Adjusted assertions to reflect changes in UI based on agent ID and user roles.
- Replaced `share-agent` component with `grant-access-dialog` in tests to align with recent UI updates.
- Added tests for handling null agent data and permissions loading scenarios.

* ci: enhance GraphApiService tests with MongoDB in-memory server

- Updated test setup to use MongoDB in-memory server for isolated testing.
- Refactored beforeEach to beforeAll for database connection management.
- Cleared database before each test to ensure a clean state.
- Retained existing mocks while improving test structure for better clarity.

* ci: enhance GraphApiService tests with additional logger mocks

- Added mock implementation for logger methods in GraphApiService tests to improve error and debug logging during test execution.
- Ensured existing mocks remain intact while enhancing test coverage and clarity.

* chore: address ESLint Warnings

* - add cursor-based pagination to getListAgentsByAccess and update handler
- add index on updatedAt and _id in agent schema for improved query performance

* refactor permission service with reuse of model methods from data-schema package

* - Fix ObjectId comparison in getListAgentsHandler using .equals() method instead of strict equality
  - Add findPubliclyAccessibleResources function to PermissionService for bulk public resource queries
  - Add hasPublicPermission function to PermissionService for individual resource public permission checks
  - Update getAgentHandler to use hasPublicPermission for accurate individual agent public status
  - Replace instanceProjectId-based global checks with isPublic property from backend in client code
  - Add isPublic property to Agent type definition
  - Add NODE_TLS_REJECT_UNAUTHORIZED debug setting to VS Code launch config

* feat: add check for People.Read scope in searchContacts

* fix: add roleId parameter to grantPermission and update tests for GraphApiService

* refactor: remove problematic projection pipelines in getResourcePermissions for document db aws compatibility

* feat: enhance agent permissions migration with DocumentDB compatibility and add dry-run script

* feat: add support for including Entra ID group owners as members in permissions management + fix Group members  paging

* feat: enforce at least one owner requirement for permission updates and add corresponding localization messages

* refactor: remove German locale (must be added via i18n)

* chore: linting in `api/models/Agent.js` and removed unused variables

* chore: linting, remove unused vars, and remove project-related parameters from `updateAgentHandler`

* chore: address ESLint errors

* chore: revert removal of unused vars for versioning

---------

Co-authored-by: Atef Bellaaj <slalom.bellaaj@external.daimlertruck.com>

packages/data-provider/src/accessPermissions.ts

@@ -0,0 +1,292 @@
+import { z } from 'zod';
+
+/**
+ * Granular Permission System Types for Agent Sharing
+ *
+ * This file contains TypeScript interfaces and Zod schemas for the enhanced
+ * agent permission system that supports sharing with specific users/groups
+ * and Entra ID integration.
+ */
+
+// ===== ENUMS & CONSTANTS =====
+
+/**
+ * Principal types for permission system
+ */
+export type TPrincipalType = 'user' | 'group' | 'public';
+
+/**
+ * Source of the principal (local LibreChat or external Entra ID)
+ */
+export type TPrincipalSource = 'local' | 'entra';
+
+/**
+ * Access levels for agents
+ */
+export type TAccessLevel = 'none' | 'viewer' | 'editor' | 'owner';
+
+/**
+ * Permission bit constants for bitwise operations
+ */
+export const PERMISSION_BITS = {
+  VIEW: 1, // 001 - Can view and use agent
+  EDIT: 2, // 010 - Can modify agent settings
+  DELETE: 4, // 100 - Can delete agent
+  SHARE: 8, // 1000 - Can share agent with others (future)
+} as const;
+
+/**
+ * Standard access role IDs
+ */
+export const ACCESS_ROLE_IDS = {
+  AGENT_VIEWER: 'agent_viewer',
+  AGENT_EDITOR: 'agent_editor',
+  AGENT_OWNER: 'agent_owner', // Future use
+} as const;
+
+// ===== ZOD SCHEMAS =====
+
+/**
+ * Principal schema - represents a user, group, or public access
+ */
+export const principalSchema = z.object({
+  type: z.enum(['user', 'group', 'public']),
+  id: z.string().optional(), // undefined for 'public' type
+  name: z.string().optional(),
+  email: z.string().optional(), // for user and group types
+  source: z.enum(['local', 'entra']).optional(),
+  avatar: z.string().optional(), // for user and group types
+  description: z.string().optional(), // for group type
+  idOnTheSource: z.string().optional(), // Entra ID for users/groups
+  accessRoleId: z.string().optional(), // Access role ID for permissions
+  memberCount: z.number().optional(), // for group type
+});
+
+/**
+ * Access role schema - defines named permission sets
+ */
+export const accessRoleSchema = z.object({
+  accessRoleId: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  resourceType: z.string().default('agent'),
+  permBits: z.number(),
+});
+
+/**
+ * Permission entry schema - represents a single ACL entry
+ */
+export const permissionEntrySchema = z.object({
+  id: z.string(),
+  principalType: z.enum(['user', 'group', 'public']),
+  principalId: z.string().optional(), // undefined for 'public'
+  principalName: z.string().optional(),
+  role: accessRoleSchema,
+  grantedBy: z.string(),
+  grantedAt: z.string(), // ISO date string
+  inheritedFrom: z.string().optional(), // for project-level inheritance
+  source: z.enum(['local', 'entra']).optional(),
+});
+
+/**
+ * Resource permissions response schema
+ */
+export const resourcePermissionsResponseSchema = z.object({
+  resourceType: z.string(),
+  resourceId: z.string(),
+  permissions: z.array(permissionEntrySchema),
+});
+
+/**
+ * Update resource permissions request schema
+ * This matches the user's requirement for the frontend DTO structure
+ */
+export const updateResourcePermissionsRequestSchema = z.object({
+  updated: principalSchema.array(),
+  removed: principalSchema.array(),
+  public: z.boolean(),
+  publicAccessRoleId: z.string().optional(),
+});
+
+/**
+ * Update resource permissions response schema
+ * Returns the updated permissions with accessRoleId included
+ */
+export const updateResourcePermissionsResponseSchema = z.object({
+  message: z.string(),
+  results: z.object({
+    principals: principalSchema.array(),
+    public: z.boolean(),
+    publicAccessRoleId: z.string().optional(),
+  }),
+});
+
+// ===== TYPESCRIPT TYPES =====
+
+/**
+ * Principal - represents a user, group, or public access
+ */
+export type TPrincipal = z.infer<typeof principalSchema>;
+
+/**
+ * Access role - defines named permission sets
+ */
+export type TAccessRole = z.infer<typeof accessRoleSchema>;
+
+/**
+ * Permission entry - represents a single ACL entry
+ */
+export type TPermissionEntry = z.infer<typeof permissionEntrySchema>;
+
+/**
+ * Resource permissions response
+ */
+export type TResourcePermissionsResponse = z.infer<typeof resourcePermissionsResponseSchema>;
+
+/**
+ * Update resource permissions request
+ * This matches the user's requirement for the frontend DTO structure
+ */
+export type TUpdateResourcePermissionsRequest = z.infer<
+  typeof updateResourcePermissionsRequestSchema
+>;
+
+/**
+ * Update resource permissions response
+ * Returns the updated permissions with accessRoleId included
+ */
+export type TUpdateResourcePermissionsResponse = z.infer<
+  typeof updateResourcePermissionsResponseSchema
+>;
+
+/**
+ * Principal search request parameters
+ */
+export type TPrincipalSearchParams = {
+  q: string; // search query (required)
+  limit?: number; // max results (1-50, default 10)
+  type?: 'user' | 'group'; // filter by type (optional)
+};
+
+/**
+ * Principal search result item
+ */
+export type TPrincipalSearchResult = {
+  id?: string | null; // null for Entra ID principals that don't exist locally yet
+  type: 'user' | 'group';
+  name: string;
+  email?: string; // for users and groups
+  username?: string; // for users
+  avatar?: string; // for users and groups
+  provider?: string; // for users
+  source: 'local' | 'entra';
+  memberCount?: number; // for groups
+  description?: string; // for groups
+  idOnTheSource?: string; // Entra ID for users (maps to openidId) and groups (maps to idOnTheSource)
+};
+
+/**
+ * Principal search response
+ */
+export type TPrincipalSearchResponse = {
+  query: string;
+  limit: number;
+  type?: 'user' | 'group';
+  results: TPrincipalSearchResult[];
+  count: number;
+  sources: {
+    local: number;
+    entra: number;
+  };
+};
+
+/**
+ * Available roles response
+ */
+export type TAvailableRolesResponse = {
+  resourceType: string;
+  roles: TAccessRole[];
+};
+
+/**
+ * Get resource permissions response schema
+ * This matches the enhanced aggregation-based endpoint response format
+ */
+export const getResourcePermissionsResponseSchema = z.object({
+  resourceType: z.string(),
+  resourceId: z.string(),
+  principals: z.array(principalSchema),
+  public: z.boolean(),
+  publicAccessRoleId: z.string().optional(),
+});
+
+/**
+ * Get resource permissions response type
+ * This matches the enhanced aggregation-based endpoint response format
+ */
+export type TGetResourcePermissionsResponse = z.infer<typeof getResourcePermissionsResponseSchema>;
+
+/**
+ * Effective permissions response schema
+ * Returns just the permission bitmask for a user on a resource
+ */
+export const effectivePermissionsResponseSchema = z.object({
+  permissionBits: z.number(),
+});
+
+/**
+ * Effective permissions response type
+ * Returns just the permission bitmask for a user on a resource
+ */
+export type TEffectivePermissionsResponse = z.infer<typeof effectivePermissionsResponseSchema>;
+
+// ===== UTILITY TYPES =====
+
+/**
+ * Permission check result
+ */
+export interface TPermissionCheck {
+  canView: boolean;
+  canEdit: boolean;
+  canDelete: boolean;
+  canShare: boolean;
+  accessLevel: TAccessLevel;
+}
+
+// ===== HELPER FUNCTIONS =====
+
+/**
+ * Convert permission bits to access level
+ */
+export function permBitsToAccessLevel(permBits: number): TAccessLevel {
+  if ((permBits & PERMISSION_BITS.DELETE) > 0) return 'owner';
+  if ((permBits & PERMISSION_BITS.EDIT) > 0) return 'editor';
+  if ((permBits & PERMISSION_BITS.VIEW) > 0) return 'viewer';
+  return 'none';
+}
+
+/**
+ * Convert access role ID to permission bits
+ */
+export function accessRoleToPermBits(accessRoleId: string): number {
+  switch (accessRoleId) {
+    case ACCESS_ROLE_IDS.AGENT_VIEWER:
+      return PERMISSION_BITS.VIEW;
+    case ACCESS_ROLE_IDS.AGENT_EDITOR:
+      return PERMISSION_BITS.VIEW | PERMISSION_BITS.EDIT;
+    case ACCESS_ROLE_IDS.AGENT_OWNER:
+      return PERMISSION_BITS.VIEW | PERMISSION_BITS.EDIT | PERMISSION_BITS.DELETE;
+    default:
+      return PERMISSION_BITS.VIEW;
+  }
+}
+
+/**
+ * Check if permission bitmask contains other bitmask
+ * @param permissions - The permission bitmask to check
+ * @param requiredPermission - The required permission bit(s)
+ * @returns {boolean} Whether permissions contains requiredPermission
+ */
+export function hasPermissions(permissions: number, requiredPermission: number): boolean {
+  return (permissions & requiredPermission) === requiredPermission;
+}

packages/data-provider/src/api-endpoints.ts

@@ -287,3 +287,29 @@ export const verifyTwoFactorTemp = () => '/api/auth/2fa/verify-temp';
 export const memories = () => '/api/memories';
 export const memory = (key: string) => `${memories()}/${encodeURIComponent(key)}`;
 export const memoryPreferences = () => `${memories()}/preferences`;
+
+export const searchPrincipals = (params: q.PrincipalSearchParams) => {
+  const { q: query, limit, type } = params;
+  let url = `/api/permissions/search-principals?q=${encodeURIComponent(query)}`;
+
+  if (limit !== undefined) {
+    url += `&limit=${limit}`;
+  }
+
+  if (type !== undefined) {
+    url += `&type=${type}`;
+  }
+
+  return url;
+};
+
+export const getAccessRoles = (resourceType: string) => `/api/permissions/${resourceType}/roles`;
+
+export const getResourcePermissions = (resourceType: string, resourceId: string) =>
+  `/api/permissions/${resourceType}/${resourceId}`;
+
+export const updateResourcePermissions = (resourceType: string, resourceId: string) =>
+  `/api/permissions/${resourceType}/${resourceId}`;
+
+export const getEffectivePermissions = (resourceType: string, resourceId: string) =>
+  `/api/permissions/${resourceType}/${resourceId}/effective`;

packages/data-provider/src/data-service.ts

@@ -10,6 +10,7 @@ import * as config from './config';
 import request from './request';
 import * as s from './schemas';
 import * as r from './roles';
+import * as permissions from './accessPermissions';
 
 export function revokeUserKey(name: string): Promise<unknown> {
   return request.delete(endpoints.revokeUserKey(name));
@@ -387,6 +388,14 @@ export const getAgentById = ({ agent_id }: { agent_id: string }): Promise<a.Agen
   );
 };
 
+export const getExpandedAgentById = ({ agent_id }: { agent_id: string }): Promise<a.Agent> => {
+  return request.get(
+    endpoints.agents({
+      path: `${agent_id}/expanded`,
+    }),
+  );
+};
+
 export const updateAgent = ({
   agent_id,
   data,
@@ -832,3 +841,35 @@ export const createMemory = (data: {
 }): Promise<{ created: boolean; memory: q.TUserMemory }> => {
   return request.post(endpoints.memories(), data);
 };
+
+export function searchPrincipals(
+  params: q.PrincipalSearchParams,
+): Promise<q.PrincipalSearchResponse> {
+  return request.get(endpoints.searchPrincipals(params));
+}
+
+export function getAccessRoles(resourceType: string): Promise<q.AccessRolesResponse> {
+  return request.get(endpoints.getAccessRoles(resourceType));
+}
+
+export function getResourcePermissions(
+  resourceType: string,
+  resourceId: string,
+): Promise<permissions.TGetResourcePermissionsResponse> {
+  return request.get(endpoints.getResourcePermissions(resourceType, resourceId));
+}
+
+export function updateResourcePermissions(
+  resourceType: string,
+  resourceId: string,
+  data: permissions.TUpdateResourcePermissionsRequest,
+): Promise<permissions.TUpdateResourcePermissionsResponse> {
+  return request.put(endpoints.updateResourcePermissions(resourceType, resourceId), data);
+}
+
+export function getEffectivePermissions(
+  resourceType: string,
+  resourceId: string,
+): Promise<permissions.TEffectivePermissionsResponse> {
+  return request.get(endpoints.getEffectivePermissions(resourceType, resourceId));
+}

packages/data-provider/src/index.ts

@@ -30,6 +30,9 @@ export * from './types/mutations';
 export * from './types/queries';
 export * from './types/runs';
 export * from './types/web';
+export * from './types/graph';
+/* access permissions */
+export * from './accessPermissions';
 /* query/mutation keys */
 export * from './keys';
 /* api call helpers */

packages/data-provider/src/keys.ts

@@ -48,6 +48,10 @@ export enum QueryKeys {
   banner = 'banner',
   /* Memories */
   memories = 'memories',
+  principalSearch = 'principalSearch',
+  accessRoles = 'accessRoles',
+  resourcePermissions = 'resourcePermissions',
+  effectivePermissions = 'effectivePermissions',
 }
 
 export enum MutationKeys {

packages/data-provider/src/react-query/react-query-service.ts

@@ -8,9 +8,13 @@ import { Constants, initialModelsConfig } from '../config';
 import { defaultOrderQuery } from '../types/assistants';
 import * as dataService from '../data-service';
 import * as m from '../types/mutations';
+import * as q from '../types/queries';
 import { QueryKeys } from '../keys';
 import * as s from '../schemas';
 import * as t from '../types';
+import * as permissions from '../accessPermissions';
+
+export { hasPermissions } from '../accessPermissions';
 
 export const useGetSharedMessages = (
   shareId: string,
@@ -346,3 +350,103 @@ export const useUpdateFeedbackMutation = (
     },
   );
 };
+
+export const useSearchPrincipalsQuery = (
+  params: q.PrincipalSearchParams,
+  config?: UseQueryOptions<q.PrincipalSearchResponse>,
+): QueryObserverResult<q.PrincipalSearchResponse> => {
+  return useQuery<q.PrincipalSearchResponse>(
+    [QueryKeys.principalSearch, params],
+    () => dataService.searchPrincipals(params),
+    {
+      enabled: !!params.q && params.q.length >= 2,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      staleTime: 30000,
+      ...config,
+    },
+  );
+};
+
+export const useGetAccessRolesQuery = (
+  resourceType: string,
+  config?: UseQueryOptions<q.AccessRolesResponse>,
+): QueryObserverResult<q.AccessRolesResponse> => {
+  return useQuery<q.AccessRolesResponse>(
+    [QueryKeys.accessRoles, resourceType],
+    () => dataService.getAccessRoles(resourceType),
+    {
+      enabled: !!resourceType,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      staleTime: 5 * 60 * 1000, // Cache for 5 minutes
+      ...config,
+    },
+  );
+};
+
+export const useGetResourcePermissionsQuery = (
+  resourceType: string,
+  resourceId: string,
+  config?: UseQueryOptions<permissions.TGetResourcePermissionsResponse>,
+): QueryObserverResult<permissions.TGetResourcePermissionsResponse> => {
+  return useQuery<permissions.TGetResourcePermissionsResponse>(
+    [QueryKeys.resourcePermissions, resourceType, resourceId],
+    () => dataService.getResourcePermissions(resourceType, resourceId),
+    {
+      enabled: !!resourceType && !!resourceId,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      staleTime: 2 * 60 * 1000, // Cache for 2 minutes
+      ...config,
+    },
+  );
+};
+
+export const useUpdateResourcePermissionsMutation = (): UseMutationResult<
+  permissions.TUpdateResourcePermissionsResponse,
+  Error,
+  {
+    resourceType: string;
+    resourceId: string;
+    data: permissions.TUpdateResourcePermissionsRequest;
+  }
+> => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ resourceType, resourceId, data }) =>
+      dataService.updateResourcePermissions(resourceType, resourceId, data),
+    onSuccess: (_, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: [QueryKeys.accessRoles, variables.resourceType],
+      });
+
+      queryClient.invalidateQueries({
+        queryKey: [QueryKeys.resourcePermissions, variables.resourceType, variables.resourceId],
+      });
+
+      queryClient.invalidateQueries({
+        queryKey: [QueryKeys.effectivePermissions, variables.resourceType, variables.resourceId],
+      });
+    },
+  });
+};
+
+export const useGetEffectivePermissionsQuery = (
+  resourceType: string,
+  resourceId: string,
+  config?: UseQueryOptions<permissions.TEffectivePermissionsResponse>,
+): QueryObserverResult<permissions.TEffectivePermissionsResponse> => {
+  return useQuery<permissions.TEffectivePermissionsResponse>({
+    queryKey: [QueryKeys.effectivePermissions, resourceType, resourceId],
+    queryFn: () => dataService.getEffectivePermissions(resourceType, resourceId),
+    enabled: !!resourceType && !!resourceId,
+    refetchOnWindowFocus: false,
+    staleTime: 30000,
+    ...config,
+  });
+};

packages/data-provider/src/schemas.ts

@@ -159,6 +159,7 @@ export const defaultAgentFormValues = {
   provider: {},
   projectIds: [],
   artifacts: '',
+  /** @deprecated Use ACL permissions instead */
   isCollaborative: false,
   recursion_limit: undefined,
   [Tools.execute_code]: false,

packages/data-provider/src/types/assistants.ts

@@ -198,6 +198,7 @@ export interface AgentFileResource extends AgentBaseResource {
 }
 
 export type Agent = {
+  _id?: string;
   id: string;
   name: string | null;
   author?: string | null;
@@ -217,6 +218,7 @@ export type Agent = {
   model: string | null;
   model_parameters: AgentModelParameters;
   conversation_starters?: string[];
+  /** @deprecated Use ACL permissions instead */
   isCollaborative?: boolean;
   tool_resources?: AgentToolResources;
   agent_ids?: string[];
@@ -224,6 +226,7 @@ export type Agent = {
   hide_sequential_outputs?: boolean;
   artifacts?: ArtifactModes;
   recursion_limit?: number;
+  isPublic?: boolean;
   version?: number;
 };
 

packages/data-provider/src/types/graph.ts

@@ -0,0 +1,145 @@
+/**
+ * Microsoft Graph API type definitions
+ * Based on Microsoft Graph REST API v1.0 documentation
+ */
+
+/**
+ * Person type information from Microsoft Graph People API
+ */
+export interface TGraphPersonType {
+  /** Classification of the entity: "Person" or "Group" */
+  class: 'Person' | 'Group';
+  /** Specific subtype: e.g., "OrganizationUser", "UnifiedGroup" */
+  subclass: string;
+}
+
+/**
+ * Scored email address from Microsoft Graph People API
+ */
+export interface TGraphScoredEmailAddress {
+  /** Email address */
+  address: string;
+  /** Relevance score (0.0 to 1.0) */
+  relevanceScore: number;
+}
+
+/**
+ * Phone number from Microsoft Graph API
+ */
+export interface TGraphPhone {
+  /** Type of phone number */
+  type: string;
+  /** Phone number */
+  number: string;
+}
+
+/**
+ * Person/Contact result from Microsoft Graph /me/people endpoint
+ */
+export interface TGraphPerson {
+  /** Unique identifier */
+  id: string;
+  /** Display name */
+  displayName: string;
+  /** Given name (first name) */
+  givenName?: string;
+  /** Surname (last name) */
+  surname?: string;
+  /** User principal name */
+  userPrincipalName?: string;
+  /** Job title */
+  jobTitle?: string;
+  /** Department */
+  department?: string;
+  /** Company name */
+  companyName?: string;
+  /** Primary email address */
+  mail?: string;
+  /** Scored email addresses with relevance */
+  scoredEmailAddresses?: TGraphScoredEmailAddress[];
+  /** Person type classification */
+  personType?: TGraphPersonType;
+  /** Phone numbers */
+  phones?: TGraphPhone[];
+}
+
+/**
+ * User result from Microsoft Graph /users endpoint
+ */
+export interface TGraphUser {
+  /** Unique identifier */
+  id: string;
+  /** Display name */
+  displayName: string;
+  /** Given name (first name) */
+  givenName?: string;
+  /** Surname (last name) */
+  surname?: string;
+  /** User principal name */
+  userPrincipalName: string;
+  /** Primary email address */
+  mail?: string;
+  /** Job title */
+  jobTitle?: string;
+  /** Department */
+  department?: string;
+  /** Office location */
+  officeLocation?: string;
+  /** Business phone numbers */
+  businessPhones?: string[];
+  /** Mobile phone number */
+  mobilePhone?: string;
+}
+
+/**
+ * Group result from Microsoft Graph /groups endpoint
+ */
+export interface TGraphGroup {
+  /** Unique identifier */
+  id: string;
+  /** Display name */
+  displayName: string;
+  /** Group email address */
+  mail?: string;
+  /** Mail nickname */
+  mailNickname?: string;
+  /** Group description */
+  description?: string;
+  /** Group types (e.g., ["Unified"] for Microsoft 365 groups) */
+  groupTypes?: string[];
+  /** Whether group is mail-enabled */
+  mailEnabled?: boolean;
+  /** Whether group is security-enabled */
+  securityEnabled?: boolean;
+  /** Resource provisioning options */
+  resourceProvisioningOptions?: string[];
+}
+
+/**
+ * Response wrapper for Microsoft Graph API list endpoints
+ */
+export interface TGraphListResponse<T> {
+  /** Array of results */
+  value: T[];
+  /** OData context */
+  '@odata.context'?: string;
+  /** Next page link */
+  '@odata.nextLink'?: string;
+  /** Count of results (if requested) */
+  '@odata.count'?: number;
+}
+
+/**
+ * Response from /me/people endpoint
+ */
+export type TGraphPeopleResponse = TGraphListResponse<TGraphPerson>;
+
+/**
+ * Response from /users endpoint
+ */
+export type TGraphUsersResponse = TGraphListResponse<TGraphUser>;
+
+/**
+ * Response from /groups endpoint
+ */
+export type TGraphGroupsResponse = TGraphListResponse<TGraphGroup>;

packages/data-provider/src/types/queries.ts

@@ -124,3 +124,44 @@ export type MemoriesResponse = {
   tokenLimit: number | null;
   usagePercentage: number | null;
 };
+
+export type PrincipalSearchParams = {
+  q: string;
+  limit?: number;
+  type?: 'user' | 'group';
+};
+
+export type PrincipalSearchResult = {
+  id?: string | null;
+  type: 'user' | 'group';
+  name: string;
+  email?: string;
+  username?: string;
+  avatar?: string;
+  provider?: string;
+  source: 'local' | 'entra';
+  memberCount?: number;
+  description?: string;
+  idOnTheSource?: string;
+};
+
+export type PrincipalSearchResponse = {
+  query: string;
+  limit: number;
+  type?: 'user' | 'group';
+  results: PrincipalSearchResult[];
+  count: number;
+  sources: {
+    local: number;
+    entra: number;
+  };
+};
+
+export type AccessRole = {
+  accessRoleId: string;
+  name: string;
+  description: string;
+  permBits: number;
+};
+
+export type AccessRolesResponse = AccessRole[];