🧲 fix: Match Directory Users to Existing Principals (#15855)

* fix: Preserve Directory Identity Ownership

* fix: Fail Closed on Identity Conflicts

* fix: Resolve Existing Sharing Principals Safely

Author: danny-avila

api/server/services/AuthService.js

@@ -1005,8 +1005,8 @@ const resendVerificationEmail = async (req) => {
   } catch (error) {
     logger.error(`[resendVerificationEmail] Error resending verification email: ${error.message}`);
     return {
-      status: 500,
-      message: 'Something went wrong.',
+      status: 200,
+      message: genericVerificationMessage,
     };
   }
 };

api/server/services/AuthService.spec.js

@@ -1227,6 +1227,26 @@ describe('resendVerificationEmail', () => {
       }),
     );
   });
+
+  it('returns the generic response when delivery fails', async () => {
+    const user = {
+      _id: 'user-delivery-failure',
+      email: 'delivery-failure@example.com',
+      name: 'Delivery Failure',
+    };
+    findUser.mockResolvedValue(user);
+    sendEmail.mockRejectedValue(new Error('mail transport unavailable'));
+
+    const result = await resendVerificationEmail({ body: { email: user.email } });
+
+    expect(result).toEqual({
+      status: 200,
+      message: 'Please check your email to verify your email address.',
+    });
+    expect(logger.error).toHaveBeenCalledWith(
+      '[resendVerificationEmail] Error resending verification email: mail transport unavailable',
+    );
+  });
 });
 
 describe('CloudFront cookie integration', () => {

api/server/services/PermissionService.js

@@ -1,5 +1,5 @@
 const mongoose = require('mongoose');
-const { AccessControlService, isEnabled } = require('@librechat/api');
+const { AccessControlService, isEnabled, ensureDirectoryPrincipalUser } = require('@librechat/api');
 const {
   tenantStorage,
   getTenantId,
@@ -337,36 +337,20 @@ const ensurePrincipalExists = async function (principal) {
   }
 
   if (principal.type === PrincipalType.USER && principal.source === 'entra') {
-    if (!principal.email || !principal.idOnTheSource) {
-      throw new Error('Entra ID user principals must have email and idOnTheSource');
-    }
-
-    let existingUser = await db.findUser({ idOnTheSource: principal.idOnTheSource });
-
-    if (!existingUser) {
-      existingUser = await db.findUser({ email: principal.email });
-    }
-
-    if (existingUser) {
-      if (!existingUser.idOnTheSource && principal.idOnTheSource) {
-        await db.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 db.createUser(userData, true, true);
-    return userId.toString();
+    return ensureDirectoryPrincipalUser(principal, {
+      findUserBySourceId: async (idOnTheSource) => {
+        const user = await db.findUser({ idOnTheSource });
+        return user ? { id: user._id.toString() } : null;
+      },
+      findUserByEmail: async (email) => {
+        const user = await db.findUser({ email });
+        return user ? { id: user._id.toString() } : null;
+      },
+      createUser: async (userData) => {
+        const userId = await db.createUser(userData, true, true);
+        return userId.toString();
+      },
+    });
   }
 
   if (principal.type === PrincipalType.GROUP) {

api/server/services/PermissionService.spec.js

@@ -296,6 +296,46 @@ describe('PermissionService', () => {
       expect(principalId).toBe(currentUser._id.toString());
     });
 
+    test('accepts a directory user already linked to the supplied source id', async () => {
+      const directoryUser = await User.create({
+        name: 'ACL Principal Directory User',
+        email: 'acl-principal-directory-user@example.com',
+        provider: 'openid',
+        idOnTheSource: 'directory-user-id',
+      });
+
+      const principalId = await ensurePrincipalExists({
+        type: PrincipalType.USER,
+        name: directoryUser.name,
+        email: directoryUser.email,
+        source: 'entra',
+        idOnTheSource: directoryUser.idOnTheSource,
+      });
+
+      expect(principalId).toBe(directoryUser._id.toString());
+    });
+
+    test('uses an existing user found only by email without linking its identity', async () => {
+      const existingUser = await User.create({
+        name: 'ACL Principal Existing User',
+        email: 'acl-principal-existing-user@example.com',
+        provider: 'local',
+      });
+
+      const principalId = await ensurePrincipalExists({
+        type: PrincipalType.USER,
+        name: existingUser.name,
+        email: existingUser.email,
+        source: 'entra',
+        idOnTheSource: 'unlinked-directory-id',
+      });
+
+      const unchangedUser = await User.findById(existingUser._id).lean();
+      expect(principalId).toBe(existingUser._id.toString());
+      expect(unchangedUser.provider).toBe('local');
+      expect(unchangedUser.idOnTheSource).toBeUndefined();
+    });
+
     test('rejects a local group id outside the current request context', async () => {
       const outsideGroup = await Group.create({
         name: 'ACL Principal Outside Group',

packages/api/src/acl/principals.spec.ts

@@ -0,0 +1,54 @@
+import { ensureDirectoryPrincipalUser } from './principals';
+
+const createMethods = () => ({
+  findUserBySourceId: jest.fn().mockResolvedValue(null),
+  findUserByEmail: jest.fn().mockResolvedValue(null),
+  createUser: jest.fn().mockResolvedValue('created-user'),
+});
+
+const principal = {
+  name: 'Directory User',
+  email: 'Directory-User@Example.com',
+  idOnTheSource: 'directory-user-id',
+};
+
+describe('ensureDirectoryPrincipalUser', () => {
+  it('returns a user already linked to the directory source ID without an email lookup', async () => {
+    const methods = createMethods();
+    methods.findUserBySourceId.mockResolvedValue({ id: 'source-user' });
+
+    await expect(ensureDirectoryPrincipalUser(principal, methods)).resolves.toBe('source-user');
+    expect(methods.findUserByEmail).not.toHaveBeenCalled();
+    expect(methods.createUser).not.toHaveBeenCalled();
+  });
+
+  it('returns an existing user found by email without creating a placeholder', async () => {
+    const methods = createMethods();
+    methods.findUserByEmail.mockResolvedValue({ id: 'email-user' });
+
+    await expect(ensureDirectoryPrincipalUser(principal, methods)).resolves.toBe('email-user');
+    expect(methods.createUser).not.toHaveBeenCalled();
+  });
+
+  it('creates a normalized directory placeholder when neither identifier matches', async () => {
+    const methods = createMethods();
+
+    await expect(ensureDirectoryPrincipalUser(principal, methods)).resolves.toBe('created-user');
+    expect(methods.createUser).toHaveBeenCalledWith({
+      name: principal.name,
+      email: 'directory-user@example.com',
+      emailVerified: false,
+      provider: 'openid',
+      idOnTheSource: principal.idOnTheSource,
+    });
+  });
+
+  it('rejects incomplete directory principals before database access', async () => {
+    const methods = createMethods();
+
+    await expect(ensureDirectoryPrincipalUser({ name: 'Incomplete' }, methods)).rejects.toThrow(
+      'Directory user principals must have email and idOnTheSource',
+    );
+    expect(methods.findUserBySourceId).not.toHaveBeenCalled();
+  });
+});

packages/api/src/acl/principals.ts

@@ -0,0 +1,48 @@
+import type { TPrincipal } from 'librechat-data-provider';
+
+export interface DirectoryPrincipalUser {
+  id: string;
+}
+
+export interface DirectoryPrincipalUserData {
+  name?: string;
+  email: string;
+  emailVerified: false;
+  provider: 'openid';
+  idOnTheSource: string;
+}
+
+export interface DirectoryPrincipalUserMethods {
+  findUserBySourceId: (idOnTheSource: string) => Promise<DirectoryPrincipalUser | null>;
+  findUserByEmail: (email: string) => Promise<DirectoryPrincipalUser | null>;
+  createUser: (user: DirectoryPrincipalUserData) => Promise<string>;
+}
+
+type DirectoryPrincipal = Pick<TPrincipal, 'name' | 'email' | 'idOnTheSource'>;
+
+export const ensureDirectoryPrincipalUser = async (
+  principal: DirectoryPrincipal,
+  methods: DirectoryPrincipalUserMethods,
+): Promise<string> => {
+  if (!principal.email || !principal.idOnTheSource) {
+    throw new Error('Directory user principals must have email and idOnTheSource');
+  }
+
+  const userBySourceId = await methods.findUserBySourceId(principal.idOnTheSource);
+  if (userBySourceId) {
+    return userBySourceId.id;
+  }
+
+  const userByEmail = await methods.findUserByEmail(principal.email);
+  if (userByEmail) {
+    return userByEmail.id;
+  }
+
+  return methods.createUser({
+    name: principal.name,
+    email: principal.email.toLowerCase(),
+    emailVerified: false,
+    provider: 'openid',
+    idOnTheSource: principal.idOnTheSource,
+  });
+};

packages/api/src/index.ts

@@ -2,6 +2,7 @@ export * from './app';
 export * from './acl/accessControlService';
 export * from './acl/insightsPermissions';
 export * from './acl/middleware';
+export * from './acl/principals';
 export * from './credentials';
 /* Artifacts */
 export * from './artifacts';