🔐 feat: Admin Auth. Routes with Secure Cross-Origin Token Exchange (#11297)

* feat: implement admin authentication with OpenID & Local Auth proxy support

* feat: implement admin OAuth exchange flow with caching support

- Added caching for admin OAuth exchange codes with a short TTL.
- Introduced new endpoints for generating and exchanging admin OAuth codes.
- Updated relevant controllers and routes to handle admin panel redirects and token exchanges.
- Enhanced logging for better traceability of OAuth operations.

* refactor: enhance OpenID strategy mock to support multiple verify callbacks

- Updated the OpenID strategy mock to store and retrieve verify callbacks by strategy name.
- Improved backward compatibility by maintaining a method to get the last registered callback.
- Adjusted tests to utilize the new callback retrieval methods, ensuring clarity in the verification process for the 'openid' strategy.

* refactor: reorder import statements for better organization

* refactor: admin OAuth flow with improved URL handling and validation

- Added a utility function to retrieve the admin panel URL, defaulting to a local development URL if not set in the environment.
- Updated the OAuth exchange endpoint to include validation for the authorization code format.
- Refactored the admin panel redirect logic to handle URL parsing more robustly, ensuring accurate origin comparisons.
- Removed redundant local URL definitions from the codebase for better maintainability.

* refactor: remove deprecated requireAdmin middleware and migrate to TypeScript

- Deleted the old requireAdmin middleware file and its references in the middleware index.
- Introduced a new TypeScript version of the requireAdmin middleware with enhanced error handling and logging.
- Updated routes to utilize the new requireAdmin middleware, ensuring consistent access control for admin routes.

* feat: add requireAdmin middleware for admin role verification

- Introduced requireAdmin middleware to enforce admin role checks for authenticated users.
- Implemented comprehensive error handling and logging for unauthorized access attempts.
- Added unit tests to validate middleware functionality and ensure proper behavior for different user roles.
- Updated middleware index to include the new requireAdmin export.

packages/api/src/auth/exchange.ts

@@ -0,0 +1,157 @@
+import crypto from 'crypto';
+import { Keyv } from 'keyv';
+import { logger } from '@librechat/data-schemas';
+import type { IUser } from '@librechat/data-schemas';
+
+/** Default admin panel URL for local development */
+const DEFAULT_ADMIN_PANEL_URL = 'http://localhost:3000';
+
+/**
+ * Gets the admin panel URL from environment or falls back to default.
+ * @returns The admin panel URL
+ */
+export function getAdminPanelUrl(): string {
+  return process.env.ADMIN_PANEL_URL || DEFAULT_ADMIN_PANEL_URL;
+}
+
+/**
+ * User data stored in the exchange cache
+ */
+export interface AdminExchangeUser {
+  _id: string;
+  id: string;
+  email: string;
+  name: string;
+  username: string;
+  role: string;
+  avatar?: string;
+  provider?: string;
+  openidId?: string;
+}
+
+/**
+ * Data stored in cache for admin OAuth exchange
+ */
+export interface AdminExchangeData {
+  userId: string;
+  user: AdminExchangeUser;
+  token: string;
+  refreshToken?: string;
+}
+
+/**
+ * Response from the exchange endpoint
+ */
+export interface AdminExchangeResponse {
+  token: string;
+  refreshToken?: string;
+  user: AdminExchangeUser;
+}
+
+/**
+ * Serializes user data for the exchange cache.
+ * @param user - The authenticated user object
+ * @returns Serialized user data for admin panel
+ */
+export function serializeUserForExchange(user: IUser): AdminExchangeUser {
+  const userId = String(user._id);
+  return {
+    _id: userId,
+    id: userId,
+    email: user.email,
+    name: user.name ?? '',
+    username: user.username ?? '',
+    role: user.role ?? 'USER',
+    avatar: user.avatar,
+    provider: user.provider,
+    openidId: user.openidId,
+  };
+}
+
+/**
+ * Generates an exchange code and stores user data for admin panel OAuth flow.
+ * @param cache - The Keyv cache instance for storing exchange data
+ * @param user - The authenticated user object
+ * @param token - The JWT access token
+ * @param refreshToken - Optional refresh token for OpenID users
+ * @returns The generated exchange code
+ */
+export async function generateAdminExchangeCode(
+  cache: Keyv,
+  user: IUser,
+  token: string,
+  refreshToken?: string,
+): Promise<string> {
+  const exchangeCode = crypto.randomBytes(32).toString('hex');
+
+  const data: AdminExchangeData = {
+    userId: String(user._id),
+    user: serializeUserForExchange(user),
+    token,
+    refreshToken,
+  };
+
+  await cache.set(exchangeCode, data);
+
+  logger.info(`[adminExchange] Generated exchange code for user: ${user.email}`);
+
+  return exchangeCode;
+}
+
+/**
+ * Exchanges an authorization code for tokens and user data.
+ * The code is deleted immediately after retrieval (one-time use).
+ * @param cache - The Keyv cache instance for retrieving exchange data
+ * @param code - The authorization code to exchange
+ * @returns The exchange response with token, refreshToken, and user data, or null if invalid/expired
+ */
+export async function exchangeAdminCode(
+  cache: Keyv,
+  code: string,
+): Promise<AdminExchangeResponse | null> {
+  const data = (await cache.get(code)) as AdminExchangeData | undefined;
+
+  /** Delete immediately - one-time use */
+  await cache.delete(code);
+
+  if (!data) {
+    logger.warn('[adminExchange] Invalid or expired authorization code');
+    return null;
+  }
+
+  logger.info(`[adminExchange] Exchanged code for user: ${data.user?.email}`);
+
+  return {
+    token: data.token,
+    refreshToken: data.refreshToken,
+    user: data.user,
+  };
+}
+
+/**
+ * Checks if the redirect URI is for the admin panel (cross-origin).
+ * Uses proper URL parsing to compare origins, handling edge cases where
+ * both URLs might share the same prefix (e.g., localhost:3000 vs localhost:3001).
+ *
+ * @param redirectUri - The redirect URI to check.
+ * @param adminPanelUrl - The admin panel URL (defaults to ADMIN_PANEL_URL env var)
+ * @param domainClient - The main client domain
+ * @returns True if redirecting to admin panel (different origin from main client).
+ */
+export function isAdminPanelRedirect(
+  redirectUri: string,
+  adminPanelUrl: string,
+  domainClient: string,
+): boolean {
+  try {
+    const redirectOrigin = new URL(redirectUri).origin;
+    const adminOrigin = new URL(adminPanelUrl).origin;
+    const clientOrigin = new URL(domainClient).origin;
+
+    /** Redirect is for admin panel if it matches admin origin but not main client origin */
+    return redirectOrigin === adminOrigin && redirectOrigin !== clientOrigin;
+  } catch {
+    /** If URL parsing fails, fall back to simple string comparison */
+    return redirectUri.startsWith(adminPanelUrl) && !redirectUri.startsWith(domainClient);
+  }
+}

packages/api/src/auth/index.ts

@@ -1,2 +1,3 @@
 export * from './domain';
 export * from './openid';
+export * from './exchange';

packages/api/src/middleware/admin.spec.ts

@@ -0,0 +1,140 @@
+import { logger } from '@librechat/data-schemas';
+import { SystemRoles } from 'librechat-data-provider';
+import { requireAdmin } from './admin';
+import type { Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+
+jest.mock('@librechat/data-schemas', () => ({
+  ...jest.requireActual('@librechat/data-schemas'),
+  logger: {
+    warn: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+describe('requireAdmin middleware', () => {
+  let mockReq: Partial<ServerRequest>;
+  let mockRes: Partial<Response>;
+  let mockNext: jest.Mock;
+  let jsonMock: jest.Mock;
+  let statusMock: jest.Mock;
+
+  beforeEach(() => {
+    jsonMock = jest.fn();
+    statusMock = jest.fn().mockReturnValue({ json: jsonMock });
+
+    mockReq = {};
+    mockRes = {
+      status: statusMock,
+    };
+    mockNext = jest.fn();
+
+    (logger.warn as jest.Mock).mockClear();
+    (logger.debug as jest.Mock).mockClear();
+  });
+
+  describe('when no user is present', () => {
+    it('should return 401 with AUTHENTICATION_REQUIRED error', () => {
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(statusMock).toHaveBeenCalledWith(401);
+      expect(jsonMock).toHaveBeenCalledWith({
+        error: 'Authentication required',
+        error_code: 'AUTHENTICATION_REQUIRED',
+      });
+      expect(mockNext).not.toHaveBeenCalled();
+      expect(logger.warn).toHaveBeenCalledWith('[requireAdmin] No user found in request');
+    });
+
+    it('should return 401 when user is undefined', () => {
+      mockReq.user = undefined;
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(statusMock).toHaveBeenCalledWith(401);
+      expect(jsonMock).toHaveBeenCalledWith({
+        error: 'Authentication required',
+        error_code: 'AUTHENTICATION_REQUIRED',
+      });
+      expect(mockNext).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('when user does not have admin role', () => {
+    it('should return 403 when user has no role property', () => {
+      mockReq.user = { email: 'user@test.com' } as ServerRequest['user'];
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(statusMock).toHaveBeenCalledWith(403);
+      expect(jsonMock).toHaveBeenCalledWith({
+        error: 'Access denied: Admin privileges required',
+        error_code: 'ADMIN_REQUIRED',
+      });
+      expect(mockNext).not.toHaveBeenCalled();
+      expect(logger.debug).toHaveBeenCalledWith(
+        '[requireAdmin] Access denied for non-admin user: user@test.com',
+      );
+    });
+
+    it('should return 403 when user has USER role', () => {
+      mockReq.user = {
+        email: 'user@test.com',
+        role: SystemRoles.USER,
+      } as ServerRequest['user'];
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(statusMock).toHaveBeenCalledWith(403);
+      expect(jsonMock).toHaveBeenCalledWith({
+        error: 'Access denied: Admin privileges required',
+        error_code: 'ADMIN_REQUIRED',
+      });
+      expect(mockNext).not.toHaveBeenCalled();
+    });
+
+    it('should return 403 when user has empty string role', () => {
+      mockReq.user = {
+        email: 'user@test.com',
+        role: '',
+      } as ServerRequest['user'];
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(statusMock).toHaveBeenCalledWith(403);
+      expect(jsonMock).toHaveBeenCalledWith({
+        error: 'Access denied: Admin privileges required',
+        error_code: 'ADMIN_REQUIRED',
+      });
+      expect(mockNext).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('when user has admin role', () => {
+    it('should call next() and not send response', () => {
+      mockReq.user = {
+        email: 'admin@test.com',
+        role: SystemRoles.ADMIN,
+      } as ServerRequest['user'];
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(mockNext).toHaveBeenCalledTimes(1);
+      expect(mockNext).toHaveBeenCalledWith();
+      expect(statusMock).not.toHaveBeenCalled();
+      expect(jsonMock).not.toHaveBeenCalled();
+    });
+
+    it('should not log any warnings or debug messages for admin users', () => {
+      mockReq.user = {
+        email: 'admin@test.com',
+        role: SystemRoles.ADMIN,
+      } as ServerRequest['user'];
+
+      requireAdmin(mockReq as ServerRequest, mockRes as Response, mockNext);
+
+      expect(logger.warn).not.toHaveBeenCalled();
+      expect(logger.debug).not.toHaveBeenCalled();
+    });
+  });
+});

packages/api/src/middleware/admin.ts

@@ -0,0 +1,28 @@
+import { logger } from '@librechat/data-schemas';
+import { SystemRoles } from 'librechat-data-provider';
+import type { NextFunction, Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+
+/**
+ * Middleware to check if authenticated user has admin role.
+ * Should be used AFTER authentication middleware (requireJwtAuth, requireLocalAuth, etc.)
+ */
+export const requireAdmin = (req: ServerRequest, res: Response, next: NextFunction) => {
+  if (!req.user) {
+    logger.warn('[requireAdmin] No user found in request');
+    return res.status(401).json({
+      error: 'Authentication required',
+      error_code: 'AUTHENTICATION_REQUIRED',
+    });
+  }
+
+  if (!req.user.role || req.user.role !== SystemRoles.ADMIN) {
+    logger.debug(`[requireAdmin] Access denied for non-admin user: ${req.user.email}`);
+    return res.status(403).json({
+      error: 'Access denied: Admin privileges required',
+      error_code: 'ADMIN_REQUIRED',
+    });
+  }
+
+  next();
+};

packages/api/src/middleware/index.ts

@@ -1,4 +1,5 @@
 export * from './access';
+export * from './admin';
 export * from './error';
 export * from './balance';
 export * from './json';