🔄 feat: Body-Based OpenID Refresh for Cross-Origin Admin Panels (#46)

* 🔄 feat: Body-Based OpenID Refresh for Cross-Origin Admin Panels

The cookie-based `/api/auth/refresh` controller can't be reached cross-origin
because the refresh-token cookie doesn't ship on a fetch from a different host.
Cross-origin admin panel sessions silently die at JWT expiry with no recovery.

This routes `openid` sessions through the new `POST /api/admin/oauth/refresh`
endpoint (danny-avila/LibreChat#13007) which accepts the refresh token in
the request body and returns the same shape as `/api/admin/oauth/exchange`:
`{ token, refreshToken, user, expiresAt }`. Non-openid sessions still use
the legacy cookie-based path.

The `expiresAt` field (ms epoch) is now threaded through `SessionData` and
`OAuthExchangeResponse` so the admin panel can drive proactive refresh
before the bearer expires.

`refreshAdminToken` takes a new `userId` argument that's forwarded as
`user_id` in the refresh request body for disambiguation when multiple
user docs share the same OpenID `sub`.

* feat: forward X-Tenant-Id and centralize bearer freshness in apiFetch

Two follow-ups for the BFF refresh path now that the LibreChat
backend scopes /api/admin/oauth/refresh by tenant.

apiFetch was sending the session bearer as-is. If a query landed
past JWT expiry it would fail before the 60s revalidation interval
kicked in. apiFetch now reads expiresAt, refreshes proactively when
the bearer is within 30s of expiry, persists any rotated refresh
token, and retries the original request exactly once on a 401.

The OpenID refresh request now forwards the deployment's X-Tenant-Id
header so the backend's preAuthTenantMiddleware can scope the user
lookup. Without this the backend would fall back to single-tenant
behavior and the multi-tenant duplicate (sub, iss) protection added
in danny-avila/LibreChat#13007 wouldn't activate.

Refresh logic moves to a shared src/server/utils/refresh.ts so the
verify path and apiFetch share one implementation. Concurrent
callers are deduped on the refresh token so two React Query
subscribers can't both consume a rotating token in the same BFF
process.

Adds 19 tests covering tenant header forwarded/omitted, dedupe,
proactive refresh inside/outside skew, rotation persistence, and
single-retry 401 behavior.

* fix: break refresh URL import cycle

* fix: include user, provider, and tenant in refresh dedupe key

Keying the in-flight refresh map on refreshToken alone meant two
concurrent calls that happen to share a token string but differ by
userId, tokenProvider, or tenant would coalesce, and the second
caller would receive the first caller's bearer and persist it into
the wrong session.

Build the dedupe key from tokenProvider, userId, the request's
X-Tenant-Id header, and the refresh token (joined by NUL). Adds
three regression tests covering each discriminator.

---------

Co-authored-by: Danny Avila <danny@librechat.ai>

Author: dustinhealy

src/server/auth.ts

@@ -6,8 +6,9 @@ import { SystemRoles } from 'librechat-data-provider';
 import { createServerFn } from '@tanstack/react-start';
 import { getRequestHeader } from '@tanstack/react-start/server';
 import type * as t from '@/types';
+import { getApiBaseUrl, getServerApiUrl } from './utils/url';
+import { refreshAdminTokenDeduped } from './utils/refresh';
 import { useAppSession, SESSION_CONFIG } from './session';
-import { getApiBaseUrl, getServerApiUrl } from './utils/api';
 
 /** Extract a named cookie value from `set-cookie` response headers. */
 function extractCookieValue(response: Response, name: string): string | undefined {
@@ -146,50 +147,12 @@ const clearSession = async (session: Awaited<ReturnType<typeof useAppSession>>)
     user: undefined,
     refreshToken: undefined,
     tokenProvider: undefined,
+    expiresAt: undefined,
     lastVerified: undefined,
     lastActivity: undefined,
   });
 };
 
