Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🔄 feat: Cross-Origin Admin OAuth Refresh (#13007)

Dustin Healye262219c8fe1
diff --git a/api/server/controllers/auth/oauth.js b/api/server/controllers/auth/oauth.js
index 31499f7de6..3502be8a4c 100644
--- a/api/server/controllers/auth/oauth.js
+++ b/api/server/controllers/auth/oauth.js
@@ -46,6 +46,7 @@ function createOAuthHandler(redirectUri = domains.client) {
/** Get refresh token from tokenset for OpenID users */
const refreshToken =
req.user.tokenset?.refresh_token || req.user.federatedTokens?.refresh_token;
+ const expiresAt = Date.now() + sessionExpiry;
const callbackUrl = new URL(redirectUri);
const exchangeCode = await generateAdminExchangeCode(
@@ -55,6 +56,7 @@ function createOAuthHandler(redirectUri = domains.client) {
refreshToken,
callbackUrl.origin,
req.pkceChallenge,
+ expiresAt,
);
callbackUrl.searchParams.set('code', exchangeCode);
logger.info(`[OAuth] Admin panel redirect with exchange code for user: ${req.user.email}`);
diff --git a/api/server/routes/admin/auth.js b/api/server/routes/admin/auth.js
index 9b0ecb66a5..a385177e1f 100644
--- a/api/server/routes/admin/auth.js
+++ b/api/server/routes/admin/auth.js
@@ -1,19 +1,35 @@
const express = require('express');
const passport = require('passport');
const crypto = require('node:crypto');
+const openIdClient = require('openid-client');
const { CacheKeys } = require('librechat-data-provider');
-const { logger, SystemCapabilities } = require('@librechat/data-schemas');
const {
+ logger,
+ DEFAULT_SESSION_EXPIRY,
+ SystemCapabilities,
+ getTenantId,
+} = require('@librechat/data-schemas');
+const {
+ isEnabled,
getAdminPanelUrl,
exchangeAdminCode,
createSetBalanceConfig,
storeAndStripChallenge,
tenantContextMiddleware,
+ preAuthTenantMiddleware,
+ applyAdminRefresh,
+ AdminRefreshError,
} = require('@librechat/api');
const { loginController } = require('~/server/controllers/auth/LoginController');
-const { requireCapability } = require('~/server/middleware/roles/capabilities');
+const { hasCapability, requireCapability } = require('~/server/middleware/roles/capabilities');
const { createOAuthHandler } = require('~/server/controllers/auth/oauth');
-const { findBalanceByUser, upsertBalanceFields } = require('~/models');
+const {
+ findBalanceByUser,
+ findUsers,
+ generateToken,
+ getUserById,
+ upsertBalanceFields,
+} = require('~/models');
const { getAppConfig } = require('~/server/services/Config');
const getLogStores = require('~/cache/getLogStores');
const { getOpenIdConfig } = require('~/strategies');
@@ -464,4 +480,132 @@ router.post('/oauth/exchange', middleware.loginLimiter, async (req, res) => {
}
});
+/**
+ * Admin-panel-shaped token refresh.
+ *
+ * The standard `/api/auth/refresh` controller reads the refresh token from
+ * cookies, which a cross-origin admin panel can't set. This endpoint accepts
+ * the refresh token in the request body, exchanges it at the IdP, mints a
+ * fresh LibreChat JWT, and returns the same response shape as
+ * `/api/admin/oauth/exchange`.
+ *
+ * POST /api/admin/oauth/refresh
+ * Body: { refresh_token: string, user_id?: string }
+ * Response: { token: string, refreshToken?: string, user: object, expiresAt: number }
+ *
+ * Errors (all responses are `{ error: string, error_code: string }`):
+ * 400 MISSING_REFRESH_TOKEN — refresh_token absent or empty
+ * 401 REFRESH_FAILED — IdP rejected the refresh grant
+ * 401 USER_NOT_FOUND — no LibreChat user matches the refreshed sub
+ * 401 USER_ID_MISMATCH — supplied user_id resolves to a user with a different openidId
+ * 401 ISSUER_MISMATCH — refreshed tokenset was issued by an unexpected issuer
+ * 401 TENANT_MISMATCH — resolved user belongs to a different tenant than the request
+ * 403 FORBIDDEN — resolved user no longer holds ACCESS_ADMIN
+ * 403 TOKEN_REUSE_DISABLED — OPENID_REUSE_TOKENS is not enabled on the server
+ * 502 IDP_INCOMPLETE — IdP returned a tokenset missing access_token
+ * 502 CLAIMS_INCOMPLETE — IdP tokenset has no readable claims or no sub
+ * 503 OPENID_NOT_CONFIGURED — OpenID is not configured on this server
+ * 500 INTERNAL_ERROR — anything else (logged server-side)
+ */
+router.post(
+ '/oauth/refresh',
+ middleware.loginLimiter,
+ preAuthTenantMiddleware,
+ async (req, res) => {
+ try {
+ const { refresh_token: refreshToken, user_id: userId } = req.body ?? {};
+ if (typeof refreshToken !== 'string' || refreshToken.length === 0) {
+ return res.status(400).json({
+ error: 'Missing refresh_token',
+ error_code: 'MISSING_REFRESH_TOKEN',
+ });
+ }
+
+ if (!isEnabled(process.env.OPENID_REUSE_TOKENS)) {
+ return res.status(403).json({
+ error: 'OpenID token reuse is not enabled',
+ error_code: 'TOKEN_REUSE_DISABLED',
+ });
+ }
+
+ let openIdConfig;
+ try {
+ openIdConfig = getOpenIdConfig();
+ } catch {
+ return res.status(503).json({
+ error: 'OpenID is not configured',
+ error_code: 'OPENID_NOT_CONFIGURED',
+ });
+ }
+
+ const refreshParams = process.env.OPENID_SCOPE ? { scope: process.env.OPENID_SCOPE } : {};
+ let tokenset;
+ try {
+ tokenset = await openIdClient.refreshTokenGrant(openIdConfig, refreshToken, refreshParams);
+ } catch (err) {
+ logger.warn('[admin/oauth/refresh] IdP refresh grant failed', {
+ code: err?.code,
+ name: err?.name,
+ });
+ return res.status(401).json({
+ error: 'Refresh failed',
+ error_code: 'REFRESH_FAILED',
+ });
+ }
+
+ const sessionExpiry = Number(process.env.SESSION_EXPIRY) || DEFAULT_SESSION_EXPIRY;
+ const expectedIssuer = openIdConfig.serverMetadata?.()?.issuer;
+
+ try {
+ const result = await applyAdminRefresh(
+ tokenset,
+ {
+ findUsers,
+ getUserById,
+ canAccessAdmin: async (user) => {
+ try {
+ return await hasCapability(
+ {
+ id: user.id ?? user._id?.toString(),
+ role: user.role ?? '',
+ tenantId: user.tenantId,
+ },
+ SystemCapabilities.ACCESS_ADMIN,
+ );
+ } catch (err) {
+ logger.warn(
+ `[admin/oauth/refresh] capability check failed, denying: ${err?.message}`,
+ );
+ return false;
+ }
+ },
+ mintToken: async (user) => ({
+ token: await generateToken(user, sessionExpiry),
+ expiresAt: Date.now() + sessionExpiry,
+ }),
+ },
+ {
+ userId: typeof userId === 'string' && userId.length > 0 ? userId : undefined,
+ previousRefreshToken: refreshToken,
+ expectedIssuer,
+ tenantId: getTenantId(),
+ },
+ );
+ return res.json(result);
+ } catch (err) {
+ if (err instanceof AdminRefreshError) {
+ return res.status(err.status).json({ error: err.message, error_code: err.code });
+ }
+ throw err;
+ }
+ } catch (error) {
+ logger.error('[admin/oauth/refresh] Error:', error);
+ res.status(500).json({
+ error: 'Internal server error',
+ error_code: 'INTERNAL_ERROR',
+ });
+ }
+ },
+);
+
module.exports = router;
diff --git a/packages/api/src/auth/exchange.ts b/packages/api/src/auth/exchange.ts
index 931c251d55..650b006e38 100644
--- a/packages/api/src/auth/exchange.ts
+++ b/packages/api/src/auth/exchange.ts
@@ -30,7 +30,10 @@ export interface AdminExchangeUser {
}
/**
- * Data stored in cache for admin OAuth exchange
+ * Data stored in cache for admin OAuth exchange.
+ *
+ * `expiresAt` is the absolute expiry of `token` (ms epoch). Used by admin
+ * panel clients to drive proactive refresh before the bearer expires.
*/
export interface AdminExchangeData {
userId: string;
@@ -39,6 +42,7 @@ export interface AdminExchangeData {
refreshToken?: string;
origin?: string;
codeChallenge?: string;
+ expiresAt?: number;
}
/**
@@ -48,6 +52,7 @@ export interface AdminExchangeResponse {
token: string;
refreshToken?: string;
user: AdminExchangeUser;
+ expiresAt?: number;
}
/**
@@ -94,6 +99,7 @@ export function verifyCodeChallenge(verifier: string, challenge: string): boolea
* @param refreshToken - Optional refresh token for OpenID users
* @param origin - The admin panel origin (scheme://host:port) for origin binding
* @param codeChallenge - PKCE code_challenge (hex-encoded SHA-256 of code_verifier)
+ * @param expiresAt - Optional absolute expiry of `token` (ms epoch); admin panel uses for proactive refresh
* @returns The generated exchange code
*/
export async function generateAdminExchangeCode(
@@ -103,6 +109,7 @@ export async function generateAdminExchangeCode(
refreshToken?: string,
origin?: string,
codeChallenge?: string,
+ expiresAt?: number,
): Promise<string> {
const exchangeCode = crypto.randomBytes(32).toString('hex');
@@ -113,6 +120,7 @@ export async function generateAdminExchangeCode(
refreshToken,
origin,
codeChallenge,
+ expiresAt,
};
await cache.set(exchangeCode, data);
@@ -165,6 +173,7 @@ export async function exchangeAdminCode(
token: data.token,
refreshToken: data.refreshToken,
user: data.user,
+ expiresAt: data.expiresAt,
};
}
diff --git a/packages/api/src/auth/index.ts b/packages/api/src/auth/index.ts
index 5dd0bb01e0..d3c8a02896 100644
--- a/packages/api/src/auth/index.ts
+++ b/packages/api/src/auth/index.ts
@@ -1,6 +1,7 @@
export * from './domain';
export * from './openid';
export * from './exchange';
+export * from './refresh';
export * from './agent';
export * from './password';
export * from './invite';
diff --git a/packages/api/src/auth/openid.ts b/packages/api/src/auth/openid.ts
index e647e09f17..89432e6dd7 100644
--- a/packages/api/src/auth/openid.ts
+++ b/packages/api/src/auth/openid.ts
@@ -56,7 +56,7 @@ function isLegacyOpenIdIssuer(openidIssuer: string | undefined): boolean {
return openidIssuer != null && loginIssuer != null && openidIssuer === loginIssuer;
}
-function getIssuerBoundConditions(
+export function getIssuerBoundConditions(
field: OpenIdLookupField,
value: string | undefined,
openidIssuer: string | undefined,
@@ -76,7 +76,7 @@ function getIssuerBoundConditions(
return conditions;
}
-function isUserIssuerAllowed(user: IUser, openidIssuer: string | undefined): boolean {
+export function isUserIssuerAllowed(user: IUser, openidIssuer: string | undefined): boolean {
if (!openidIssuer) return true;
const userIssuer = normalizeOpenIdIssuer(user.openidIssuer);
diff --git a/packages/api/src/auth/refresh.spec.ts b/packages/api/src/auth/refresh.spec.ts
new file mode 100644
index 0000000000..97cea77ee4
--- /dev/null
+++ b/packages/api/src/auth/refresh.spec.ts
@@ -0,0 +1,542 @@
+import { Types } from 'mongoose';
+import { logger } from '@librechat/data-schemas';
+
+import type { IUser } from '@librechat/data-schemas';
+import type { AdminRefreshDeps, RefreshTokenset } from './refresh';
+
+import { applyAdminRefresh, AdminRefreshError } from './refresh';
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: {
+ debug: jest.fn(),
+ info: jest.fn(),
+ warn: jest.fn(),
+ },
+}));
+
+const SUB = 'idp-sub-12345';
+
+function makeUser(overrides: Partial<IUser> = {}): IUser {
+ const _id = overrides._id ?? new Types.ObjectId();
+ return {
+ _id,
+ email: '[email protected]',
+ name: 'Admin User',
+ username: 'admin',
+ role: 'ADMIN',
+ provider: 'openid',
+ openidId: SUB,
+ ...overrides,
+ } as unknown as IUser;
+}
+
+function makeTokenset(overrides: Partial<RefreshTokenset> = {}): RefreshTokenset {
+ return {
+ access_token: 'new-access',
+ refresh_token: 'new-refresh',
+ claims: () => ({ sub: SUB }),
+ ...overrides,
+ };
+}
+
+function makeDeps(user: IUser | undefined, overrides: Partial<AdminRefreshDeps> = {}) {
+ const findUsers = jest.fn().mockResolvedValue(user ? [user] : []);
+ const getUserById = jest.fn().mockResolvedValue(user ?? null);
+ const mintToken = jest.fn().mockResolvedValue({ token: 'minted-jwt', expiresAt: 1234567890 });
+ const onRefreshSuccess = jest.fn().mockResolvedValue(undefined);
+ return {
+ findUsers,
+ getUserById,
+ mintToken,
+ onRefreshSuccess,
+ ...overrides,
+ };
+}
+
+describe('applyAdminRefresh', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ describe('happy path', () => {
+ it('returns a fully-populated AdminExchangeResponse', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+ const tokenset = makeTokenset();
+
+ const result = await applyAdminRefresh(tokenset, deps);
+
+ expect(result).toEqual({
+ token: 'minted-jwt',
+ refreshToken: 'new-refresh',
+ user: expect.objectContaining({
+ email: '[email protected]',
+ openidId: SUB,
+ }),
+ expiresAt: 1234567890,
+ });
+ expect(deps.mintToken).toHaveBeenCalledWith(user, tokenset);
+ expect(deps.onRefreshSuccess).toHaveBeenCalledWith(user, tokenset);
+ });
+
+ it('uses findUsers when no userId is supplied', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps);
+
+ expect(deps.findUsers).toHaveBeenCalledWith(
+ { openidId: SUB },
+ '-password -__v -totpSecret -backupCodes',
+ { sort: { updatedAt: -1 }, limit: 1 },
+ );
+ expect(deps.getUserById).not.toHaveBeenCalled();
+ });
+
+ it('skips onRefreshSuccess when not provided', async () => {
+ const user = makeUser();
+ const { onRefreshSuccess: _omit, ...rest } = makeDeps(user);
+ const deps: AdminRefreshDeps = rest;
+
+ const result = await applyAdminRefresh(makeTokenset(), deps);
+ expect(result.token).toBe('minted-jwt');
+ expect(result.user.email).toBe('[email protected]');
+ });
+ });
+
+ describe('userId disambiguation', () => {
+ it('returns the direct user when userId resolves and openidId matches', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id });
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps, { userId: id.toString() });
+
+ expect(deps.getUserById).toHaveBeenCalledWith(
+ id.toString(),
+ '-password -__v -totpSecret -backupCodes',
+ );
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ });
+
+ it('falls through to findUsers when userId is not a valid ObjectId', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps, { userId: 'not-a-valid-id' });
+
+ expect(deps.getUserById).not.toHaveBeenCalled();
+ expect(deps.findUsers).toHaveBeenCalled();
+ });
+
+ it('falls through to findUsers when userId resolves to null', async () => {
+ const user = makeUser();
+ const id = new Types.ObjectId().toString();
+ const deps = makeDeps(user, { getUserById: jest.fn().mockResolvedValue(null) });
+
+ await applyAdminRefresh(makeTokenset(), deps, { userId: id });
+
+ expect(deps.getUserById).toHaveBeenCalledWith(id, '-password -__v -totpSecret -backupCodes');
+ expect(deps.findUsers).toHaveBeenCalledWith(
+ { openidId: SUB },
+ '-password -__v -totpSecret -backupCodes',
+ { sort: { updatedAt: -1 }, limit: 1 },
+ );
+ });
+
+ it('throws USER_ID_MISMATCH when the resolved user has a different openidId', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id, openidId: 'different-sub' });
+ const deps = makeDeps(user, {
+ getUserById: jest.fn().mockResolvedValue(user),
+ findUsers: jest.fn(),
+ });
+
+ await expect(
+ applyAdminRefresh(makeTokenset(), deps, { userId: id.toString() }),
+ ).rejects.toMatchObject({
+ name: 'AdminRefreshError',
+ code: 'USER_ID_MISMATCH',
+ status: 401,
+ });
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('error branches', () => {
+ it('throws IDP_INCOMPLETE when access_token is missing', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({ access_token: undefined });
+
+ await expect(applyAdminRefresh(tokenset, deps)).rejects.toMatchObject({
+ code: 'IDP_INCOMPLETE',
+ status: 502,
+ });
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ });
+
+ it('throws CLAIMS_INCOMPLETE when claims() throws', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({
+ claims: () => {
+ throw new Error('id_token missing');
+ },
+ });
+
+ await expect(applyAdminRefresh(tokenset, deps)).rejects.toMatchObject({
+ code: 'CLAIMS_INCOMPLETE',
+ status: 502,
+ });
+ });
+
+ it('throws CLAIMS_INCOMPLETE when sub is missing', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({ claims: () => ({}) });
+
+ await expect(applyAdminRefresh(tokenset, deps)).rejects.toMatchObject({
+ code: 'CLAIMS_INCOMPLETE',
+ status: 502,
+ });
+ });
+
+ it('throws USER_NOT_FOUND when no user matches the refreshed identity', async () => {
+ const deps = makeDeps(undefined);
+
+ await expect(applyAdminRefresh(makeTokenset(), deps)).rejects.toMatchObject({
+ code: 'USER_NOT_FOUND',
+ status: 401,
+ });
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ });
+
+ it('propagates errors thrown from mintToken', async () => {
+ const deps = makeDeps(makeUser(), {
+ mintToken: jest.fn().mockRejectedValue(new Error('signing failure')),
+ });
+
+ await expect(applyAdminRefresh(makeTokenset(), deps)).rejects.toThrow('signing failure');
+ });
+
+ it('propagates errors thrown from onRefreshSuccess', async () => {
+ const deps = makeDeps(makeUser(), {
+ onRefreshSuccess: jest.fn().mockRejectedValue(new Error('cache write failed')),
+ });
+
+ await expect(applyAdminRefresh(makeTokenset(), deps)).rejects.toThrow('cache write failed');
+ });
+ });
+
+ describe('issuer-bound user lookup', () => {
+ it('binds findUsers to (openidId, openidIssuer) when expectedIssuer is provided', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://issuer.example.com' }),
+ });
+
+ await applyAdminRefresh(tokenset, deps, {
+ expectedIssuer: 'https://issuer.example.com',
+ });
+
+ const [filter] = (deps.findUsers as jest.Mock).mock.calls[0];
+ expect(filter).toMatchObject({
+ $or: expect.arrayContaining([
+ { openidId: SUB, openidIssuer: 'https://issuer.example.com' },
+ ]),
+ });
+ });
+
+ it('falls back to openidId-only lookup when expectedIssuer is not provided', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps);
+
+ expect(deps.findUsers).toHaveBeenCalledWith(
+ { openidId: SUB },
+ '-password -__v -totpSecret -backupCodes',
+ { sort: { updatedAt: -1 }, limit: 1 },
+ );
+ });
+
+ it('throws USER_ID_MISMATCH when direct user_id resolves but issuer differs', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id, openidIssuer: 'https://other-issuer.example.com' });
+ const deps = makeDeps(user, {
+ getUserById: jest.fn().mockResolvedValue(user),
+ findUsers: jest.fn(),
+ });
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://issuer.example.com' }),
+ });
+
+ await expect(
+ applyAdminRefresh(tokenset, deps, {
+ userId: id.toString(),
+ expectedIssuer: 'https://issuer.example.com',
+ }),
+ ).rejects.toMatchObject({ code: 'USER_ID_MISMATCH', status: 401 });
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ });
+
+ it('accepts direct user_id when stored openidIssuer matches the expected issuer', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id, openidIssuer: 'https://issuer.example.com' });
+ const deps = makeDeps(user, { getUserById: jest.fn().mockResolvedValue(user) });
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://issuer.example.com' }),
+ });
+
+ await expect(
+ applyAdminRefresh(tokenset, deps, {
+ userId: id.toString(),
+ expectedIssuer: 'https://issuer.example.com',
+ }),
+ ).resolves.toBeDefined();
+ });
+ });
+
+ describe('issuer guard', () => {
+ it('passes when expected and actual issuers match', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://issuer.example.com' }),
+ });
+
+ await expect(
+ applyAdminRefresh(tokenset, deps, { expectedIssuer: 'https://issuer.example.com' }),
+ ).resolves.toBeDefined();
+ });
+
+ it('passes when expected and actual issuers match modulo trailing slash', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://issuer.example.com/' }),
+ });
+
+ await expect(
+ applyAdminRefresh(tokenset, deps, { expectedIssuer: 'https://issuer.example.com' }),
+ ).resolves.toBeDefined();
+ });
+
+ it('throws ISSUER_MISMATCH when issuers differ', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://attacker.example.com' }),
+ });
+
+ await expect(
+ applyAdminRefresh(tokenset, deps, { expectedIssuer: 'https://issuer.example.com' }),
+ ).rejects.toMatchObject({ code: 'ISSUER_MISMATCH', status: 401 });
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ });
+
+ it('skips the check when expectedIssuer is not provided', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({
+ claims: () => ({ sub: SUB, iss: 'https://attacker.example.com' }),
+ });
+
+ await expect(applyAdminRefresh(tokenset, deps)).resolves.toBeDefined();
+ });
+
+ it('skips the check when the tokenset has no iss claim', async () => {
+ const deps = makeDeps(makeUser());
+
+ await expect(
+ applyAdminRefresh(makeTokenset(), deps, {
+ expectedIssuer: 'https://issuer.example.com',
+ }),
+ ).resolves.toBeDefined();
+ });
+ });
+
+ describe('refresh-token preservation', () => {
+ it('preserves the inbound refresh token when the IdP does not rotate', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({ refresh_token: undefined });
+
+ const result = await applyAdminRefresh(tokenset, deps, {
+ previousRefreshToken: 'inbound-refresh',
+ });
+
+ expect(result.refreshToken).toBe('inbound-refresh');
+ });
+
+ it('prefers the rotated refresh token over the previousRefreshToken fallback', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({ refresh_token: 'rotated-refresh' });
+
+ const result = await applyAdminRefresh(tokenset, deps, {
+ previousRefreshToken: 'inbound-refresh',
+ });
+
+ expect(result.refreshToken).toBe('rotated-refresh');
+ });
+
+ it('returns undefined refreshToken when neither rotation nor fallback is available', async () => {
+ const deps = makeDeps(makeUser());
+ const tokenset = makeTokenset({ refresh_token: undefined });
+
+ const result = await applyAdminRefresh(tokenset, deps);
+
+ expect(result.refreshToken).toBeUndefined();
+ });
+ });
+
+ describe('tenant scoping', () => {
+ it('constrains the fallback findUsers filter to options.tenantId', async () => {
+ const user = makeUser({ tenantId: 'tenant-a' } as Partial<IUser>);
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps, { tenantId: 'tenant-a' });
+
+ const [filter] = (deps.findUsers as jest.Mock).mock.calls[0];
+ expect(filter).toMatchObject({ openidId: SUB, tenantId: 'tenant-a' });
+ });
+
+ it('returns the tenant-A user when two users share (sub, iss) across tenants', async () => {
+ const userA = makeUser({ tenantId: 'tenant-a', email: '[email protected]' } as Partial<IUser>);
+ const userB = makeUser({ tenantId: 'tenant-b', email: '[email protected]' } as Partial<IUser>);
+
+ const findUsers = jest.fn().mockImplementation(async (filter: { tenantId?: string }) => {
+ if (filter.tenantId === 'tenant-a') return [userA];
+ if (filter.tenantId === 'tenant-b') return [userB];
+ return [userA, userB];
+ });
+ const deps = makeDeps(userA, { findUsers });
+
+ const result = await applyAdminRefresh(makeTokenset(), deps, { tenantId: 'tenant-a' });
+
+ expect(result.user.email).toBe('[email protected]');
+ expect(findUsers).toHaveBeenCalledWith(
+ { openidId: SUB, tenantId: 'tenant-a' },
+ '-password -__v -totpSecret -backupCodes',
+ { sort: { updatedAt: -1 }, limit: 1 },
+ );
+ });
+
+ it('throws TENANT_MISMATCH when direct user_id resolves to a different tenant', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id, tenantId: 'tenant-b' } as Partial<IUser>);
+ const deps = makeDeps(user, {
+ getUserById: jest.fn().mockResolvedValue(user),
+ findUsers: jest.fn(),
+ });
+
+ await expect(
+ applyAdminRefresh(makeTokenset(), deps, {
+ userId: id.toString(),
+ tenantId: 'tenant-a',
+ }),
+ ).rejects.toMatchObject({
+ name: 'AdminRefreshError',
+ code: 'TENANT_MISMATCH',
+ status: 401,
+ });
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ });
+
+ it('accepts direct user_id when stored tenantId matches options.tenantId', async () => {
+ const id = new Types.ObjectId();
+ const user = makeUser({ _id: id, tenantId: 'tenant-a' } as Partial<IUser>);
+ const deps = makeDeps(user, {
+ getUserById: jest.fn().mockResolvedValue(user),
+ findUsers: jest.fn(),
+ });
+
+ const result = await applyAdminRefresh(makeTokenset(), deps, {
+ userId: id.toString(),
+ tenantId: 'tenant-a',
+ });
+
+ expect(result.token).toBe('minted-jwt');
+ expect(deps.findUsers).not.toHaveBeenCalled();
+ });
+
+ it('falls back to openidId-only filter when options.tenantId is omitted', async () => {
+ const user = makeUser();
+ const deps = makeDeps(user);
+
+ await applyAdminRefresh(makeTokenset(), deps);
+
+ const [filter] = (deps.findUsers as jest.Mock).mock.calls[0];
+ expect(filter).toEqual({ openidId: SUB });
+ expect(filter).not.toHaveProperty('tenantId');
+ });
+ });
+
+ describe('admin-access guard', () => {
+ it('throws FORBIDDEN and does not mint when canAccessAdmin returns false', async () => {
+ const user = makeUser();
+ const canAccessAdmin = jest.fn().mockResolvedValue(false);
+ const deps = makeDeps(user, { canAccessAdmin });
+
+ await expect(applyAdminRefresh(makeTokenset(), deps)).rejects.toMatchObject({
+ name: 'AdminRefreshError',
+ code: 'FORBIDDEN',
+ status: 403,
+ });
+
+ expect(canAccessAdmin).toHaveBeenCalledWith(user);
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ expect(deps.onRefreshSuccess).not.toHaveBeenCalled();
+ });
+
+ it('mints when canAccessAdmin returns true', async () => {
+ const user = makeUser();
+ const canAccessAdmin = jest.fn().mockResolvedValue(true);
+ const deps = makeDeps(user, { canAccessAdmin });
+
+ const result = await applyAdminRefresh(makeTokenset(), deps);
+
+ expect(canAccessAdmin).toHaveBeenCalledWith(user);
+ expect(deps.mintToken).toHaveBeenCalledWith(user, expect.any(Object));
+ expect(result.token).toBe('minted-jwt');
+ });
+
+ it('skips the check when canAccessAdmin is not provided', async () => {
+ const user = makeUser();
+ const { canAccessAdmin: _omit, ...rest } = makeDeps(user);
+ const deps: AdminRefreshDeps = rest;
+
+ const result = await applyAdminRefresh(makeTokenset(), deps);
+ expect(result.token).toBe('minted-jwt');
+ });
+
+ it('propagates errors thrown by canAccessAdmin without minting', async () => {
+ const user = makeUser();
+ const boom = new Error('capability backend exploded');
+ const canAccessAdmin = jest.fn().mockRejectedValue(boom);
+ const deps = makeDeps(user, { canAccessAdmin });
+
+ await expect(applyAdminRefresh(makeTokenset(), deps)).rejects.toBe(boom);
+ expect(deps.mintToken).not.toHaveBeenCalled();
+ expect(deps.onRefreshSuccess).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('logging', () => {
+ it('logs the refreshed user email at debug', async () => {
+ const deps = makeDeps(makeUser());
+
+ await applyAdminRefresh(makeTokenset(), deps);
+
+ expect(logger.debug).toHaveBeenCalledWith(expect.stringContaining('[email protected]'));
+ });
+ });
+});
+
+describe('AdminRefreshError', () => {
+ it('captures code, status, and message', () => {
+ const err = new AdminRefreshError('SOME_CODE', 418, 'teapot');
+ expect(err.name).toBe('AdminRefreshError');
+ expect(err.code).toBe('SOME_CODE');
+ expect(err.status).toBe(418);
+ expect(err.message).toBe('teapot');
+ expect(err).toBeInstanceOf(Error);
+ });
+});
diff --git a/packages/api/src/auth/refresh.ts b/packages/api/src/auth/refresh.ts
new file mode 100644
index 0000000000..9185998100
--- /dev/null
+++ b/packages/api/src/auth/refresh.ts
@@ -0,0 +1,254 @@
+import { Types } from 'mongoose';
+import { logger } from '@librechat/data-schemas';
+
+import type { IUser } from '@librechat/data-schemas';
+import type { FilterQuery } from 'mongoose';
+import type { AdminExchangeResponse } from '~/auth/exchange';
+
+import {
+ isUserIssuerAllowed,
+ normalizeOpenIdIssuer,
+ getIssuerBoundConditions,
+} from '~/auth/openid';
+import { serializeUserForExchange } from '~/auth/exchange';
+
+const SAFE_USER_PROJECTION = '-password -__v -totpSecret -backupCodes';
+
+interface AdminRefreshClaims {
+ sub?: string;
+ iss?: string;
+}
+
+/**
+ * The minimal shape this module needs from an `openid-client` tokenset.
+ * Avoids a hard import dependency on `openid-client` types in this package.
+ */
+export interface RefreshTokenset {
+ access_token?: string;
+ refresh_token?: string;
+ claims: () => AdminRefreshClaims;
+}
+
+export interface MintedToken {
+ /** Bearer the admin panel will send on subsequent requests. */
+ token: string;
+ /** Absolute expiry of `token` (ms epoch). Drives the admin panel's proactive refresh. */
+ expiresAt: number;
+}
+
+export interface AdminRefreshDeps {
+ findUsers: (
+ filter: FilterQuery<IUser>,
+ projection: string,
+ options: { sort: Record<string, 1 | -1>; limit: number },
+ ) => Promise<IUser[]>;
+ getUserById: (id: string, projection: string) => Promise<IUser | null>;
+ /**
+ * Mints the bearer the admin panel will send on subsequent requests, and
+ * reports its absolute expiry. The minter is authoritative for the bearer's
+ * lifetime — the helper does not attempt to derive expiry from the IdP's
+ * `exp` claim. Default OSS callers pass `generateToken(user, sessionExpiry)`
+ * and `Date.now() + sessionExpiry`.
+ */
+ mintToken: (user: IUser, tokenset: RefreshTokenset) => Promise<MintedToken>;
+ /**
+ * Authorizes the resolved user against the same admin-access invariant
+ * the initial OAuth callback enforces. The IdP refresh token can outlive
+ * a capability/role change, so the bearer must not be reissued for a
+ * user who no longer holds `ACCESS_ADMIN`. Optional only for backward
+ * compatibility with existing callers; route handlers that mint admin
+ * bearers should always inject this.
+ */
+ canAccessAdmin?: (user: IUser) => Promise<boolean>;
+ /**
+ * Optional post-success hook for forks that need to do additional work
+ * with the refreshed tokenset and resolved user (e.g. update a server-side
+ * token cache or reconcile downstream session state). Errors thrown here
+ * propagate to the route handler.
+ */
+ onRefreshSuccess?: (user: IUser, tokenset: RefreshTokenset) => Promise<void>;
+}
+
+export interface AdminRefreshOptions {
+ /**
+ * Optional user `_id` from the previous admin-panel session. When provided,
+ * the resolved user must have a matching `openidId` — otherwise the refresh
+ * is rejected as a possible identity-swap attempt.
+ */
+ userId?: string;
+ /**
+ * The refresh token the admin panel sent in. Preserved as the response
+ * `refreshToken` when the IdP doesn't rotate (Auth0 with rotation off,
+ * Microsoft personal accounts in some flows). Without this fallback, the
+ * admin panel would receive `undefined` and lose its refresh capability.
+ */
+ previousRefreshToken?: string;
+ /**
+ * Issuer URL of the OpenID provider this server trusts. When provided
+ * alongside an `iss` claim on the refreshed tokenset, the helper rejects
+ * the refresh if the two don't match. Defends against tokensets emitted
+ * by an unexpected issuer, even though `IUser` lookup is still keyed by
+ * `openidId` alone.
+ */
+ expectedIssuer?: string;
+ /**
+ * Trusted tenant id resolved by the route layer (e.g. `getTenantId()` from
+ * the pre-auth tenant ALS scope). When provided, the helper:
+ * - constrains the fallback `findUsers` lookup with `tenantId`, and
+ * - asserts a direct `getUserById` result has a matching `tenantId`,
+ * so the same `(sub, iss)` existing in another tenant can never resolve
+ * here. Multi-tenant deployments MUST pass this. Single-tenant deployments
+ * may omit it.
+ */
+ tenantId?: string;
+}
+
+export class AdminRefreshError extends Error {
+ constructor(
+ public readonly code: string,
+ public readonly status: number,
+ message: string,
+ ) {
+ super(message);
+ this.name = 'AdminRefreshError';
+ }
+}
+
+async function resolveAdminUser(
+ deps: AdminRefreshDeps,
+ openidId: string,
+ normalizedIssuer: string | undefined,
+ options: AdminRefreshOptions,
+): Promise<IUser | undefined> {
+ const expectedTenantId = options.tenantId;
+
+ if (options.userId && Types.ObjectId.isValid(options.userId)) {
+ const direct = await deps.getUserById(options.userId as string, SAFE_USER_PROJECTION);
+ if (direct) {
+ if (direct.openidId !== openidId) {
+ throw new AdminRefreshError(
+ 'USER_ID_MISMATCH',
+ 401,
+ 'Provided user_id does not match the refreshed identity',
+ );
+ }
+ if (!isUserIssuerAllowed(direct, normalizedIssuer)) {
+ throw new AdminRefreshError(
+ 'USER_ID_MISMATCH',
+ 401,
+ 'Provided user_id matches sub but issuer differs from the refreshed identity',
+ );
+ }
+ if (expectedTenantId && direct.tenantId !== expectedTenantId) {
+ throw new AdminRefreshError(
+ 'TENANT_MISMATCH',
+ 401,
+ 'Provided user_id resolves outside the request tenant',
+ );
+ }
+ return direct;
+ }
+ logger.debug(
+ `[adminRefresh] user_id ${options.userId} not found; falling through to openidId lookup`,
+ );
+ }
+
+ const issuerBound = getIssuerBoundConditions('openidId', openidId, normalizedIssuer);
+ const baseFilter: FilterQuery<IUser> =
+ issuerBound.length > 0 ? { $or: issuerBound } : ({ openidId } as FilterQuery<IUser>);
+ const filter: FilterQuery<IUser> = expectedTenantId
+ ? ({ ...baseFilter, tenantId: expectedTenantId } as FilterQuery<IUser>)
+ : baseFilter;
+
+ const [user] = await deps.findUsers(filter, SAFE_USER_PROJECTION, {
+ sort: { updatedAt: -1 },
+ limit: 1,
+ });
+ return user;
+}
+
+function readClaims(tokenset: RefreshTokenset): AdminRefreshClaims {
+ try {
+ return tokenset.claims();
+ } catch (err) {
+ const error = err as { name?: string; message?: string };
+ logger.warn('[adminRefresh] tokenset.claims() threw', {
+ name: error?.name,
+ message: error?.message,
+ });
+ throw new AdminRefreshError(
+ 'CLAIMS_INCOMPLETE',
+ 502,
+ 'IdP returned a tokenset whose claims could not be read (no id_token?)',
+ );
+ }
+}
+
+/**
+ * Looks up the active admin user for a freshly-refreshed OpenID tokenset,
+ * mints the bearer the admin panel should send on subsequent requests, and
+ * returns the response shape used by `/api/admin/oauth/exchange`.
+ *
+ * The route handler is responsible for the IdP `refreshTokenGrant` call;
+ * this helper takes the resulting tokenset and turns it into an admin-panel
+ * exchange response.
+ */
+export async function applyAdminRefresh(
+ tokenset: RefreshTokenset,
+ deps: AdminRefreshDeps,
+ options: AdminRefreshOptions = {},
+): Promise<AdminExchangeResponse> {
+ if (!tokenset.access_token) {
+ throw new AdminRefreshError(
+ 'IDP_INCOMPLETE',
+ 502,
+ 'IdP returned an incomplete tokenset (missing access_token)',
+ );
+ }
+
+ const claims = readClaims(tokenset);
+ const openidId = claims.sub;
+ if (!openidId) {
+ throw new AdminRefreshError(
+ 'CLAIMS_INCOMPLETE',
+ 502,
+ 'IdP returned a tokenset missing the required `sub` claim',
+ );
+ }
+
+ const expected = normalizeOpenIdIssuer(options.expectedIssuer);
+ const actual = normalizeOpenIdIssuer(claims.iss);
+ if (expected && actual && expected !== actual) {
+ throw new AdminRefreshError(
+ 'ISSUER_MISMATCH',
+ 401,
+ 'Refreshed tokenset was issued by an unexpected issuer',
+ );
+ }
+
+ const user = await resolveAdminUser(deps, openidId, expected, options);
+ if (!user) {
+ throw new AdminRefreshError('USER_NOT_FOUND', 401, 'No user found for the refreshed identity');
+ }
+
+ if (deps.canAccessAdmin && !(await deps.canAccessAdmin(user))) {
+ throw new AdminRefreshError('FORBIDDEN', 403, 'User does not have admin access');
+ }
+
+ const minted = await deps.mintToken(user, tokenset);
+
+ if (deps.onRefreshSuccess) {
+ await deps.onRefreshSuccess(user, tokenset);
+ }
+
+ const responseUser = serializeUserForExchange(user);
+
+ logger.debug(`[adminRefresh] Refreshed tokens for user: ${responseUser.email}`);
+
+ return {
+ token: minted.token,
+ refreshToken: tokenset.refresh_token ?? options.previousRefreshToken,
+ user: responseUser,
+ expiresAt: minted.expiresAt,
+ };
+}