🔐 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/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';