-/**
- * Attempt to refresh the JWT using the stored refresh token.
- * Returns the new token and refreshToken on success, or undefined on failure.
- *
- * Note: concurrent callers sharing a rotating refresh token may race; the
- * current call pattern (single React Query with 60s interval) is sequential.
- */
-const refreshResponseSchema = z.object({ token: z.string() });
-
-async function refreshAdminToken(
-  refreshToken: string,
-  tokenProvider: t.SessionData['tokenProvider'],
-): Promise<{ token: string; refreshToken?: string } | undefined> {
-  try {
-    const cookieParts = [`refreshToken=${refreshToken}`];
-    if (tokenProvider === 'openid') {
-      cookieParts.push('token_provider=openid');
-    }
-
-    const response = await fetch(`${getServerApiUrl()}/api/auth/refresh`, {
-      method: 'POST',
-      headers: { Cookie: cookieParts.join('; ') },
-    });
-
-    if (!response.ok) return undefined;
-
-    const parsed = refreshResponseSchema.safeParse(await response.json());
-    if (!parsed.success) return undefined;
-
-    return {
-      token: parsed.data.token,
-      refreshToken: extractCookieValue(response, 'refreshToken'),
-    };
-  } catch (error) {
-    console.warn('[refreshAdminToken] Token refresh request failed:', error);
-    return undefined;
-  }
-}
-
 export const verifyAdminTokenFn = createServerFn({ method: 'GET' }).handler(async () => {
   try {
     const session = await useAppSession();
@@ -227,11 +190,12 @@ export const verifyAdminTokenFn = createServerFn({ method: 'GET' }).handler(asyn
           }
           if (response.status === 401) {
             if (refreshToken) {
-              const refreshed = await refreshAdminToken(refreshToken, tokenProvider);
+              const refreshed = await refreshAdminTokenDeduped(refreshToken, tokenProvider, user.id);
               if (refreshed) {
                 const refreshedSession = {
                   token: refreshed.token,
                   refreshToken: refreshed.refreshToken ?? refreshToken,
+                  expiresAt: refreshed.expiresAt,
                   lastVerified: now,
                   lastActivity: now,
                 };
@@ -422,6 +386,7 @@ export const oauthExchangeFn = createServerFn({ method: 'POST' })
         token: exchangeData.token,
         refreshToken: exchangeData.refreshToken ?? extractCookieValue(response, 'refreshToken'),
         tokenProvider: 'openid',
+        expiresAt: exchangeData.expiresAt,
         lastVerified: now,
         lastActivity: now,
         codeVerifier: undefined,

src/server/utils/api.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const ensureFreshBearer = vi.fn();
+const refreshOn401 = vi.fn();
+
+vi.mock('./refresh', () => ({
+  ensureFreshBearer: (...args: unknown[]) => ensureFreshBearer(...args),
+  refreshOn401: (...args: unknown[]) => refreshOn401(...args),
+}));
+
+import { apiFetch } from './api';
+
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  fetchMock.mockReset();
+  ensureFreshBearer.mockReset();
+  refreshOn401.mockReset();
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+function jsonResponse(status: number, body: unknown = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+describe('apiFetch', () => {
+  it('throws when no bearer is available', async () => {
+    ensureFreshBearer.mockResolvedValueOnce(undefined);
+    await expect(apiFetch('/api/admin/grants')).rejects.toThrow(/No admin session token/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('sends Authorization with the bearer returned by ensureFreshBearer', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-fresh');
+    fetchMock.mockResolvedValueOnce(jsonResponse(200));
+
+    await apiFetch('/api/admin/grants');
+
+    const [, init] = fetchMock.mock.calls[0];
+    const headers = (init as RequestInit).headers as Record<string, string>;
+    expect(headers.Authorization).toBe('Bearer jwt-fresh');
+    expect(refreshOn401).not.toHaveBeenCalled();
+  });
+
+  it('passes through the proactive-refresh skew window of 30s', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-fresh');
+    fetchMock.mockResolvedValueOnce(jsonResponse(200));
+    await apiFetch('/api/admin/grants');
+    expect(ensureFreshBearer).toHaveBeenCalledWith(30_000);
+  });
+
+  it('retries exactly once on 401, using the refreshed bearer', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-stale');
+    refreshOn401.mockResolvedValueOnce('jwt-fresh');
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(401, { error: 'expired' }))
+      .mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+
+    const response = await apiFetch('/api/admin/grants');
+
+    expect(response.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(refreshOn401).toHaveBeenCalledTimes(1);
+
+    const [, init1] = fetchMock.mock.calls[0];
+    const [, init2] = fetchMock.mock.calls[1];
+    expect((init1 as RequestInit).headers).toMatchObject({ Authorization: 'Bearer jwt-stale' });
+    expect((init2 as RequestInit).headers).toMatchObject({ Authorization: 'Bearer jwt-fresh' });
+  });
+
+  it('does not retry when the second response is also 401', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-stale');
+    refreshOn401.mockResolvedValueOnce('jwt-fresh');
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse(401))
+      .mockResolvedValueOnce(jsonResponse(401, { error: 'still bad' }));
+
+    const response = await apiFetch('/api/admin/grants');
+
+    expect(response.status).toBe(401);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(refreshOn401).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the original 401 when refreshOn401 fails', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-stale');
+    refreshOn401.mockResolvedValueOnce(undefined);
+    const expired = jsonResponse(401, { error: 'expired' });
+    fetchMock.mockResolvedValueOnce(expired);
+
+    const response = await apiFetch('/api/admin/grants');
+
+    expect(response.status).toBe(401);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call refreshOn401 on non-401 errors', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-fresh');
+    fetchMock.mockResolvedValueOnce(jsonResponse(500, { error: 'server' }));
+
+    const response = await apiFetch('/api/admin/grants');
+
+    expect(response.status).toBe(500);
+    expect(refreshOn401).not.toHaveBeenCalled();
+  });
+
+  it('lets caller-supplied headers be overridden by the Authorization header', async () => {
+    ensureFreshBearer.mockResolvedValueOnce('jwt-fresh');
+    fetchMock.mockResolvedValueOnce(jsonResponse(200));
+
+    await apiFetch('/api/admin/grants', {
+      method: 'POST',
+      headers: { Authorization: 'Bearer attacker', 'X-Custom': 'keep-me' },
+    });
+
+    const [, init] = fetchMock.mock.calls[0];
+    const headers = (init as RequestInit).headers as Record<string, string>;
+    expect(headers.Authorization).toBe('Bearer jwt-fresh');
+    expect(headers['X-Custom']).toBe('keep-me');
+  });
+});

src/server/utils/api.ts

@@ -1,45 +1,47 @@
-import { useAppSession } from '../session';
+import { ensureFreshBearer, refreshOn401 } from './refresh';
+import { getServerApiUrl } from './url';
 
-export function getApiBaseUrl(): string {
-  if (typeof process !== 'undefined' && process.env?.VITE_API_BASE_URL) {
-    return process.env.VITE_API_BASE_URL;
-  }
-  if (typeof import.meta !== 'undefined' && import.meta.env?.VITE_API_BASE_URL) {
-    return import.meta.env.VITE_API_BASE_URL;
-  }
-  return 'http://localhost:3080';
-}
-
-/** Server-to-server API URL. Falls back to getApiBaseUrl() if API_SERVER_URL is not set. */
-export function getServerApiUrl(): string {
-  if (typeof process !== 'undefined' && process.env?.API_SERVER_URL) {
-    return process.env.API_SERVER_URL;
-  }
-  return getApiBaseUrl();
-}
+/** Skew window: refresh proactively when the bearer is within this of expiry. */
+const PROACTIVE_REFRESH_SKEW_MS = 30_000;
 
 /**
  * Make an authenticated request to the LibreChat API.
- * Reads the JWT token from the admin session and sets the Authorization header.
  *
- * @throws {Error} If no session token is available
+ * Centralises bearer freshness: refreshes proactively when `expiresAt` is
+ * within {@link PROACTIVE_REFRESH_SKEW_MS} of now, persists any rotated
+ * refresh token to the session, and retries the original request once on a
+ * 401 (so a token that expired between the freshness check and the request
+ * landing still recovers without bubbling the failure up to the caller).
+ *
+ * @throws {Error} If no session bearer is available even after a refresh
+ *   attempt.
  */
 export async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
-  const session = await useAppSession();
-  const token = session.data.token;
-  if (!token) {
+  const initialToken = await ensureFreshBearer(PROACTIVE_REFRESH_SKEW_MS);
+  if (!initialToken) {
     throw new Error('No admin session token available');
   }
 
   const url = `${getServerApiUrl()}${path}`;
-  return fetch(url, {
+  const buildInit = (token: string): RequestInit => ({
     ...init,
     headers: {
       'Content-Type': 'application/json',
-      Authorization: `Bearer ${token}`,
       ...init?.headers,
+      Authorization: `Bearer ${token}`,
     },
   });
+
+  const response = await fetch(url, buildInit(initialToken));
+  if (response.status !== 401) {
+    return response;
+  }
+
+  const refreshedToken = await refreshOn401();
+  if (!refreshedToken) {
+    return response;
+  }
+  return fetch(url, buildInit(refreshedToken));
 }
 
 /**