From 91ae2e57e2ec5b5e277266a0cc705dfa24f891b2 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Tue, 9 Jun 2026 21:53:14 -0400
Subject: [PATCH 01/19] Added Entra OIDC

---
 app/(auth)/login/page.tsx              |  25 ++++-
 app/api/auth/entra/callback/route.ts   |  59 ++++++++++
 app/api/auth/entra/login/route.ts      |  42 +++++++
 app/api/auth/entra/logout/route.ts     |  45 ++++++++
 app/api/auth/entra/refresh/route.ts    |  64 +++++++++++
 app/api/auth/session/route.ts          |  31 ++++++
 app/api/tiled/[...path]/route.ts       |  21 +++-
 app/api/ws/[...path]/route.ts          |  49 ++++++--
 components/layout/header.tsx           |   5 +-
 components/providers/auth-provider.tsx | 123 +++++++++++++++-----
 lib/auth/config.ts                     | 114 +++++++++++++++++++
 lib/auth/cookies.ts                    |  92 +++++++++++++++
 lib/auth/entra.ts                      | 148 +++++++++++++++++++++++++
 lib/auth/jwt.ts                        |  86 ++++++++++++++
 lib/auth/obo.ts                        | 112 +++++++++++++++++++
 lib/auth/oidc-flow.ts                  | 144 ++++++++++++++++++++++++
 lib/auth/token-store.ts                |  81 ++++++++++++++
 lib/tiled/auth.ts                      |  25 ++++-
 lib/tiled/client.ts                    |  52 +++++++--
 lib/tiled/types.ts                     |  10 ++
 lib/tiled/websocket.ts                 |   3 +-
 package-lock.json                      |   8 +-
 package.json                           |   1 +
 23 files changed, 1286 insertions(+), 54 deletions(-)
 create mode 100644 app/api/auth/entra/callback/route.ts
 create mode 100644 app/api/auth/entra/login/route.ts
 create mode 100644 app/api/auth/entra/logout/route.ts
 create mode 100644 app/api/auth/entra/refresh/route.ts
 create mode 100644 app/api/auth/session/route.ts
 create mode 100644 lib/auth/config.ts
 create mode 100644 lib/auth/cookies.ts
 create mode 100644 lib/auth/entra.ts
 create mode 100644 lib/auth/jwt.ts
 create mode 100644 lib/auth/obo.ts
 create mode 100644 lib/auth/oidc-flow.ts
 create mode 100644 lib/auth/token-store.ts

diff --git a/app/(auth)/login/page.tsx b/app/(auth)/login/page.tsx
index 6e04b58..729536d 100644
--- a/app/(auth)/login/page.tsx
+++ b/app/(auth)/login/page.tsx
@@ -12,7 +12,7 @@ type AuthMode = 'password' | 'apikey';
 
 export default function LoginPage() {
   const router = useRouter();
-  const { login, loginWithApiKey, isLoading } = useAuth();
+  const { login, loginWithApiKey, loginWithEntra, isLoading } = useAuth();
   const [mode, setMode] = useState<AuthMode>('password');
   const [username, setUsername] = useState('');
   const [password, setPassword] = useState('');
@@ -79,6 +79,29 @@ export default function LoginPage() {
             </p>
           </div>
 
+          {/* Microsoft SSO */}
+          <Button
+            type="button"
+            onClick={() => loginWithEntra()}
+            disabled={isLoading}
+            className="w-full h-10 bg-[#2f2f2f] text-white hover:bg-[#1a1a1a] font-medium rounded-lg gap-2.5 mb-4"
+          >
+            <svg className="w-4 h-4" viewBox="0 0 21 21" fill="none">
+              <rect x="1" y="1" width="9" height="9" fill="#F25022" />
+              <rect x="11" y="1" width="9" height="9" fill="#7FBA00" />
+              <rect x="1" y="11" width="9" height="9" fill="#00A4EF" />
+              <rect x="11" y="11" width="9" height="9" fill="#FFB900" />
+            </svg>
+            Sign in with Microsoft
+          </Button>
+
+          {/* Divider */}
+          <div className="flex items-center gap-3 mb-4">
+            <div className="flex-1 h-px bg-border-subtle" />
+            <span className="text-[11px] text-text-tertiary uppercase tracking-wider">or</span>
+            <div className="flex-1 h-px bg-border-subtle" />
+          </div>
+
           {/* Mode Toggle */}
           <div className="flex p-1 mb-6 rounded-lg bg-surface-ground border border-border-subtle">
             <button
diff --git a/app/api/auth/entra/callback/route.ts b/app/api/auth/entra/callback/route.ts
new file mode 100644
index 0000000..fdc4cfe
--- /dev/null
+++ b/app/api/auth/entra/callback/route.ts
@@ -0,0 +1,59 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { assertAuthConfig, buildCallbackUrl } from '@/lib/auth/config';
+import { validateAndConsumeOidcFlow, clearOidcFlowCookie } from '@/lib/auth/oidc-flow';
+import { exchangeCodeForUser } from '@/lib/auth/entra';
+import { setTokens } from '@/lib/auth/token-store';
+import { issueSessionTokens } from '@/lib/auth/jwt';
+import { setSessionCookies } from '@/lib/auth/cookies';
+
+export async function GET(request: NextRequest) {
+  assertAuthConfig();
+
+  const code = request.nextUrl.searchParams.get('code');
+  const stateParam = request.nextUrl.searchParams.get('state');
+  const error = request.nextUrl.searchParams.get('error');
+
+  // Handle Entra error response
+  if (error) {
+    console.error('[Entra Callback] Error from Entra:', error);
+    return NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
+  }
+
+  if (!code || !stateParam) {
+    return NextResponse.redirect(new URL('/login?error=missing_code', request.url));
+  }
+
+  try {
+    // Validate OIDC flow state (checks cookie, state match)
+    const { nonce, codeVerifier } = await validateAndConsumeOidcFlow(request, stateParam);
+
+    // Build the same redirect_uri used in the login request
+    const redirectUri = buildCallbackUrl(request);
+
+    // Exchange code for tokens and verify id_token
+    const { username, displayName, accessToken, refreshToken } =
+      await exchangeCodeForUser(code, redirectUri, codeVerifier, nonce);
+
+    // Store Entra tokens in-memory
+    setTokens(username, {
+      entraAccessToken: accessToken,
+      entraRefreshToken: refreshToken,
+      storedAt: Date.now(),
+    });
+
+    // Issue app-level session tokens
+    const sessionTokens = await issueSessionTokens(username, displayName);
+
+    // Redirect to app root with session cookies set
+    const response = NextResponse.redirect(new URL('/', request.url));
+    setSessionCookies(response, sessionTokens.accessToken, sessionTokens.refreshToken);
+    clearOidcFlowCookie(response);
+
+    return response;
+  } catch (err) {
+    console.error('[Entra Callback] Auth failed:', err instanceof Error ? err.message : err);
+    const response = NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
+    clearOidcFlowCookie(response);
+    return response;
+  }
+}
diff --git a/app/api/auth/entra/login/route.ts b/app/api/auth/entra/login/route.ts
new file mode 100644
index 0000000..c96d9e4
--- /dev/null
+++ b/app/api/auth/entra/login/route.ts
@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  AUTH_ENDPOINT,
+  CLIENT_ID,
+  buildCallbackUrl,
+  entraUserScope,
+  assertAuthConfig,
+} from '@/lib/auth/config';
+import {
+  createOidcFlowState,
+  buildPkceChallenge,
+  setOidcFlowCookie,
+} from '@/lib/auth/oidc-flow';
+
+export async function GET(request: NextRequest) {
+  assertAuthConfig();
+
+  // Generate OIDC flow state (state, nonce, PKCE code_verifier)
+  const flowState = createOidcFlowState();
+  const codeChallenge = await buildPkceChallenge(flowState.codeVerifier);
+  const redirectUri = buildCallbackUrl(request);
+
+  // Build Entra authorize URL
+  const params = new URLSearchParams({
+    client_id: CLIENT_ID,
+    response_type: 'code',
+    redirect_uri: redirectUri,
+    scope: entraUserScope(),
+    state: flowState.state,
+    nonce: flowState.nonce,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+  });
+
+  const authorizeUrl = `${AUTH_ENDPOINT}?${params.toString()}`;
+
+  // Create redirect response and set OIDC flow cookie
+  const response = NextResponse.redirect(authorizeUrl);
+  await setOidcFlowCookie(response, flowState);
+
+  return response;
+}
diff --git a/app/api/auth/entra/logout/route.ts b/app/api/auth/entra/logout/route.ts
new file mode 100644
index 0000000..c64e872
--- /dev/null
+++ b/app/api/auth/entra/logout/route.ts
@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ACCESS_COOKIE, REFRESH_COOKIE } from '@/lib/auth/config';
+import { decodeSessionToken } from '@/lib/auth/jwt';
+import { clearSessionCookies } from '@/lib/auth/cookies';
+import { deleteTokens } from '@/lib/auth/token-store';
+import { clearOboCache } from '@/lib/auth/obo';
+
+export async function POST(request: NextRequest) {
+  let username: string | null = null;
+
+  // Try to get username from access cookie first, then refresh cookie
+  const accessCookie = request.cookies.get(ACCESS_COOKIE)?.value;
+  if (accessCookie) {
+    try {
+      const payload = await decodeSessionToken(accessCookie, 'access');
+      username = payload.sub;
+    } catch {
+      // Ignore -- try refresh cookie
+    }
+  }
+
+  if (!username) {
+    const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
+    if (refreshCookie) {
+      try {
+        const payload = await decodeSessionToken(refreshCookie, 'refresh');
+        username = payload.sub;
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  // Clean up server-side state
+  if (username) {
+    deleteTokens(username);
+    clearOboCache(username);
+  }
+
+  // Clear cookies
+  const response = NextResponse.json({ status: 'ok' });
+  clearSessionCookies(response);
+
+  return response;
+}
diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
new file mode 100644
index 0000000..fbff54d
--- /dev/null
+++ b/app/api/auth/entra/refresh/route.ts
@@ -0,0 +1,64 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { REFRESH_COOKIE } from '@/lib/auth/config';
+import { decodeSessionToken, issueSessionTokens } from '@/lib/auth/jwt';
+import { setSessionCookies, clearSessionCookies } from '@/lib/auth/cookies';
+import { getTokens, getFreshEntraToken, setTokens } from '@/lib/auth/token-store';
+import { refreshEntraAccessToken } from '@/lib/auth/entra';
+
+export async function POST(request: NextRequest) {
+  const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
+
+  if (!refreshCookie) {
+    return NextResponse.json({ error: 'missing refresh token' }, { status: 401 });
+  }
+
+  let username: string;
+  let displayName: string;
+
+  try {
+    const payload = await decodeSessionToken(refreshCookie, 'refresh');
+    username = payload.sub;
+    displayName = payload.name || username;
+  } catch {
+    const response = NextResponse.json({ error: 'invalid refresh token' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
+  }
+
+  // Try to refresh the underlying Entra token
+  const entry = getTokens(username);
+  if (!entry) {
+    const response = NextResponse.json({ error: 'missing entra credentials' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
+  }
+
+  if (entry.entraRefreshToken) {
+    try {
+      const refreshed = await refreshEntraAccessToken(entry.entraRefreshToken);
+      setTokens(username, {
+        entraAccessToken: refreshed.accessToken,
+        entraRefreshToken: refreshed.refreshToken,
+        storedAt: Date.now(),
+      });
+    } catch (err) {
+      console.error('[Entra Refresh] Failed:', err instanceof Error ? err.message : err);
+      // Clear stored tokens on refresh failure
+      const { deleteTokens } = await import('@/lib/auth/token-store');
+      deleteTokens(username);
+      const response = NextResponse.json(
+        { error: 'entra refresh failed' },
+        { status: 401 }
+      );
+      clearSessionCookies(response);
+      return response;
+    }
+  }
+
+  // Issue new session tokens
+  const newTokens = await issueSessionTokens(username, displayName);
+  const response = NextResponse.json({ status: 'ok' });
+  setSessionCookies(response, newTokens.accessToken, newTokens.refreshToken);
+
+  return response;
+}
diff --git a/app/api/auth/session/route.ts b/app/api/auth/session/route.ts
new file mode 100644
index 0000000..790dbda
--- /dev/null
+++ b/app/api/auth/session/route.ts
@@ -0,0 +1,31 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getSessionFromRequest, setSessionCookies } from '@/lib/auth/cookies';
+import { issueSessionTokens } from '@/lib/auth/jwt';
+
+export async function GET(request: NextRequest) {
+  const session = await getSessionFromRequest(request);
+
+  if (!session) {
+    return NextResponse.json({ error: 'not authenticated' }, { status: 401 });
+  }
+
+  // If the access token was valid, return user info directly
+  if (session.source === 'access') {
+    return NextResponse.json({
+      username: session.username,
+      display_name: session.displayName,
+      source: 'entra',
+    });
+  }
+
+  // Access expired but refresh is valid -- reissue session tokens
+  const newTokens = await issueSessionTokens(session.username, session.displayName);
+  const response = NextResponse.json({
+    username: session.username,
+    display_name: session.displayName,
+    source: 'entra',
+  });
+  setSessionCookies(response, newTokens.accessToken, newTokens.refreshToken);
+
+  return response;
+}
diff --git a/app/api/tiled/[...path]/route.ts b/app/api/tiled/[...path]/route.ts
index 03f9f87..27f360b 100644
--- a/app/api/tiled/[...path]/route.ts
+++ b/app/api/tiled/[...path]/route.ts
@@ -1,4 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { ACCESS_COOKIE } from '@/lib/auth/config';
+import { decodeSessionToken } from '@/lib/auth/jwt';
+import { getOboTokenForUser } from '@/lib/auth/obo';
 
 const TILED_URL = process.env.NEXT_PUBLIC_TILED_URL || 'https://tiled.nsls2.bnl.gov';
 
@@ -12,7 +15,23 @@ export async function GET(
     const searchParams = request.nextUrl.searchParams.toString();
     const url = `${TILED_URL}/api/v1/${tiledPath}${searchParams ? `?${searchParams}` : ''}`;
 
-    const authHeader = request.headers.get('Authorization');
+    // Determine auth: cookie-session (Entra/OBO) or pass-through (Tiled token/API key)
+    let authHeader: string | null = null;
+
+    const sessionCookie = request.cookies.get(ACCESS_COOKIE)?.value;
+    if (sessionCookie) {
+      try {
+        const payload = await decodeSessionToken(sessionCookie, 'access');
+        const tiledToken = await getOboTokenForUser(payload.sub);
+        authHeader = `Bearer ${tiledToken}`;
+      } catch {
+        // Cookie invalid/expired - fall through to header-based auth
+        authHeader = request.headers.get('Authorization');
+      }
+    } else {
+      authHeader = request.headers.get('Authorization');
+    }
+
     const ifNoneMatch = request.headers.get('If-None-Match');
 
     const headers: HeadersInit = {};
diff --git a/app/api/ws/[...path]/route.ts b/app/api/ws/[...path]/route.ts
index d89fe01..20ccafb 100644
--- a/app/api/ws/[...path]/route.ts
+++ b/app/api/ws/[...path]/route.ts
@@ -1,4 +1,7 @@
 import { WebSocket as NodeWebSocket } from 'ws';
+import { ACCESS_COOKIE } from '@/lib/auth/config';
+import { decodeSessionToken } from '@/lib/auth/jwt';
+import { getOboTokenForUser } from '@/lib/auth/obo';
 
 const TILED_URL = process.env.NEXT_PUBLIC_TILED_URL || 'https://tiled.nsls2.bnl.gov';
 
@@ -75,6 +78,29 @@ export function SOCKET(
   const token = url.searchParams.get('token');
   const authType = url.searchParams.get('auth_type') || 'token';
 
+  // Try cookie-based auth (Entra/OBO) first
+  let effectiveToken: string | null = token;
+  let effectiveAuthType: string = authType;
+  let cookieAuthPromise: Promise<string | null> | null = null;
+
+  const cookieHeader = request.headers.cookie || '';
+  const sessionCookieMatch = cookieHeader.match(
+    new RegExp(`(?:^|;\\s*)${ACCESS_COOKIE}=([^;]+)`)
+  );
+
+  if (sessionCookieMatch) {
+    cookieAuthPromise = (async () => {
+      try {
+        const cookieValue = decodeURIComponent(sessionCookieMatch[1]);
+        const payload = await decodeSessionToken(cookieValue, 'access');
+        const oboToken = await getOboTokenForUser(payload.sub);
+        return oboToken;
+      } catch {
+        return null;
+      }
+    })();
+  }
+
   // Build Tiled WebSocket URL with required params
   const wsUrl = TILED_URL.replace('https://', 'wss://').replace('http://', 'ws://');
   const tiledParams = new URLSearchParams();
@@ -88,22 +114,31 @@ export function SOCKET(
   const tiledWsUrl = `${wsUrl}/api/v1/stream/single/${tiledPath}?${tiledParams.toString()}`;
 
   console.log('[WS Proxy] Client connected, proxying to:', tiledWsUrl);
-  console.log('[WS Proxy] Auth type:', authType, 'Token present:', !!token);
+  console.log('[WS Proxy] Auth type:', effectiveAuthType, 'Token present:', !!effectiveToken, 'Cookie auth:', !!cookieAuthPromise);
 
   // Connect to Tiled - need to handle async API key creation
   const connectToTiled = async () => {
+    // Resolve effective token from cookie auth if applicable
+    if (cookieAuthPromise) {
+      const oboToken = await cookieAuthPromise;
+      if (oboToken) {
+        effectiveToken = oboToken;
+        effectiveAuthType = 'token';
+      }
+    }
+
     let apiKey: string | null = null;
     let keyInfo: { secret: string; firstEight: string } | null = null;
 
-    if (token) {
-      if (authType === 'apikey') {
+    if (effectiveToken) {
+      if (effectiveAuthType === 'apikey') {
         // Already have an API key, use it directly
-        apiKey = token;
+        apiKey = effectiveToken;
         console.log('[WS Proxy] Using provided API key');
       } else {
         // Have a Bearer token, create a short-lived API key
         console.log('[WS Proxy] Creating API key from access token...');
-        keyInfo = await createApiKey(token);
+        keyInfo = await createApiKey(effectiveToken);
         if (!keyInfo) {
           client.send(JSON.stringify({ type: 'proxy-error', error: 'Failed to create API key' }));
           client.close(1011, 'Auth error');
@@ -123,9 +158,9 @@ export function SOCKET(
     // Track if we've revoked the key to avoid double-revoke
     let keyRevoked = false;
     const revokeKeyOnce = () => {
-      if (!keyRevoked && keyInfo && token) {
+      if (!keyRevoked && keyInfo && effectiveToken) {
         keyRevoked = true;
-        revokeApiKey(token, keyInfo.firstEight);
+        revokeApiKey(effectiveToken, keyInfo.firstEight);
       }
     };
 
diff --git a/components/layout/header.tsx b/components/layout/header.tsx
index eaa31ed..361dc84 100644
--- a/components/layout/header.tsx
+++ b/components/layout/header.tsx
@@ -64,8 +64,11 @@ export function Header({ isConnected = false }: HeaderProps) {
             <div className="flex items-center gap-2 px-3 py-1.5 rounded-lg bg-surface-raised/50 border border-border-subtle">
               <User className="w-3.5 h-3.5 text-cell" />
               <span className="text-[12px] font-mono text-text-secondary">
-                {user?.identities?.[0]?.id || 'User'}
+                {user?.displayName || 'User'}
               </span>
+              {user?.source === 'entra' && (
+                <span className="text-[9px] font-medium text-nebula bg-nebula/10 px-1.5 py-0.5 rounded">SSO</span>
+              )}
             </div>
             <Button
               variant="ghost"
diff --git a/components/providers/auth-provider.tsx b/components/providers/auth-provider.tsx
index 1ab6a96..38bf85f 100644
--- a/components/providers/auth-provider.tsx
+++ b/components/providers/auth-provider.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
-import { TiledUser } from '@/lib/tiled/types';
+import { TiledUser, AppSessionUser } from '@/lib/tiled/types';
 import {
   getStoredTokens,
   getStoredApiKey,
@@ -14,11 +14,13 @@ import {
   isTokenExpired,
   isRefreshTokenExpired,
   getTokenStatus,
+  setEntraAuthMarker,
+  clearEntraAuthMarker,
 } from '@/lib/tiled/auth';
 import { onAuthError } from '@/lib/tiled/client';
 
 interface AuthState {
-  user: TiledUser | null;
+  user: AppSessionUser | null;
   isAuthenticated: boolean;
   isLoading: boolean;
   accessToken: string | null;
@@ -27,6 +29,7 @@ interface AuthState {
 interface AuthContextValue extends AuthState {
   login: (username: string, password: string) => Promise<void>;
   loginWithApiKey: (apiKey: string) => Promise<void>;
+  loginWithEntra: () => void;
   logout: () => Promise<void>;
 }
 
@@ -41,15 +44,38 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   });
 
   const checkAuth = useCallback(async () => {
-    const authType = getAuthType();
+    // 1. FIRST: Check for Entra cookie session via /api/auth/session
+    try {
+      const sessionResponse = await fetch('/api/auth/session');
+      if (sessionResponse.ok) {
+        const sessionData = await sessionResponse.json();
+        setEntraAuthMarker();
+        setState({
+          user: {
+            username: sessionData.username,
+            displayName: sessionData.display_name,
+            source: 'entra',
+          },
+          isAuthenticated: true,
+          isLoading: false,
+          accessToken: null, // Server-side cookies handle auth
+        });
+        return;
+      }
+      // Non-200: clear stale Entra marker
+      clearEntraAuthMarker();
+    } catch {
+      // Network error: keep marker unchanged, continue to fallback
+    }
 
-    // Check API key auth first
+    // 2. Check API key auth
+    const authType = getAuthType();
     if (authType === 'apikey') {
       const apiKey = getStoredApiKey();
       if (apiKey) {
         const user = await getCurrentUser(apiKey);
         setState({
-          user,
+          user: user ? { username: user.identities?.[0]?.id || 'user', displayName: user.identities?.[0]?.id || 'user', source: 'tiled', tiledUser: user } : null,
           isAuthenticated: !!user,
           isLoading: false,
           accessToken: apiKey,
@@ -58,7 +84,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       }
     }
 
-    // Token-based auth
+    // 3. Token-based auth
     const { accessToken } = getStoredTokens();
 
     if (!accessToken) {
@@ -96,11 +122,11 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       return;
     }
 
-    const user = await getCurrentUser(currentToken);
+    const tiledUser = await getCurrentUser(currentToken);
 
     setState({
-      user,
-      isAuthenticated: !!user,
+      user: tiledUser ? { username: tiledUser.identities?.[0]?.id || 'user', displayName: tiledUser.identities?.[0]?.id || 'user', source: 'tiled', tiledUser } : null,
+      isAuthenticated: !!tiledUser,
       isLoading: false,
       accessToken: currentToken,
     });
@@ -127,9 +153,45 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   // Refresh token proactively and when tab becomes visible
   useEffect(() => {
     if (!state.isAuthenticated) return;
-    if (getAuthType() === 'apikey') return; // API keys don't expire
 
-    // Always try to refresh - don't wait for expiry since refresh tokens may also be short-lived
+    const authType = getAuthType();
+
+    // API keys don't expire
+    if (authType === 'apikey') return;
+
+    if (authType === 'entra') {
+      // Entra sessions: periodically refresh via server-side endpoint
+      const refreshEntra = async () => {
+        try {
+          const response = await fetch('/api/auth/entra/refresh', { method: 'POST' });
+          if (!response.ok) {
+            console.log('[Auth] Entra refresh failed, re-checking session...');
+            checkAuth();
+          }
+        } catch {
+          // Network error, skip
+        }
+      };
+
+      const handleVisibilityChange = () => {
+        if (document.visibilityState === 'visible') {
+          refreshEntra();
+        }
+      };
+
+      document.addEventListener('visibilitychange', handleVisibilityChange);
+      // Refresh every 8 minutes (access token is 10min)
+      const interval = setInterval(refreshEntra, 8 * 60 * 1000);
+      // Also refresh immediately on mount
+      refreshEntra();
+
+      return () => {
+        document.removeEventListener('visibilitychange', handleVisibilityChange);
+        clearInterval(interval);
+      };
+    }
+
+    // Tiled token-based refresh logic (existing)
     const refresh = async (force = false) => {
       const status = getTokenStatus();
       console.log('[Auth] Token status:', {
@@ -139,7 +201,6 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         refreshExpired: status.refreshExpired,
       });
 
-      // If refresh token is expired, no point trying
       if (status.refreshExpired) {
         console.log('[Auth] Refresh token expired, cannot refresh');
         return;
@@ -157,26 +218,19 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       }
     };
 
-    // Handle visibility change - refresh when tab becomes visible
     const handleVisibilityChange = () => {
       if (document.visibilityState === 'visible') {
-        console.log('[Auth] Tab visible, checking token...');
-        refresh(true); // Force refresh when coming back to tab
+        refresh(true);
       }
     };
 
-    // Handle window focus - also catches alt-tab back to browser
     const handleFocus = () => {
       refresh();
     };
 
     document.addEventListener('visibilitychange', handleVisibilityChange);
     window.addEventListener('focus', handleFocus);
-
-    // Refresh more aggressively - every 2 minutes to stay ahead of short-lived tokens
     const interval = setInterval(() => refresh(), 2 * 60 * 1000);
-
-    // Also refresh immediately on mount to ensure fresh token
     refresh();
 
     return () => {
@@ -191,10 +245,10 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
     try {
       const tokens = await loginWithPassword(username, password);
-      const user = await getCurrentUser(tokens.access_token);
+      const tiledUser = await getCurrentUser(tokens.access_token);
 
       setState({
-        user,
+        user: tiledUser ? { username: tiledUser.identities?.[0]?.id || username, displayName: tiledUser.identities?.[0]?.id || username, source: 'tiled', tiledUser } : null,
         isAuthenticated: true,
         isLoading: false,
         accessToken: tokens.access_token,
@@ -214,10 +268,10 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     setState((prev) => ({ ...prev, isLoading: true }));
 
     try {
-      const user = await validateApiKey(apiKey);
+      const tiledUser = await validateApiKey(apiKey);
 
       setState({
-        user,
+        user: { username: tiledUser.identities?.[0]?.id || 'user', displayName: tiledUser.identities?.[0]?.id || 'user', source: 'tiled', tiledUser },
         isAuthenticated: true,
         isLoading: false,
         accessToken: apiKey,
@@ -233,8 +287,25 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     }
   };
 
+  const loginWithEntra = () => {
+    window.location.href = '/api/auth/entra/login';
+  };
+
   const logout = async () => {
-    await tiledLogout();
+    const authType = getAuthType();
+
+    if (authType === 'entra') {
+      // Clear server-side session
+      try {
+        await fetch('/api/auth/entra/logout', { method: 'POST' });
+      } catch {
+        // Best effort
+      }
+      clearEntraAuthMarker();
+    } else {
+      await tiledLogout();
+    }
+
     setState({
       user: null,
       isAuthenticated: false,
@@ -244,7 +315,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   };
 
   return (
-    <AuthContext.Provider value={{ ...state, login, loginWithApiKey: loginWithApiKeyFn, logout }}>
+    <AuthContext.Provider value={{ ...state, login, loginWithApiKey: loginWithApiKeyFn, loginWithEntra, logout }}>
       {children}
     </AuthContext.Provider>
   );
diff --git a/lib/auth/config.ts b/lib/auth/config.ts
new file mode 100644
index 0000000..3f7b5d2
--- /dev/null
+++ b/lib/auth/config.ts
@@ -0,0 +1,114 @@
+import { NextRequest } from 'next/server';
+
+// ---------------------------------------------------------------------------
+// Token lifetimes (matching FastAPI app)
+// ---------------------------------------------------------------------------
+export const ACCESS_TOKEN_LIFETIME = 600; // 10 minutes (seconds)
+export const REFRESH_TOKEN_LIFETIME = 86400; // 24 hours (seconds)
+export const ENTRA_REFRESH_SKEW = 30; // Refresh Entra token 30s before expiry
+
+// ---------------------------------------------------------------------------
+// Cookie names (matching FastAPI app)
+// ---------------------------------------------------------------------------
+export const ACCESS_COOKIE = 'session_access_token';
+export const REFRESH_COOKIE = 'session_refresh_token';
+
+// ---------------------------------------------------------------------------
+// Environment-derived constants
+// ---------------------------------------------------------------------------
+export const TENANT_ID = process.env.ENTRA_TENANT_ID ?? '';
+export const CLIENT_ID = process.env.ENTRA_CLIENT_ID ?? '';
+export const CLIENT_SECRET = process.env.ENTRA_CLIENT_SECRET ?? '';
+export const SESSION_SECRET = process.env.SESSION_SECRET ?? '';
+export const TILED_SCOPE = process.env.TILED_SCOPE ?? '';
+export const APP_BASE_URL = process.env.APP_BASE_URL || null;
+export const REDIRECT_ORIGIN_ALLOWLIST: string[] = (
+  process.env.ENTRA_REDIRECT_ORIGIN_ALLOWLIST || ''
+)
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+// ---------------------------------------------------------------------------
+// Entra endpoints (derived from TENANT_ID)
+// ---------------------------------------------------------------------------
+export const AUTH_ENDPOINT = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/authorize`;
+export const TOKEN_ENDPOINT = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`;
+export const JWKS_URL = `https://login.microsoftonline.com/${TENANT_ID}/discovery/v2.0/keys`;
+
+// ---------------------------------------------------------------------------
+// Scopes requested during login
+// ---------------------------------------------------------------------------
+export function entraUserScope(): string {
+  return `openid profile offline_access api://${CLIENT_ID}/access_as_user`;
+}
+
+// ---------------------------------------------------------------------------
+// Config validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Throws at startup/first-use if required server env vars are missing.
+ */
+export function assertAuthConfig(): void {
+  const missing: string[] = [];
+  if (!TENANT_ID) missing.push('ENTRA_TENANT_ID');
+  if (!CLIENT_ID) missing.push('ENTRA_CLIENT_ID');
+  if (!CLIENT_SECRET) missing.push('ENTRA_CLIENT_SECRET');
+  if (!SESSION_SECRET) missing.push('SESSION_SECRET');
+  if (!TILED_SCOPE) missing.push('TILED_SCOPE');
+  if (missing.length > 0) {
+    throw new Error(
+      `[auth/config] Missing required environment variables: ${missing.join(', ')}`
+    );
+  }
+  if (SESSION_SECRET.length < 32) {
+    throw new Error(
+      '[auth/config] SESSION_SECRET must be at least 32 characters'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Build callback URI from request origin
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the OAuth callback URL from the incoming request.
+ *
+ * Uses X-Forwarded-Host / X-Forwarded-Proto when available (behind proxy),
+ * otherwise falls back to the Host header or APP_BASE_URL.
+ *
+ * Only accepts NextRequest (used in API route handlers).
+ */
+export function buildCallbackUrl(request: NextRequest): string {
+  const origin = resolveOrigin(request);
+  return `${origin}/api/auth/entra/callback`;
+}
+
+function resolveOrigin(request: NextRequest): string {
+  const forwardedHost = request.headers.get('x-forwarded-host');
+  const forwardedProto = request.headers.get('x-forwarded-proto') || 'https';
+  const host = forwardedHost || request.headers.get('host');
+
+  if (host) {
+    const proto = forwardedHost ? forwardedProto : (request.nextUrl.protocol?.replace(':', '') || 'https');
+    const origin = `${proto}://${host}`;
+
+    // If allowlist is configured, validate
+    if (REDIRECT_ORIGIN_ALLOWLIST.length > 0) {
+      if (REDIRECT_ORIGIN_ALLOWLIST.includes(origin)) {
+        return origin;
+      }
+      // Not in allowlist - fall through to APP_BASE_URL
+    } else {
+      return origin;
+    }
+  }
+
+  if (APP_BASE_URL) {
+    return APP_BASE_URL;
+  }
+
+  return 'http://localhost:3000';
+}
diff --git a/lib/auth/cookies.ts b/lib/auth/cookies.ts
new file mode 100644
index 0000000..ab7dcd9
--- /dev/null
+++ b/lib/auth/cookies.ts
@@ -0,0 +1,92 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ACCESS_COOKIE, REFRESH_COOKIE, ACCESS_TOKEN_LIFETIME, REFRESH_TOKEN_LIFETIME } from './config';
+import { decodeSessionToken } from './jwt';
+
+// ---------------------------------------------------------------------------
+// Set / clear session cookies
+// ---------------------------------------------------------------------------
+
+/**
+ * Set session cookies on a NextResponse.
+ * Mirrors: FastAPI app/utils/auth.py set_session_cookies()
+ */
+export function setSessionCookies(
+  response: NextResponse,
+  accessToken: string,
+  refreshToken: string
+): void {
+  const isLocalhost = process.env.NODE_ENV === 'development';
+
+  response.cookies.set(ACCESS_COOKIE, accessToken, {
+    httpOnly: true,
+    secure: !isLocalhost,
+    sameSite: 'strict',
+    path: '/',
+    maxAge: ACCESS_TOKEN_LIFETIME,
+  });
+
+  response.cookies.set(REFRESH_COOKIE, refreshToken, {
+    httpOnly: true,
+    secure: !isLocalhost,
+    sameSite: 'strict',
+    path: '/',
+    maxAge: REFRESH_TOKEN_LIFETIME,
+  });
+}
+
+/**
+ * Clear session cookies.
+ * Mirrors: FastAPI app/utils/auth.py clear_session_cookies()
+ */
+export function clearSessionCookies(response: NextResponse): void {
+  response.cookies.set(ACCESS_COOKIE, '', { path: '/', maxAge: 0 });
+  response.cookies.set(REFRESH_COOKIE, '', { path: '/', maxAge: 0 });
+}
+
+// ---------------------------------------------------------------------------
+// Read session from cookies
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and decode the session from request cookies.
+ * Returns null if no valid session exists.
+ */
+export async function getSessionFromRequest(
+  request: NextRequest
+): Promise<{
+  username: string;
+  displayName: string;
+  source: 'access' | 'refresh';
+} | null> {
+  // Try access token first
+  const accessCookie = request.cookies.get(ACCESS_COOKIE)?.value;
+  if (accessCookie) {
+    try {
+      const payload = await decodeSessionToken(accessCookie, 'access');
+      return {
+        username: payload.sub,
+        displayName: payload.name || payload.sub,
+        source: 'access',
+      };
+    } catch {
+      // Access token invalid/expired -- try refresh below
+    }
+  }
+
+  // Try refresh token
+  const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
+  if (refreshCookie) {
+    try {
+      const payload = await decodeSessionToken(refreshCookie, 'refresh');
+      return {
+        username: payload.sub,
+        displayName: payload.name || payload.sub,
+        source: 'refresh',
+      };
+    } catch {
+      // Refresh token also invalid
+    }
+  }
+
+  return null;
+}
diff --git a/lib/auth/entra.ts b/lib/auth/entra.ts
new file mode 100644
index 0000000..b96281c
--- /dev/null
+++ b/lib/auth/entra.ts
@@ -0,0 +1,148 @@
+import { createRemoteJWKSet, jwtVerify, decodeJwt } from 'jose';
+import {
+  JWKS_URL,
+  TOKEN_ENDPOINT,
+  CLIENT_ID,
+  CLIENT_SECRET,
+  ENTRA_REFRESH_SKEW,
+  TENANT_ID,
+  entraUserScope,
+} from './config';
+
+// ---------------------------------------------------------------------------
+// JWKS (cached automatically by jose)
+// ---------------------------------------------------------------------------
+
+const jwks = createRemoteJWKSet(new URL(JWKS_URL));
+
+// ---------------------------------------------------------------------------
+// Code exchange
+// ---------------------------------------------------------------------------
+
+/**
+ * Exchange an authorization code for user identity + tokens.
+ *
+ * Mirrors: FastAPI app/utils/auth.py exchange_code_for_username()
+ */
+export async function exchangeCodeForUser(
+  code: string,
+  redirectUri: string,
+  codeVerifier: string,
+  expectedNonce: string
+): Promise<{
+  username: string;
+  displayName: string;
+  accessToken: string;
+  refreshToken: string | null;
+}> {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: codeVerifier,
+  });
+
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Entra token exchange failed: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  const idToken: string = data.id_token;
+  const accessToken: string = data.access_token;
+  const refreshToken: string | null = data.refresh_token || null;
+
+  // Verify id_token
+  const { payload } = await jwtVerify(idToken, jwks, {
+    algorithms: ['RS256'],
+    audience: CLIENT_ID,
+    issuer: `https://login.microsoftonline.com/${TENANT_ID}/v2.0`,
+  });
+
+  // Validate nonce
+  if (payload.nonce !== expectedNonce) {
+    throw new Error('id_token nonce mismatch');
+  }
+
+  const username = payload.sub;
+  if (!username) {
+    throw new Error('id_token missing sub claim');
+  }
+
+  const displayName =
+    (payload.name as string) ||
+    (payload.preferred_username as string) ||
+    username;
+
+  return { username, displayName, accessToken, refreshToken };
+}
+
+// ---------------------------------------------------------------------------
+// Token expiry check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if an Entra access token is close to expiry.
+ * Decodes without verification (we only need the exp claim).
+ *
+ * Mirrors: FastAPI app/utils/auth.py is_entra_token_expiring()
+ */
+export function isEntraTokenExpiring(
+  token: string,
+  minTtlSeconds: number = ENTRA_REFRESH_SKEW
+): boolean {
+  try {
+    const claims = decodeJwt(token);
+    const exp = claims.exp;
+    if (exp === undefined) return true;
+    return Date.now() / 1000 > exp - minTtlSeconds;
+  } catch {
+    return true;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Token refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Refresh an Entra access token using the refresh token.
+ *
+ * Mirrors: FastAPI app/utils/auth.py refresh_entra_access_token()
+ */
+export async function refreshEntraAccessToken(
+  refreshToken: string
+): Promise<{ accessToken: string; refreshToken: string }> {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+    refresh_token: refreshToken,
+    scope: entraUserScope(),
+  });
+
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Entra token refresh failed: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || refreshToken,
+  };
+}
diff --git a/lib/auth/jwt.ts b/lib/auth/jwt.ts
new file mode 100644
index 0000000..94ef740
--- /dev/null
+++ b/lib/auth/jwt.ts
@@ -0,0 +1,86 @@
+import { SignJWT, jwtVerify } from 'jose';
+import {
+  SESSION_SECRET,
+  ACCESS_TOKEN_LIFETIME,
+  REFRESH_TOKEN_LIFETIME,
+} from './config';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SessionPayload {
+  sub: string; // username (Entra OID)
+  name: string; // display name
+  type: 'access' | 'refresh';
+  exp: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getSecretKey(): Uint8Array {
+  return new TextEncoder().encode(SESSION_SECRET);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a session JWT signed with SESSION_SECRET (HS256).
+ * Mirrors: FastAPI app/utils/auth.py create_token()
+ */
+export async function createSessionToken(
+  payload: { sub: string; name: string; type: string },
+  lifetime: number
+): Promise<string> {
+  const secret = getSecretKey();
+  return new SignJWT({ ...payload })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setExpirationTime(Math.floor(Date.now() / 1000) + lifetime)
+    .setIssuedAt()
+    .sign(secret);
+}
+
+/**
+ * Decode and verify a session JWT.
+ * Mirrors: FastAPI app/utils/auth.py decode_token()
+ *
+ * Throws if signature invalid, token expired, or type mismatch.
+ */
+export async function decodeSessionToken(
+  token: string,
+  expectedType: 'access' | 'refresh' | 'oidc_flow'
+): Promise<SessionPayload> {
+  const secret = getSecretKey();
+  const { payload } = await jwtVerify(token, secret, {
+    algorithms: ['HS256'],
+  });
+
+  if (payload.type !== expectedType) {
+    throw new Error(`Expected token type '${expectedType}', got '${payload.type}'`);
+  }
+
+  return payload as unknown as SessionPayload;
+}
+
+/**
+ * Issue a pair of session tokens (access + refresh).
+ * Mirrors: FastAPI app/utils/auth.py issue_session_tokens()
+ */
+export async function issueSessionTokens(
+  username: string,
+  displayName: string
+): Promise<{ accessToken: string; refreshToken: string }> {
+  const accessToken = await createSessionToken(
+    { sub: username, name: displayName, type: 'access' },
+    ACCESS_TOKEN_LIFETIME
+  );
+  const refreshToken = await createSessionToken(
+    { sub: username, name: displayName, type: 'refresh' },
+    REFRESH_TOKEN_LIFETIME
+  );
+  return { accessToken, refreshToken };
+}
diff --git a/lib/auth/obo.ts b/lib/auth/obo.ts
new file mode 100644
index 0000000..0bc0276
--- /dev/null
+++ b/lib/auth/obo.ts
@@ -0,0 +1,112 @@
+import { TOKEN_ENDPOINT, CLIENT_ID, CLIENT_SECRET, TILED_SCOPE } from './config';
+import { getFreshEntraToken } from './token-store';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface OboTokenEntry {
+  token: string;
+  expiresAt: number; // Unix ms
+}
+
+// ---------------------------------------------------------------------------
+// In-process OBO token cache (keyed by `${username}:${scope}`)
+// ---------------------------------------------------------------------------
+
+const OBO_CACHE_BUFFER_MS = 60_000; // Evict 1 min before actual expiry
+const oboCacheKey = '__oboCacheStore';
+
+function getOboCache(): Map<string, OboTokenEntry> {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[oboCacheKey]) {
+    g[oboCacheKey] = new Map<string, OboTokenEntry>();
+  }
+  return g[oboCacheKey] as Map<string, OboTokenEntry>;
+}
+
+// ---------------------------------------------------------------------------
+// OBO exchange
+// ---------------------------------------------------------------------------
+
+/**
+ * Exchange an Entra access token for a Tiled-scoped token via OBO.
+ *
+ * Mirrors: FastAPI app/utils/auth.py exchange_token_obo()
+ */
+async function exchangeTokenObo(
+  entraAccessToken: string
+): Promise<{ access_token: string; expires_in: number }> {
+  const body = new URLSearchParams({
+    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+    assertion: entraAccessToken,
+    requested_token_use: 'on_behalf_of',
+    scope: TILED_SCOPE,
+  });
+
+  const response = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`OBO token exchange failed: ${response.status} ${errorText}`);
+  }
+
+  const data = await response.json();
+  return {
+    access_token: data.access_token,
+    expires_in: data.expires_in || 3600, // Default 1hr if not specified
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a valid OBO token for a user, using cache when possible.
+ *
+ * Flow:
+ * 1. Check cache for non-expired entry -> return if valid
+ * 2. Get fresh Entra token (auto-refreshes if needed)
+ * 3. Exchange for Tiled-scoped OBO token
+ * 4. Cache the result
+ * 5. Return the token
+ */
+export async function getOboTokenForUser(username: string): Promise<string> {
+  const cache = getOboCache();
+  const cacheKey = `${username}:${TILED_SCOPE}`;
+
+  const cached = cache.get(cacheKey);
+  if (cached && Date.now() < cached.expiresAt - OBO_CACHE_BUFFER_MS) {
+    return cached.token;
+  }
+
+  // Get a fresh Entra token for this user
+  const entraToken = await getFreshEntraToken(username);
+
+  // Exchange for Tiled token
+  const oboResult = await exchangeTokenObo(entraToken);
+
+  // Cache it
+  cache.set(cacheKey, {
+    token: oboResult.access_token,
+    expiresAt: Date.now() + oboResult.expires_in * 1000,
+  });
+
+  return oboResult.access_token;
+}
+
+/**
+ * Clear a user's OBO cache entry (e.g., on logout).
+ */
+export function clearOboCache(username: string): void {
+  const cache = getOboCache();
+  const cacheKey = `${username}:${TILED_SCOPE}`;
+  cache.delete(cacheKey);
+}
diff --git a/lib/auth/oidc-flow.ts b/lib/auth/oidc-flow.ts
new file mode 100644
index 0000000..a27a0a9
--- /dev/null
+++ b/lib/auth/oidc-flow.ts
@@ -0,0 +1,144 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { SignJWT, jwtVerify } from 'jose';
+import { SESSION_SECRET } from './config';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const OIDC_FLOW_COOKIE = 'oidc_flow';
+export const OIDC_FLOW_LIFETIME_SECONDS = 10 * 60; // 10 minutes
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export interface OidcFlowState {
+  state: string;
+  nonce: string;
+  codeVerifier: string;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getSecretKey(): Uint8Array {
+  return new TextEncoder().encode(SESSION_SECRET);
+}
+
+function generateRandomString(length: number): string {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+
+function base64UrlEncode(data: Uint8Array): string {
+  const base64 = Buffer.from(data).toString('base64');
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create cryptographically random state material for authorization-code flow.
+ */
+export function createOidcFlowState(): OidcFlowState {
+  return {
+    state: generateRandomString(32),
+    nonce: generateRandomString(32),
+    codeVerifier: generateRandomString(48),
+    createdAt: Date.now(),
+  };
+}
+
+/**
+ * Build S256 PKCE code_challenge from code_verifier.
+ */
+export async function buildPkceChallenge(codeVerifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+/**
+ * Serialize flow state into a signed JWT (HS256 with SESSION_SECRET) and
+ * set it as an httpOnly cookie on the response.
+ *
+ * JWT payload: { state, nonce, code_verifier, type: 'oidc_flow', exp }
+ */
+export async function setOidcFlowCookie(
+  response: NextResponse,
+  flowState: OidcFlowState
+): Promise<void> {
+  const secret = getSecretKey();
+  const token = await new SignJWT({
+    state: flowState.state,
+    nonce: flowState.nonce,
+    code_verifier: flowState.codeVerifier,
+    type: 'oidc_flow',
+  })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setExpirationTime(Math.floor(Date.now() / 1000) + OIDC_FLOW_LIFETIME_SECONDS)
+    .setIssuedAt()
+    .sign(secret);
+
+  const isLocalhost = process.env.NODE_ENV === 'development';
+
+  response.cookies.set(OIDC_FLOW_COOKIE, token, {
+    httpOnly: true,
+    secure: !isLocalhost,
+    sameSite: 'lax', // Must be lax for cross-site top-level redirect from Entra
+    path: '/',
+    maxAge: OIDC_FLOW_LIFETIME_SECONDS,
+  });
+}
+
+/**
+ * Read the oidc_flow cookie from the request, verify the JWT signature,
+ * validate that `state` matches the query param, and return the nonce +
+ * codeVerifier.
+ *
+ * Always marks the cookie for deletion (single-use).
+ *
+ * Throws if:
+ * - Cookie missing or JWT invalid/expired
+ * - JWT `type` claim is not `oidc_flow`
+ * - state param does not match the JWT's state claim
+ */
+export async function validateAndConsumeOidcFlow(
+  request: NextRequest,
+  stateParam: string
+): Promise<{ nonce: string; codeVerifier: string }> {
+  const cookieValue = request.cookies.get(OIDC_FLOW_COOKIE)?.value;
+  if (!cookieValue) {
+    throw new Error('OIDC flow cookie missing');
+  }
+
+  const secret = getSecretKey();
+  const { payload } = await jwtVerify(cookieValue, secret, {
+    algorithms: ['HS256'],
+  });
+
+  if (payload.type !== 'oidc_flow') {
+    throw new Error('Invalid OIDC flow token type');
+  }
+
+  if (payload.state !== stateParam) {
+    throw new Error('OIDC state mismatch');
+  }
+
+  return {
+    nonce: payload.nonce as string,
+    codeVerifier: payload.code_verifier as string,
+  };
+}
+
+/**
+ * Delete the oidc_flow cookie on a response (call after validation).
+ */
+export function clearOidcFlowCookie(response: NextResponse): void {
+  response.cookies.set(OIDC_FLOW_COOKIE, '', { path: '/', maxAge: 0 });
+}
diff --git a/lib/auth/token-store.ts b/lib/auth/token-store.ts
new file mode 100644
index 0000000..57a85c3
--- /dev/null
+++ b/lib/auth/token-store.ts
@@ -0,0 +1,81 @@
+import { isEntraTokenExpiring, refreshEntraAccessToken } from './entra';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EntraTokenEntry {
+  entraAccessToken: string;
+  entraRefreshToken: string | null;
+  storedAt: number; // Date.now() when stored
+}
+
+// ---------------------------------------------------------------------------
+// In-memory store (survives hot-reload in dev via globalThis)
+// ---------------------------------------------------------------------------
+
+const globalKey = '__entraTokenStore';
+
+function getStore(): Map<string, EntraTokenEntry> {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[globalKey]) {
+    g[globalKey] = new Map<string, EntraTokenEntry>();
+  }
+  return g[globalKey] as Map<string, EntraTokenEntry>;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function getTokens(username: string): EntraTokenEntry | null {
+  return getStore().get(username) ?? null;
+}
+
+export function setTokens(username: string, entry: EntraTokenEntry): void {
+  getStore().set(username, entry);
+}
+
+export function deleteTokens(username: string): void {
+  getStore().delete(username);
+}
+
+/**
+ * Get a fresh (non-expired) Entra access token for a user.
+ * If the stored token is expiring, refreshes it automatically.
+ * If refresh fails, deletes the entry and throws.
+ *
+ * Mirrors: FastAPI app/utils/auth.py get_fresh_entra_access_token()
+ */
+export async function getFreshEntraToken(username: string): Promise<string> {
+  const entry = getTokens(username);
+  if (!entry) {
+    throw new Error('No Entra credentials stored for user');
+  }
+
+  if (!isEntraTokenExpiring(entry.entraAccessToken)) {
+    return entry.entraAccessToken;
+  }
+
+  // Token is expiring -- attempt refresh
+  if (!entry.entraRefreshToken) {
+    deleteTokens(username);
+    throw new Error('Entra refresh token missing; re-authentication required');
+  }
+
+  try {
+    const refreshed = await refreshEntraAccessToken(entry.entraRefreshToken);
+    const updatedEntry: EntraTokenEntry = {
+      entraAccessToken: refreshed.accessToken,
+      entraRefreshToken: refreshed.refreshToken,
+      storedAt: Date.now(),
+    };
+    setTokens(username, updatedEntry);
+    return refreshed.accessToken;
+  } catch (err) {
+    deleteTokens(username);
+    throw new Error(
+      `Entra token refresh failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
diff --git a/lib/tiled/auth.ts b/lib/tiled/auth.ts
index b5106ba..dc929c3 100644
--- a/lib/tiled/auth.ts
+++ b/lib/tiled/auth.ts
@@ -7,7 +7,7 @@ const REFRESH_TOKEN_EXPIRY_KEY = 'tiled_refresh_token_expiry';
 const API_KEY_KEY = 'tiled_api_key';
 const AUTH_TYPE_KEY = 'tiled_auth_type';
 
-type AuthType = 'token' | 'apikey';
+type AuthType = 'token' | 'apikey' | 'entra';
 
 export function getStoredTokens(): { accessToken: string | null; refreshToken: string | null; expiresAt: number | null } {
   if (typeof window === 'undefined') {
@@ -31,6 +31,24 @@ export function getAuthType(): AuthType | null {
   return localStorage.getItem(AUTH_TYPE_KEY) as AuthType | null;
 }
 
+export function setEntraAuthMarker(): void {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(AUTH_TYPE_KEY, 'entra');
+  // Clear any Tiled tokens when switching to Entra
+  localStorage.removeItem(TOKEN_KEY);
+  localStorage.removeItem(REFRESH_TOKEN_KEY);
+  localStorage.removeItem(TOKEN_EXPIRY_KEY);
+  localStorage.removeItem(REFRESH_TOKEN_EXPIRY_KEY);
+  localStorage.removeItem(API_KEY_KEY);
+}
+
+export function clearEntraAuthMarker(): void {
+  if (typeof window === 'undefined') return;
+  if (localStorage.getItem(AUTH_TYPE_KEY) === 'entra') {
+    localStorage.removeItem(AUTH_TYPE_KEY);
+  }
+}
+
 export function storeTokens(response: TokenResponse): void {
   if (typeof window === 'undefined') return;
 
@@ -258,6 +276,11 @@ export async function logout(): Promise<void> {
 export async function getValidAccessToken(): Promise<string | null> {
   const authType = getAuthType();
 
+  // For Entra sessions, auth is handled server-side via cookies
+  if (authType === 'entra') {
+    return null;
+  }
+
   // If using API key, return it directly (they don't expire)
   if (authType === 'apikey') {
     return getStoredApiKey();
diff --git a/lib/tiled/client.ts b/lib/tiled/client.ts
index 674148f..d6ca001 100644
--- a/lib/tiled/client.ts
+++ b/lib/tiled/client.ts
@@ -57,13 +57,19 @@ function notifyAuthError(): void {
 
 // Get a valid auth header, refreshing token if needed
 async function getValidAuthHeader(): Promise<string | null> {
+  // For Entra sessions, auth is handled server-side via cookies
+  // The browser automatically sends cookies; no Authorization header needed
+  const authType = getAuthType();
+  if (authType === 'entra') {
+    return null;
+  }
+
   const token = await getValidAccessToken();
   if (!token) {
     console.log('[Client] No valid token available');
     return null;
   }
 
-  const authType = getAuthType();
   return authType === 'apikey' ? `Apikey ${token}` : `Bearer ${token}`;
 }
 
@@ -79,19 +85,41 @@ async function fetchWithAuth(url: string, options: RequestInit = {}, isRetry = f
 
   // On 401, try to refresh and retry once
   if (response.status === 401 && !isRetry) {
-    console.log('[Client] Got 401, attempting token refresh and retry...');
-    const { refreshAccessToken } = await import('./auth');
-    const refreshed = await refreshAccessToken();
+    const currentAuthType = getAuthType();
+
+    if (currentAuthType === 'entra') {
+      // For Entra sessions, call the server-side refresh endpoint
+      console.log('[Client] Got 401 in Entra mode, calling server refresh...');
+      try {
+        const refreshResponse = await fetch('/api/auth/entra/refresh', { method: 'POST' });
+        if (refreshResponse.ok) {
+          console.log('[Client] Entra session refreshed, retrying request...');
+          return fetchWithAuth(url, options, true);
+        }
+      } catch {
+        // Refresh failed
+      }
+      // Refresh failed - notify auth error
+      console.log('[Client] Entra refresh failed, logging out');
+      const { clearEntraAuthMarker } = await import('./auth');
+      clearEntraAuthMarker();
+      notifyAuthError();
+    } else {
+      // For Tiled token auth, try client-side refresh
+      console.log('[Client] Got 401, attempting token refresh and retry...');
+      const { refreshAccessToken } = await import('./auth');
+      const refreshed = await refreshAccessToken();
+
+      if (refreshed) {
+        console.log('[Client] Token refreshed, retrying request...');
+        return fetchWithAuth(url, options, true);
+      }
 
-    if (refreshed) {
-      console.log('[Client] Token refreshed, retrying request...');
-      return fetchWithAuth(url, options, true);
+      // Refresh failed - clear tokens and notify
+      console.log('[Client] Token refresh failed, logging out');
+      clearTokens();
+      notifyAuthError();
     }
-
-    // Refresh failed - clear tokens and notify
-    console.log('[Client] Token refresh failed, logging out');
-    clearTokens();
-    notifyAuthError();
   }
 
   return response;
diff --git a/lib/tiled/types.ts b/lib/tiled/types.ts
index ec99a4b..e351830 100644
--- a/lib/tiled/types.ts
+++ b/lib/tiled/types.ts
@@ -15,6 +15,16 @@ export interface TiledUser {
   roles?: string[];
 }
 
+/**
+ * Unified user identity across Tiled and Entra sessions.
+ */
+export interface AppSessionUser {
+  username: string;
+  displayName: string;
+  source: 'entra' | 'tiled';
+  tiledUser?: TiledUser;
+}
+
 export interface TiledSearchResponse<T = TiledNode> {
   data: T[];
   links: {
diff --git a/lib/tiled/websocket.ts b/lib/tiled/websocket.ts
index 39cd765..062f846 100644
--- a/lib/tiled/websocket.ts
+++ b/lib/tiled/websocket.ts
@@ -53,8 +53,9 @@ export class TiledWebSocket {
       url = `${wsProtocol}//${window.location.host}/api/ws/${this.path}`;
 
       // Pass token as query param to our proxy
+      // For Entra sessions, don't send a token - the proxy reads httpOnly cookies
       const params = new URLSearchParams();
-      if (token) {
+      if (authType !== 'entra' && token) {
         params.set('token', token);
         params.set('auth_type', authType || 'token');
       }
diff --git a/package-lock.json b/package-lock.json
index 0d6eb8b..6812188 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,6 +16,7 @@
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "framer-motion": "^12.34.3",
+        "jose": "^6.2.3",
         "lucide-react": "^0.575.0",
         "next": "^16.2.4",
         "next-ws": "^2.1.17",
@@ -8372,10 +8373,9 @@
       }
     },
     "node_modules/jose": {
-      "version": "6.1.3",
-      "resolved": "https://registry.npmjs.org/jose/-/jose-6.1.3.tgz",
-      "integrity": "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==",
-      "dev": true,
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
+      "integrity": "sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==",
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/panva"
diff --git a/package.json b/package.json
index a145ba1..33f116d 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "framer-motion": "^12.34.3",
+    "jose": "^6.2.3",
     "lucide-react": "^0.575.0",
     "next": "^16.2.4",
     "next-ws": "^2.1.17",

From 379968d5fca8f4d27f5564d3c4bea4aaeeeaefbc Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 11:41:41 -0400
Subject: [PATCH 02/19] validateAndConsumeOidcFlow now clears cookie

---
 app/api/auth/entra/callback/route.ts | 24 +++++++++-----
 lib/auth/oidc-flow.ts                | 47 +++++++++++++++-------------
 2 files changed, 42 insertions(+), 29 deletions(-)

diff --git a/app/api/auth/entra/callback/route.ts b/app/api/auth/entra/callback/route.ts
index fdc4cfe..1d8f5fd 100644
--- a/app/api/auth/entra/callback/route.ts
+++ b/app/api/auth/entra/callback/route.ts
@@ -16,16 +16,26 @@ export async function GET(request: NextRequest) {
   // Handle Entra error response
   if (error) {
     console.error('[Entra Callback] Error from Entra:', error);
-    return NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
+    const response = NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
+    clearOidcFlowCookie(response);
+    return response;
   }
 
   if (!code || !stateParam) {
-    return NextResponse.redirect(new URL('/login?error=missing_code', request.url));
+    const response = NextResponse.redirect(new URL('/login?error=missing_code', request.url));
+    clearOidcFlowCookie(response);
+    return response;
   }
 
+  const response = NextResponse.redirect(new URL('/', request.url));
+
   try {
     // Validate OIDC flow state (checks cookie, state match)
-    const { nonce, codeVerifier } = await validateAndConsumeOidcFlow(request, stateParam);
+    const { nonce, codeVerifier } = await validateAndConsumeOidcFlow(
+      request,
+      response,
+      stateParam
+    );
 
     // Build the same redirect_uri used in the login request
     const redirectUri = buildCallbackUrl(request);
@@ -45,15 +55,13 @@ export async function GET(request: NextRequest) {
     const sessionTokens = await issueSessionTokens(username, displayName);
 
     // Redirect to app root with session cookies set
-    const response = NextResponse.redirect(new URL('/', request.url));
     setSessionCookies(response, sessionTokens.accessToken, sessionTokens.refreshToken);
-    clearOidcFlowCookie(response);
 
     return response;
   } catch (err) {
     console.error('[Entra Callback] Auth failed:', err instanceof Error ? err.message : err);
-    const response = NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
-    clearOidcFlowCookie(response);
-    return response;
+    const errorResponse = NextResponse.redirect(new URL('/login?error=signin_failed', request.url));
+    clearOidcFlowCookie(errorResponse);
+    return errorResponse;
   }
 }
diff --git a/lib/auth/oidc-flow.ts b/lib/auth/oidc-flow.ts
index a27a0a9..a7b1b04 100644
--- a/lib/auth/oidc-flow.ts
+++ b/lib/auth/oidc-flow.ts
@@ -110,30 +110,35 @@ export async function setOidcFlowCookie(
  */
 export async function validateAndConsumeOidcFlow(
   request: NextRequest,
+  response: NextResponse,
   stateParam: string
 ): Promise<{ nonce: string; codeVerifier: string }> {
-  const cookieValue = request.cookies.get(OIDC_FLOW_COOKIE)?.value;
-  if (!cookieValue) {
-    throw new Error('OIDC flow cookie missing');
-  }
-
-  const secret = getSecretKey();
-  const { payload } = await jwtVerify(cookieValue, secret, {
-    algorithms: ['HS256'],
-  });
-
-  if (payload.type !== 'oidc_flow') {
-    throw new Error('Invalid OIDC flow token type');
+  try {
+    const cookieValue = request.cookies.get(OIDC_FLOW_COOKIE)?.value;
+    if (!cookieValue) {
+      throw new Error('OIDC flow cookie missing');
+    }
+
+    const secret = getSecretKey();
+    const { payload } = await jwtVerify(cookieValue, secret, {
+      algorithms: ['HS256'],
+    });
+
+    if (payload.type !== 'oidc_flow') {
+      throw new Error('Invalid OIDC flow token type');
+    }
+
+    if (payload.state !== stateParam) {
+      throw new Error('OIDC state mismatch');
+    }
+
+    return {
+      nonce: payload.nonce as string,
+      codeVerifier: payload.code_verifier as string,
+    };
+  } finally {
+    clearOidcFlowCookie(response);
   }
-
-  if (payload.state !== stateParam) {
-    throw new Error('OIDC state mismatch');
-  }
-
-  return {
-    nonce: payload.nonce as string,
-    codeVerifier: payload.code_verifier as string,
-  };
 }
 
 /**

From 16ed7bad270c36e5772e23922cee9cb856a3b851 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 11:49:15 -0400
Subject: [PATCH 03/19] Fix redirect uri-generation code

---
 lib/auth/config.ts | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/lib/auth/config.ts b/lib/auth/config.ts
index 3f7b5d2..b805fea 100644
--- a/lib/auth/config.ts
+++ b/lib/auth/config.ts
@@ -87,12 +87,26 @@ export function buildCallbackUrl(request: NextRequest): string {
 }
 
 function resolveOrigin(request: NextRequest): string {
-  const forwardedHost = request.headers.get('x-forwarded-host');
-  const forwardedProto = request.headers.get('x-forwarded-proto') || 'https';
-  const host = forwardedHost || request.headers.get('host');
+  const forwardedHost = request.headers.get('x-forwarded-host')?.split(',')[0]?.trim();
+  const forwardedProtoRaw = request
+    .headers.get('x-forwarded-proto')
+    ?.split(',')[0]
+    ?.trim()
+    ?.toLowerCase();
+  const forwardedProto =
+    forwardedProtoRaw === 'http' || forwardedProtoRaw === 'https'
+      ? forwardedProtoRaw
+      : 'https';
+  const host = forwardedHost || request.headers.get('host')?.split(',')[0]?.trim();
 
   if (host) {
-    const proto = forwardedHost ? forwardedProto : (request.nextUrl.protocol?.replace(':', '') || 'https');
+    const requestProto = request.nextUrl.protocol?.replace(':', '').toLowerCase();
+    const proto =
+      forwardedHost
+        ? forwardedProto
+        : requestProto === 'http' || requestProto === 'https'
+          ? requestProto
+          : 'https';
     const origin = `${proto}://${host}`;
 
     // If allowlist is configured, validate

From bea5d31be5d6f847733ca2694c7e88ae59d7fe63 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 11:51:09 -0400
Subject: [PATCH 04/19] Removed getFreshEntraToken from imports

---
 app/api/auth/entra/refresh/route.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
index fbff54d..0297fec 100644
--- a/app/api/auth/entra/refresh/route.ts
+++ b/app/api/auth/entra/refresh/route.ts
@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { REFRESH_COOKIE } from '@/lib/auth/config';
 import { decodeSessionToken, issueSessionTokens } from '@/lib/auth/jwt';
 import { setSessionCookies, clearSessionCookies } from '@/lib/auth/cookies';
-import { getTokens, getFreshEntraToken, setTokens } from '@/lib/auth/token-store';
+import { getTokens, setTokens } from '@/lib/auth/token-store';
 import { refreshEntraAccessToken } from '@/lib/auth/entra';
 
 export async function POST(request: NextRequest) {

From e7ecfe2c98e324e1e710683bb5de30c28022cc47 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 11:57:30 -0400
Subject: [PATCH 05/19] Add reauth when refresh token expired

---
 app/api/auth/entra/refresh/route.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
index 0297fec..a73e838 100644
--- a/app/api/auth/entra/refresh/route.ts
+++ b/app/api/auth/entra/refresh/route.ts
@@ -2,8 +2,8 @@ import { NextRequest, NextResponse } from 'next/server';
 import { REFRESH_COOKIE } from '@/lib/auth/config';
 import { decodeSessionToken, issueSessionTokens } from '@/lib/auth/jwt';
 import { setSessionCookies, clearSessionCookies } from '@/lib/auth/cookies';
-import { getTokens, setTokens } from '@/lib/auth/token-store';
-import { refreshEntraAccessToken } from '@/lib/auth/entra';
+import { deleteTokens, getTokens, setTokens } from '@/lib/auth/token-store';
+import { isEntraTokenExpiring, refreshEntraAccessToken } from '@/lib/auth/entra';
 
 export async function POST(request: NextRequest) {
   const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
@@ -44,7 +44,6 @@ export async function POST(request: NextRequest) {
     } catch (err) {
       console.error('[Entra Refresh] Failed:', err instanceof Error ? err.message : err);
       // Clear stored tokens on refresh failure
-      const { deleteTokens } = await import('@/lib/auth/token-store');
       deleteTokens(username);
       const response = NextResponse.json(
         { error: 'entra refresh failed' },
@@ -53,6 +52,15 @@ export async function POST(request: NextRequest) {
       clearSessionCookies(response);
       return response;
     }
+  } else if (isEntraTokenExpiring(entry.entraAccessToken)) {
+    // No refresh token available and the access token is expiring/expired.
+    deleteTokens(username);
+    const response = NextResponse.json(
+      { error: 'entra refresh token missing; re-authentication required' },
+      { status: 401 }
+    );
+    clearSessionCookies(response);
+    return response;
   }
 
   // Issue new session tokens

From ffc50df89f07ad8f0f3b93206923cade0c1af2a5 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:02:32 -0400
Subject: [PATCH 06/19] Verify token store entry exists before authenticating
 client

---
 app/api/auth/session/route.ts | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/app/api/auth/session/route.ts b/app/api/auth/session/route.ts
index 790dbda..5fee437 100644
--- a/app/api/auth/session/route.ts
+++ b/app/api/auth/session/route.ts
@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { getSessionFromRequest, setSessionCookies } from '@/lib/auth/cookies';
+import { getSessionFromRequest, setSessionCookies, clearSessionCookies } from '@/lib/auth/cookies';
 import { issueSessionTokens } from '@/lib/auth/jwt';
+import { deleteTokens, getTokens } from '@/lib/auth/token-store';
+import { isEntraTokenExpiring } from '@/lib/auth/entra';
 
 export async function GET(request: NextRequest) {
   const session = await getSessionFromRequest(request);
@@ -9,6 +11,22 @@ export async function GET(request: NextRequest) {
     return NextResponse.json({ error: 'not authenticated' }, { status: 401 });
   }
 
+  // Ensure server-side Entra credentials still exist
+  const entry = getTokens(session.username);
+  if (!entry) {
+    const response = NextResponse.json({ error: 'not authenticated' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
+  }
+
+  // If Entra access is expiring and cannot be refreshed, force re-authentication
+  if (!entry.entraRefreshToken && isEntraTokenExpiring(entry.entraAccessToken)) {
+    deleteTokens(session.username);
+    const response = NextResponse.json({ error: 'not authenticated' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
+  }
+
   // If the access token was valid, return user info directly
   if (session.source === 'access') {
     return NextResponse.json({

From 3f759fa65f2605012354aabff793fc2bb55a4fe0 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:14:38 -0400
Subject: [PATCH 07/19] Send token to tiled-ws after checking both refresh and
 access cookie

---
 app/api/ws/[...path]/route.ts | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/app/api/ws/[...path]/route.ts b/app/api/ws/[...path]/route.ts
index 20ccafb..c288aa8 100644
--- a/app/api/ws/[...path]/route.ts
+++ b/app/api/ws/[...path]/route.ts
@@ -1,5 +1,5 @@
 import { WebSocket as NodeWebSocket } from 'ws';
-import { ACCESS_COOKIE } from '@/lib/auth/config';
+import { ACCESS_COOKIE, REFRESH_COOKIE } from '@/lib/auth/config';
 import { decodeSessionToken } from '@/lib/auth/jwt';
 import { getOboTokenForUser } from '@/lib/auth/obo';
 
@@ -84,20 +84,36 @@ export function SOCKET(
   let cookieAuthPromise: Promise<string | null> | null = null;
 
   const cookieHeader = request.headers.cookie || '';
-  const sessionCookieMatch = cookieHeader.match(
+  const accessCookieMatch = cookieHeader.match(
     new RegExp(`(?:^|;\\s*)${ACCESS_COOKIE}=([^;]+)`)
   );
+  const refreshCookieMatch = cookieHeader.match(
+    new RegExp(`(?:^|;\\s*)${REFRESH_COOKIE}=([^;]+)`)
+  );
 
-  if (sessionCookieMatch) {
+  if (accessCookieMatch || refreshCookieMatch) {
     cookieAuthPromise = (async () => {
       try {
-        const cookieValue = decodeURIComponent(sessionCookieMatch[1]);
-        const payload = await decodeSessionToken(cookieValue, 'access');
-        const oboToken = await getOboTokenForUser(payload.sub);
-        return oboToken;
+        if (accessCookieMatch) {
+          const accessCookieValue = decodeURIComponent(accessCookieMatch[1]);
+          const accessPayload = await decodeSessionToken(accessCookieValue, 'access');
+          return await getOboTokenForUser(accessPayload.sub);
+        }
+      } catch {
+        // Access cookie invalid/expired -- try refresh cookie below
+      }
+
+      try {
+        if (refreshCookieMatch) {
+          const refreshCookieValue = decodeURIComponent(refreshCookieMatch[1]);
+          const refreshPayload = await decodeSessionToken(refreshCookieValue, 'refresh');
+          return await getOboTokenForUser(refreshPayload.sub);
+        }
       } catch {
         return null;
       }
+
+      return null;
     })();
   }
 

From e879b5e3a69573b703c461c41002033a47fd7814 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:15:32 -0400
Subject: [PATCH 08/19] Added stronger typing for cookie type

---
 lib/auth/jwt.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/auth/jwt.ts b/lib/auth/jwt.ts
index 94ef740..e17ce89 100644
--- a/lib/auth/jwt.ts
+++ b/lib/auth/jwt.ts
@@ -33,7 +33,7 @@ function getSecretKey(): Uint8Array {
  * Mirrors: FastAPI app/utils/auth.py create_token()
  */
 export async function createSessionToken(
-  payload: { sub: string; name: string; type: string },
+  payload: { sub: string; name: string; type: SessionPayload['type'] },
   lifetime: number
 ): Promise<string> {
   const secret = getSecretKey();
@@ -52,7 +52,7 @@ export async function createSessionToken(
  */
 export async function decodeSessionToken(
   token: string,
-  expectedType: 'access' | 'refresh' | 'oidc_flow'
+  expectedType: SessionPayload['type']
 ): Promise<SessionPayload> {
   const secret = getSecretKey();
   const { payload } = await jwtVerify(token, secret, {

From bdda4269f7b9d5ccd99b3de1b4f5e5a73a9ce4e3 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:26:20 -0400
Subject: [PATCH 09/19] Changed 'sameSite' from strict to lax in cookies

---
 lib/auth/cookies.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/auth/cookies.ts b/lib/auth/cookies.ts
index ab7dcd9..59d5c01 100644
--- a/lib/auth/cookies.ts
+++ b/lib/auth/cookies.ts
@@ -20,7 +20,7 @@ export function setSessionCookies(
   response.cookies.set(ACCESS_COOKIE, accessToken, {
     httpOnly: true,
     secure: !isLocalhost,
-    sameSite: 'strict',
+    sameSite: 'lax',
     path: '/',
     maxAge: ACCESS_TOKEN_LIFETIME,
   });
@@ -28,7 +28,7 @@ export function setSessionCookies(
   response.cookies.set(REFRESH_COOKIE, refreshToken, {
     httpOnly: true,
     secure: !isLocalhost,
-    sameSite: 'strict',
+    sameSite: 'lax',
     path: '/',
     maxAge: REFRESH_TOKEN_LIFETIME,
   });

From 946afccfdaa93ecb4ee1be8bc48e0c0d4e0ecafc Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:30:00 -0400
Subject: [PATCH 10/19] Added helper for auth-provider fallback

---
 components/providers/auth-provider.tsx | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/components/providers/auth-provider.tsx b/components/providers/auth-provider.tsx
index 38bf85f..6a2d9ba 100644
--- a/components/providers/auth-provider.tsx
+++ b/components/providers/auth-provider.tsx
@@ -35,6 +35,23 @@ interface AuthContextValue extends AuthState {
 
 const AuthContext = createContext<AuthContextValue | null>(null);
 
+function toAppSessionUser(
+  tiledUser: TiledUser | null,
+  fallbackName: string = 'user'
+): AppSessionUser | null {
+  if (!tiledUser) {
+    return null;
+  }
+
+  const identity = tiledUser.identities?.[0]?.id || fallbackName;
+  return {
+    username: identity,
+    displayName: identity,
+    source: 'tiled',
+    tiledUser,
+  };
+}
+
 export function AuthProvider({ children }: { children: React.ReactNode }) {
   const [state, setState] = useState<AuthState>({
     user: null,
@@ -75,7 +92,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       if (apiKey) {
         const user = await getCurrentUser(apiKey);
         setState({
-          user: user ? { username: user.identities?.[0]?.id || 'user', displayName: user.identities?.[0]?.id || 'user', source: 'tiled', tiledUser: user } : null,
+          user: toAppSessionUser(user),
           isAuthenticated: !!user,
           isLoading: false,
           accessToken: apiKey,
@@ -125,7 +142,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     const tiledUser = await getCurrentUser(currentToken);
 
     setState({
-      user: tiledUser ? { username: tiledUser.identities?.[0]?.id || 'user', displayName: tiledUser.identities?.[0]?.id || 'user', source: 'tiled', tiledUser } : null,
+      user: toAppSessionUser(tiledUser),
       isAuthenticated: !!tiledUser,
       isLoading: false,
       accessToken: currentToken,
@@ -248,7 +265,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       const tiledUser = await getCurrentUser(tokens.access_token);
 
       setState({
-        user: tiledUser ? { username: tiledUser.identities?.[0]?.id || username, displayName: tiledUser.identities?.[0]?.id || username, source: 'tiled', tiledUser } : null,
+        user: toAppSessionUser(tiledUser, username),
         isAuthenticated: true,
         isLoading: false,
         accessToken: tokens.access_token,
@@ -271,7 +288,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       const tiledUser = await validateApiKey(apiKey);
 
       setState({
-        user: { username: tiledUser.identities?.[0]?.id || 'user', displayName: tiledUser.identities?.[0]?.id || 'user', source: 'tiled', tiledUser },
+        user: toAppSessionUser(tiledUser),
         isAuthenticated: true,
         isLoading: false,
         accessToken: apiKey,

From 344fb58397936180d8dbacffa3cb27218d5a9eb6 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:33:15 -0400
Subject: [PATCH 11/19] Fixed lint issues

---
 components/providers/auth-provider.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/components/providers/auth-provider.tsx b/components/providers/auth-provider.tsx
index 6a2d9ba..2ad7c87 100644
--- a/components/providers/auth-provider.tsx
+++ b/components/providers/auth-provider.tsx
@@ -12,7 +12,6 @@ import {
   getCurrentUser,
   refreshAccessToken,
   isTokenExpired,
-  isRefreshTokenExpired,
   getTokenStatus,
   setEntraAuthMarker,
   clearEntraAuthMarker,
@@ -150,7 +149,13 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   }, []);
 
   useEffect(() => {
-    checkAuth();
+    const timer = window.setTimeout(() => {
+      void checkAuth();
+    }, 0);
+
+    return () => {
+      window.clearTimeout(timer);
+    };
   }, [checkAuth]);
 
   // Listen for auth errors from API calls (401 responses)

From fd141c45a8acaa3dd88a83f83059de584e4576a8 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:45:00 -0400
Subject: [PATCH 12/19] Added dev/prod modes and set /auth/code as callback uri
 for entra

---
 app/auth/code/route.ts |  1 +
 lib/auth/config.ts     | 65 ++++++++++++++++++++++++++++++++++++------
 2 files changed, 57 insertions(+), 9 deletions(-)
 create mode 100644 app/auth/code/route.ts

diff --git a/app/auth/code/route.ts b/app/auth/code/route.ts
new file mode 100644
index 0000000..b6f73db
--- /dev/null
+++ b/app/auth/code/route.ts
@@ -0,0 +1 @@
+export { GET } from '@/app/api/auth/entra/callback/route';
diff --git a/lib/auth/config.ts b/lib/auth/config.ts
index b805fea..19c7ca8 100644
--- a/lib/auth/config.ts
+++ b/lib/auth/config.ts
@@ -51,6 +51,7 @@ export function entraUserScope(): string {
  * Throws at startup/first-use if required server env vars are missing.
  */
 export function assertAuthConfig(): void {
+  const isDevelopment = process.env.NODE_ENV === 'development';
   const missing: string[] = [];
   if (!TENANT_ID) missing.push('ENTRA_TENANT_ID');
   if (!CLIENT_ID) missing.push('ENTRA_CLIENT_ID');
@@ -67,6 +68,12 @@ export function assertAuthConfig(): void {
       '[auth/config] SESSION_SECRET must be at least 32 characters'
     );
   }
+
+  if (!isDevelopment && REDIRECT_ORIGIN_ALLOWLIST.length === 0 && !APP_BASE_URL) {
+    throw new Error(
+      '[auth/config] In non-development environments, configure APP_BASE_URL or ENTRA_REDIRECT_ORIGIN_ALLOWLIST'
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -83,10 +90,11 @@ export function assertAuthConfig(): void {
  */
 export function buildCallbackUrl(request: NextRequest): string {
   const origin = resolveOrigin(request);
-  return `${origin}/api/auth/entra/callback`;
+  return `${origin}/auth/code`;
 }
 
 function resolveOrigin(request: NextRequest): string {
+  const isDevelopment = process.env.NODE_ENV === 'development';
   const forwardedHost = request.headers.get('x-forwarded-host')?.split(',')[0]?.trim();
   const forwardedProtoRaw = request
     .headers.get('x-forwarded-proto')
@@ -98,6 +106,7 @@ function resolveOrigin(request: NextRequest): string {
       ? forwardedProtoRaw
       : 'https';
   const host = forwardedHost || request.headers.get('host')?.split(',')[0]?.trim();
+  let requestOrigin: string | null = null;
 
   if (host) {
     const requestProto = request.nextUrl.protocol?.replace(':', '').toLowerCase();
@@ -107,22 +116,60 @@ function resolveOrigin(request: NextRequest): string {
         : requestProto === 'http' || requestProto === 'https'
           ? requestProto
           : 'https';
-    const origin = `${proto}://${host}`;
+    requestOrigin = `${proto}://${host}`;
+
+    if (isDevelopment) {
+      // In development, allow request-derived origin unless an allowlist is set.
+      if (REDIRECT_ORIGIN_ALLOWLIST.length === 0) {
+        return requestOrigin;
+      }
 
-    // If allowlist is configured, validate
-    if (REDIRECT_ORIGIN_ALLOWLIST.length > 0) {
-      if (REDIRECT_ORIGIN_ALLOWLIST.includes(origin)) {
-        return origin;
+      if (REDIRECT_ORIGIN_ALLOWLIST.includes(requestOrigin)) {
+        return requestOrigin;
       }
       // Not in allowlist - fall through to APP_BASE_URL
-    } else {
-      return origin;
     }
   }
 
+  if (isDevelopment) {
+    if (APP_BASE_URL) {
+      return APP_BASE_URL;
+    }
+    return 'http://localhost:3000';
+  }
+
+  // Non-development hardening:
+  // - If allowlist exists, request-derived origin must be in allowlist.
+  // - If allowlist is empty, do not trust request-derived headers.
+  if (REDIRECT_ORIGIN_ALLOWLIST.length > 0) {
+    if (requestOrigin) {
+      if (REDIRECT_ORIGIN_ALLOWLIST.includes(requestOrigin)) {
+        return requestOrigin;
+      }
+      throw new Error(
+        `[auth/config] Derived redirect origin '${requestOrigin}' is not in ENTRA_REDIRECT_ORIGIN_ALLOWLIST`
+      );
+    }
+
+    if (APP_BASE_URL) {
+      if (REDIRECT_ORIGIN_ALLOWLIST.includes(APP_BASE_URL)) {
+        return APP_BASE_URL;
+      }
+      throw new Error(
+        `[auth/config] APP_BASE_URL '${APP_BASE_URL}' must be included in ENTRA_REDIRECT_ORIGIN_ALLOWLIST`
+      );
+    }
+
+    throw new Error(
+      '[auth/config] Unable to derive request origin and APP_BASE_URL is not configured'
+    );
+  }
+
   if (APP_BASE_URL) {
     return APP_BASE_URL;
   }
 
-  return 'http://localhost:3000';
+  throw new Error(
+    '[auth/config] In non-development environments, APP_BASE_URL is required when ENTRA_REDIRECT_ORIGIN_ALLOWLIST is empty'
+  );
 }

From 4cd841733dbf0b1c1b4ada9235bd364e91e292c1 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:48:06 -0400
Subject: [PATCH 13/19] Add assertAuthConfig to entra refresh route

---
 app/api/auth/entra/refresh/route.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
index a73e838..3e64b5d 100644
--- a/app/api/auth/entra/refresh/route.ts
+++ b/app/api/auth/entra/refresh/route.ts
@@ -1,11 +1,13 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { REFRESH_COOKIE } from '@/lib/auth/config';
+import { REFRESH_COOKIE, assertAuthConfig } from '@/lib/auth/config';
 import { decodeSessionToken, issueSessionTokens } from '@/lib/auth/jwt';
 import { setSessionCookies, clearSessionCookies } from '@/lib/auth/cookies';
 import { deleteTokens, getTokens, setTokens } from '@/lib/auth/token-store';
 import { isEntraTokenExpiring, refreshEntraAccessToken } from '@/lib/auth/entra';
 
 export async function POST(request: NextRequest) {
+  assertAuthConfig();
+
   const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
 
   if (!refreshCookie) {

From 998cc70c9534012eb32409e65090b7c30492a2ff Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 12:52:28 -0400
Subject: [PATCH 14/19] Copilot suggestion for hardening for Next.js Edge
 runtime

---
 app/api/auth/entra/callback/route.ts |  2 ++
 app/api/auth/entra/login/route.ts    |  2 ++
 lib/auth/oidc-flow.ts                | 28 ++++++++++++++++++++++++++--
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/app/api/auth/entra/callback/route.ts b/app/api/auth/entra/callback/route.ts
index 1d8f5fd..5681e79 100644
--- a/app/api/auth/entra/callback/route.ts
+++ b/app/api/auth/entra/callback/route.ts
@@ -6,6 +6,8 @@ import { setTokens } from '@/lib/auth/token-store';
 import { issueSessionTokens } from '@/lib/auth/jwt';
 import { setSessionCookies } from '@/lib/auth/cookies';
 
+export const runtime = 'nodejs';
+
 export async function GET(request: NextRequest) {
   assertAuthConfig();
 
diff --git a/app/api/auth/entra/login/route.ts b/app/api/auth/entra/login/route.ts
index c96d9e4..b72ee0b 100644
--- a/app/api/auth/entra/login/route.ts
+++ b/app/api/auth/entra/login/route.ts
@@ -12,6 +12,8 @@ import {
   setOidcFlowCookie,
 } from '@/lib/auth/oidc-flow';
 
+export const runtime = 'nodejs';
+
 export async function GET(request: NextRequest) {
   assertAuthConfig();
 
diff --git a/lib/auth/oidc-flow.ts b/lib/auth/oidc-flow.ts
index a7b1b04..3d20a79 100644
--- a/lib/auth/oidc-flow.ts
+++ b/lib/auth/oidc-flow.ts
@@ -32,9 +32,33 @@ function generateRandomString(length: number): string {
   return base64UrlEncode(bytes);
 }
 
+const BASE64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
 function base64UrlEncode(data: Uint8Array): string {
-  const base64 = Buffer.from(data).toString('base64');
-  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  let result = '';
+  let i = 0;
+
+  // Encode full 3-byte chunks into 4 base64url chars
+  for (; i + 2 < data.length; i += 3) {
+    const n = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];
+    result += BASE64URL_ALPHABET[(n >> 18) & 63];
+    result += BASE64URL_ALPHABET[(n >> 12) & 63];
+    result += BASE64URL_ALPHABET[(n >> 6) & 63];
+    result += BASE64URL_ALPHABET[n & 63];
+  }
+
+  // Encode remaining 1-2 bytes (without padding)
+  if (i < data.length) {
+    const remaining = data.length - i;
+    const n = (data[i] << 16) | (remaining === 2 ? data[i + 1] << 8 : 0);
+    result += BASE64URL_ALPHABET[(n >> 18) & 63];
+    result += BASE64URL_ALPHABET[(n >> 12) & 63];
+    if (remaining === 2) {
+      result += BASE64URL_ALPHABET[(n >> 6) & 63];
+    }
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------------------

From 37f47542030f6ee9fad6c7e698c2c78573951bbf Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 13:52:06 -0400
Subject: [PATCH 15/19] Added sqlite database to track sessions and store
 tokens

---
 README.md                            |  19 +
 app/api/auth/entra/callback/route.ts |  10 +-
 app/api/auth/entra/logout/route.ts   |  11 +-
 app/api/auth/entra/refresh/route.ts  |  21 +-
 app/api/auth/session/route.ts        |  16 +-
 app/api/tiled/[...path]/route.ts     |   8 +-
 app/api/ws/[...path]/route.ts        |  13 +-
 lib/auth/cookies.ts                  |   3 +
 lib/auth/jwt.ts                      |  24 +-
 lib/auth/obo.ts                      |  24 +-
 lib/auth/token-store.ts              | 162 +++++-
 lib/db/client.ts                     |  69 +++
 next.config.ts                       |   1 +
 package-lock.json                    | 746 ++++++++++++++++++++++++++-
 package.json                         |   4 +
 scripts/db-migrate.mjs               |  89 ++++
 16 files changed, 1162 insertions(+), 58 deletions(-)
 create mode 100644 lib/db/client.ts
 create mode 100644 scripts/db-migrate.mjs

diff --git a/README.md b/README.md
index 8670258..4bc8831 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,25 @@ npm run build
 npm start
 ```
 
+## Database Setup
+
+The app uses a single `DATABASE_URL` for persistence. Supported values:
+
+- `file:./data/app.sqlite` (default fallback)
+- `postgres://...` or `postgresql://...`
+
+Initialize schema during deploy:
+
+```bash
+npm run db:migrate
+```
+
+Notes:
+
+- For SQLite, the DB file and parent directory are created automatically if missing.
+- The app also bootstraps the `entra_credentials` table at runtime if not present.
+- Running `npm run db:migrate` is still recommended in deploy automation for fail-fast startup.
+
 ## WebSocket Events
 
 The dashboard listens for `container-child-created` events:
diff --git a/app/api/auth/entra/callback/route.ts b/app/api/auth/entra/callback/route.ts
index 5681e79..4a13cda 100644
--- a/app/api/auth/entra/callback/route.ts
+++ b/app/api/auth/entra/callback/route.ts
@@ -3,7 +3,7 @@ import { assertAuthConfig, buildCallbackUrl } from '@/lib/auth/config';
 import { validateAndConsumeOidcFlow, clearOidcFlowCookie } from '@/lib/auth/oidc-flow';
 import { exchangeCodeForUser } from '@/lib/auth/entra';
 import { setTokens } from '@/lib/auth/token-store';
-import { issueSessionTokens } from '@/lib/auth/jwt';
+import { generateSessionId, issueSessionTokens } from '@/lib/auth/jwt';
 import { setSessionCookies } from '@/lib/auth/cookies';
 
 export const runtime = 'nodejs';
@@ -46,15 +46,17 @@ export async function GET(request: NextRequest) {
     const { username, displayName, accessToken, refreshToken } =
       await exchangeCodeForUser(code, redirectUri, codeVerifier, nonce);
 
-    // Store Entra tokens in-memory
-    setTokens(username, {
+    const sessionId = generateSessionId();
+
+    // Store Entra tokens for this app session
+    await setTokens(username, sessionId, {
       entraAccessToken: accessToken,
       entraRefreshToken: refreshToken,
       storedAt: Date.now(),
     });
 
     // Issue app-level session tokens
-    const sessionTokens = await issueSessionTokens(username, displayName);
+    const sessionTokens = await issueSessionTokens(username, displayName, sessionId);
 
     // Redirect to app root with session cookies set
     setSessionCookies(response, sessionTokens.accessToken, sessionTokens.refreshToken);
diff --git a/app/api/auth/entra/logout/route.ts b/app/api/auth/entra/logout/route.ts
index c64e872..8fb40ec 100644
--- a/app/api/auth/entra/logout/route.ts
+++ b/app/api/auth/entra/logout/route.ts
@@ -3,10 +3,11 @@ import { ACCESS_COOKIE, REFRESH_COOKIE } from '@/lib/auth/config';
 import { decodeSessionToken } from '@/lib/auth/jwt';
 import { clearSessionCookies } from '@/lib/auth/cookies';
 import { deleteTokens } from '@/lib/auth/token-store';
-import { clearOboCache } from '@/lib/auth/obo';
+import { clearOboCacheForSession } from '@/lib/auth/obo';
 
 export async function POST(request: NextRequest) {
   let username: string | null = null;
+  let sessionId: string | null = null;
 
   // Try to get username from access cookie first, then refresh cookie
   const accessCookie = request.cookies.get(ACCESS_COOKIE)?.value;
@@ -14,6 +15,7 @@ export async function POST(request: NextRequest) {
     try {
       const payload = await decodeSessionToken(accessCookie, 'access');
       username = payload.sub;
+      sessionId = payload.sid || null;
     } catch {
       // Ignore -- try refresh cookie
     }
@@ -25,6 +27,7 @@ export async function POST(request: NextRequest) {
       try {
         const payload = await decodeSessionToken(refreshCookie, 'refresh');
         username = payload.sub;
+        sessionId = payload.sid || null;
       } catch {
         // Ignore
       }
@@ -32,9 +35,9 @@ export async function POST(request: NextRequest) {
   }
 
   // Clean up server-side state
-  if (username) {
-    deleteTokens(username);
-    clearOboCache(username);
+  if (username && sessionId) {
+    await deleteTokens(username, sessionId);
+    clearOboCacheForSession(username, sessionId);
   }
 
   // Clear cookies
diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
index 3e64b5d..36e6456 100644
--- a/app/api/auth/entra/refresh/route.ts
+++ b/app/api/auth/entra/refresh/route.ts
@@ -16,11 +16,22 @@ export async function POST(request: NextRequest) {
 
   let username: string;
   let displayName: string;
+  let sessionId: string;
 
   try {
     const payload = await decodeSessionToken(refreshCookie, 'refresh');
     username = payload.sub;
     displayName = payload.name || username;
+    sessionId = payload.sid || '';
+
+    if (!sessionId) {
+      const response = NextResponse.json(
+        { error: 'invalid session token' },
+        { status: 401 }
+      );
+      clearSessionCookies(response);
+      return response;
+    }
   } catch {
     const response = NextResponse.json({ error: 'invalid refresh token' }, { status: 401 });
     clearSessionCookies(response);
@@ -28,7 +39,7 @@ export async function POST(request: NextRequest) {
   }
 
   // Try to refresh the underlying Entra token
-  const entry = getTokens(username);
+  const entry = await getTokens(username, sessionId);
   if (!entry) {
     const response = NextResponse.json({ error: 'missing entra credentials' }, { status: 401 });
     clearSessionCookies(response);
@@ -38,7 +49,7 @@ export async function POST(request: NextRequest) {
   if (entry.entraRefreshToken) {
     try {
       const refreshed = await refreshEntraAccessToken(entry.entraRefreshToken);
-      setTokens(username, {
+      await setTokens(username, sessionId, {
         entraAccessToken: refreshed.accessToken,
         entraRefreshToken: refreshed.refreshToken,
         storedAt: Date.now(),
@@ -46,7 +57,7 @@ export async function POST(request: NextRequest) {
     } catch (err) {
       console.error('[Entra Refresh] Failed:', err instanceof Error ? err.message : err);
       // Clear stored tokens on refresh failure
-      deleteTokens(username);
+      await deleteTokens(username, sessionId);
       const response = NextResponse.json(
         { error: 'entra refresh failed' },
         { status: 401 }
@@ -56,7 +67,7 @@ export async function POST(request: NextRequest) {
     }
   } else if (isEntraTokenExpiring(entry.entraAccessToken)) {
     // No refresh token available and the access token is expiring/expired.
-    deleteTokens(username);
+    await deleteTokens(username, sessionId);
     const response = NextResponse.json(
       { error: 'entra refresh token missing; re-authentication required' },
       { status: 401 }
@@ -66,7 +77,7 @@ export async function POST(request: NextRequest) {
   }
 
   // Issue new session tokens
-  const newTokens = await issueSessionTokens(username, displayName);
+  const newTokens = await issueSessionTokens(username, displayName, sessionId);
   const response = NextResponse.json({ status: 'ok' });
   setSessionCookies(response, newTokens.accessToken, newTokens.refreshToken);
 
diff --git a/app/api/auth/session/route.ts b/app/api/auth/session/route.ts
index 5fee437..c4f6571 100644
--- a/app/api/auth/session/route.ts
+++ b/app/api/auth/session/route.ts
@@ -11,8 +11,14 @@ export async function GET(request: NextRequest) {
     return NextResponse.json({ error: 'not authenticated' }, { status: 401 });
   }
 
+  if (!session.sessionId) {
+    const response = NextResponse.json({ error: 'not authenticated' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
+  }
+
   // Ensure server-side Entra credentials still exist
-  const entry = getTokens(session.username);
+  const entry = await getTokens(session.username, session.sessionId);
   if (!entry) {
     const response = NextResponse.json({ error: 'not authenticated' }, { status: 401 });
     clearSessionCookies(response);
@@ -21,7 +27,7 @@ export async function GET(request: NextRequest) {
 
   // If Entra access is expiring and cannot be refreshed, force re-authentication
   if (!entry.entraRefreshToken && isEntraTokenExpiring(entry.entraAccessToken)) {
-    deleteTokens(session.username);
+    await deleteTokens(session.username, session.sessionId);
     const response = NextResponse.json({ error: 'not authenticated' }, { status: 401 });
     clearSessionCookies(response);
     return response;
@@ -37,7 +43,11 @@ export async function GET(request: NextRequest) {
   }
 
   // Access expired but refresh is valid -- reissue session tokens
-  const newTokens = await issueSessionTokens(session.username, session.displayName);
+  const newTokens = await issueSessionTokens(
+    session.username,
+    session.displayName,
+    session.sessionId
+  );
   const response = NextResponse.json({
     username: session.username,
     display_name: session.displayName,
diff --git a/app/api/tiled/[...path]/route.ts b/app/api/tiled/[...path]/route.ts
index 27f360b..cca59f4 100644
--- a/app/api/tiled/[...path]/route.ts
+++ b/app/api/tiled/[...path]/route.ts
@@ -22,8 +22,12 @@ export async function GET(
     if (sessionCookie) {
       try {
         const payload = await decodeSessionToken(sessionCookie, 'access');
-        const tiledToken = await getOboTokenForUser(payload.sub);
-        authHeader = `Bearer ${tiledToken}`;
+        if (payload.sid) {
+          const tiledToken = await getOboTokenForUser(payload.sub, payload.sid);
+          authHeader = `Bearer ${tiledToken}`;
+        } else {
+          authHeader = request.headers.get('Authorization');
+        }
       } catch {
         // Cookie invalid/expired - fall through to header-based auth
         authHeader = request.headers.get('Authorization');
diff --git a/app/api/ws/[...path]/route.ts b/app/api/ws/[...path]/route.ts
index c288aa8..edf44bb 100644
--- a/app/api/ws/[...path]/route.ts
+++ b/app/api/ws/[...path]/route.ts
@@ -65,8 +65,7 @@ async function revokeApiKey(accessToken: string, firstEight: string): Promise<vo
 
 export function SOCKET(
   client: import('ws').WebSocket,
-  request: import('http').IncomingMessage,
-  server: import('ws').WebSocketServer
+  request: import('http').IncomingMessage
 ) {
   const url = new URL(request.url || '', `http://${request.headers.host}`);
 
@@ -97,7 +96,10 @@ export function SOCKET(
         if (accessCookieMatch) {
           const accessCookieValue = decodeURIComponent(accessCookieMatch[1]);
           const accessPayload = await decodeSessionToken(accessCookieValue, 'access');
-          return await getOboTokenForUser(accessPayload.sub);
+          if (accessPayload.sid) {
+            return await getOboTokenForUser(accessPayload.sub, accessPayload.sid);
+          }
+          return null;
         }
       } catch {
         // Access cookie invalid/expired -- try refresh cookie below
@@ -107,7 +109,10 @@ export function SOCKET(
         if (refreshCookieMatch) {
           const refreshCookieValue = decodeURIComponent(refreshCookieMatch[1]);
           const refreshPayload = await decodeSessionToken(refreshCookieValue, 'refresh');
-          return await getOboTokenForUser(refreshPayload.sub);
+          if (refreshPayload.sid) {
+            return await getOboTokenForUser(refreshPayload.sub, refreshPayload.sid);
+          }
+          return null;
         }
       } catch {
         return null;
diff --git a/lib/auth/cookies.ts b/lib/auth/cookies.ts
index 59d5c01..db1e9db 100644
--- a/lib/auth/cookies.ts
+++ b/lib/auth/cookies.ts
@@ -56,6 +56,7 @@ export async function getSessionFromRequest(
 ): Promise<{
   username: string;
   displayName: string;
+  sessionId: string | null;
   source: 'access' | 'refresh';
 } | null> {
   // Try access token first
@@ -66,6 +67,7 @@ export async function getSessionFromRequest(
       return {
         username: payload.sub,
         displayName: payload.name || payload.sub,
+        sessionId: payload.sid || null,
         source: 'access',
       };
     } catch {
@@ -81,6 +83,7 @@ export async function getSessionFromRequest(
       return {
         username: payload.sub,
         displayName: payload.name || payload.sub,
+        sessionId: payload.sid || null,
         source: 'refresh',
       };
     } catch {
diff --git a/lib/auth/jwt.ts b/lib/auth/jwt.ts
index e17ce89..cc0283c 100644
--- a/lib/auth/jwt.ts
+++ b/lib/auth/jwt.ts
@@ -13,9 +13,17 @@ export interface SessionPayload {
   sub: string; // username (Entra OID)
   name: string; // display name
   type: 'access' | 'refresh';
+  sid?: string; // logical session id (required for new tokens)
   exp: number;
 }
 
+interface SessionTokenClaims {
+  sub: string;
+  name: string;
+  type: SessionPayload['type'];
+  sid: string;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -33,7 +41,7 @@ function getSecretKey(): Uint8Array {
  * Mirrors: FastAPI app/utils/auth.py create_token()
  */
 export async function createSessionToken(
-  payload: { sub: string; name: string; type: SessionPayload['type'] },
+  payload: SessionTokenClaims,
   lifetime: number
 ): Promise<string> {
   const secret = getSecretKey();
@@ -66,20 +74,28 @@ export async function decodeSessionToken(
   return payload as unknown as SessionPayload;
 }
 
+/**
+ * Generate a session id shared across access/refresh tokens.
+ */
+export function generateSessionId(): string {
+  return crypto.randomUUID();
+}
+
 /**
  * Issue a pair of session tokens (access + refresh).
  * Mirrors: FastAPI app/utils/auth.py issue_session_tokens()
  */
 export async function issueSessionTokens(
   username: string,
-  displayName: string
+  displayName: string,
+  sessionId: string
 ): Promise<{ accessToken: string; refreshToken: string }> {
   const accessToken = await createSessionToken(
-    { sub: username, name: displayName, type: 'access' },
+    { sub: username, name: displayName, type: 'access', sid: sessionId },
     ACCESS_TOKEN_LIFETIME
   );
   const refreshToken = await createSessionToken(
-    { sub: username, name: displayName, type: 'refresh' },
+    { sub: username, name: displayName, type: 'refresh', sid: sessionId },
     REFRESH_TOKEN_LIFETIME
   );
   return { accessToken, refreshToken };
diff --git a/lib/auth/obo.ts b/lib/auth/obo.ts
index 0bc0276..8942ce5 100644
--- a/lib/auth/obo.ts
+++ b/lib/auth/obo.ts
@@ -78,9 +78,12 @@ async function exchangeTokenObo(
  * 4. Cache the result
  * 5. Return the token
  */
-export async function getOboTokenForUser(username: string): Promise<string> {
+export async function getOboTokenForUser(
+  username: string,
+  sessionId: string
+): Promise<string> {
   const cache = getOboCache();
-  const cacheKey = `${username}:${TILED_SCOPE}`;
+  const cacheKey = `${username}:${sessionId}:${TILED_SCOPE}`;
 
   const cached = cache.get(cacheKey);
   if (cached && Date.now() < cached.expiresAt - OBO_CACHE_BUFFER_MS) {
@@ -88,7 +91,7 @@ export async function getOboTokenForUser(username: string): Promise<string> {
   }
 
   // Get a fresh Entra token for this user
-  const entraToken = await getFreshEntraToken(username);
+  const entraToken = await getFreshEntraToken(username, sessionId);
 
   // Exchange for Tiled token
   const oboResult = await exchangeTokenObo(entraToken);
@@ -107,6 +110,19 @@ export async function getOboTokenForUser(username: string): Promise<string> {
  */
 export function clearOboCache(username: string): void {
   const cache = getOboCache();
-  const cacheKey = `${username}:${TILED_SCOPE}`;
+  const cacheKey = `${username}:`;
+  for (const key of cache.keys()) {
+    if (key.startsWith(cacheKey)) {
+      cache.delete(key);
+    }
+  }
+}
+
+/**
+ * Clear a user's OBO cache entry for a specific session.
+ */
+export function clearOboCacheForSession(username: string, sessionId: string): void {
+  const cache = getOboCache();
+  const cacheKey = `${username}:${sessionId}:${TILED_SCOPE}`;
   cache.delete(cacheKey);
 }
diff --git a/lib/auth/token-store.ts b/lib/auth/token-store.ts
index 57a85c3..37b17c2 100644
--- a/lib/auth/token-store.ts
+++ b/lib/auth/token-store.ts
@@ -1,4 +1,5 @@
 import { isEntraTokenExpiring, refreshEntraAccessToken } from './entra';
+import { getDbClient } from '@/lib/db/client';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -11,33 +12,153 @@ export interface EntraTokenEntry {
 }
 
 // ---------------------------------------------------------------------------
-// In-memory store (survives hot-reload in dev via globalThis)
+// Persistent store schema
 // ---------------------------------------------------------------------------
 
-const globalKey = '__entraTokenStore';
+const TABLE_NAME = 'entra_credentials';
+const initKey = '__entraTokenStoreInit';
+const cleanupIntervalMs = 60_000;
+const lastCleanupKey = '__entraTokenStoreLastCleanup';
 
-function getStore(): Map<string, EntraTokenEntry> {
+function maxAgeSeconds(): number {
+  const raw = Number(process.env.ENTRA_CREDENTIALS_MAX_AGE_SECONDS ?? 7 * 24 * 60 * 60);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 7 * 24 * 60 * 60;
+}
+
+function maxRows(): number {
+  const raw = Number(process.env.ENTRA_CREDENTIALS_MAX_ROWS ?? 10_000);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 10_000;
+}
+
+async function ensureSchema(): Promise<void> {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[initKey]) {
+    g[initKey] = (async () => {
+      const db = getDbClient();
+      const exists = await db.schema.hasTable(TABLE_NAME);
+      if (!exists) {
+        await db.schema.createTable(TABLE_NAME, (table) => {
+          table.string('username').notNullable();
+          table.string('session_id').notNullable();
+          table.text('entra_access_token').notNullable();
+          table.text('entra_refresh_token').nullable();
+          table.bigInteger('stored_at').notNullable();
+          table.bigInteger('updated_at').notNullable();
+          table.bigInteger('last_used_at').notNullable();
+          table.primary(['username', 'session_id']);
+          table.index(['updated_at']);
+          table.index(['last_used_at']);
+        });
+      }
+    })();
+  }
+  await g[initKey];
+}
+
+async function runCleanupIfNeeded(): Promise<void> {
   const g = globalThis as Record<string, unknown>;
-  if (!g[globalKey]) {
-    g[globalKey] = new Map<string, EntraTokenEntry>();
+  const now = Date.now();
+  const lastRun = (g[lastCleanupKey] as number | undefined) ?? 0;
+  if (now - lastRun < cleanupIntervalMs) {
+    return;
+  }
+
+  g[lastCleanupKey] = now;
+  const db = getDbClient();
+
+  // TTL eviction
+  const cutoff = now - maxAgeSeconds() * 1000;
+  await db(TABLE_NAME)
+    .where('updated_at', '<', cutoff)
+    .delete();
+
+  // Size eviction
+  const [{ count }] = await db(TABLE_NAME).count<{ count: string | number }[]>({ count: '*' });
+  const totalCount = Number(count);
+  const limit = maxRows();
+  if (!Number.isFinite(totalCount) || totalCount <= limit) {
+    return;
+  }
+
+  const toDelete = totalCount - limit;
+  const rows = await db(TABLE_NAME)
+    .select('username', 'session_id')
+    .orderBy('updated_at', 'asc')
+    .limit(toDelete);
+
+  if (rows.length > 0) {
+    await db(TABLE_NAME)
+      .whereIn(
+        ['username', 'session_id'],
+        rows.map((row) => [row.username as string, row.session_id as string])
+      )
+      .delete();
   }
-  return g[globalKey] as Map<string, EntraTokenEntry>;
 }
 
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
-export function getTokens(username: string): EntraTokenEntry | null {
-  return getStore().get(username) ?? null;
+export async function getTokens(
+  username: string,
+  sessionId: string
+): Promise<EntraTokenEntry | null> {
+  await ensureSchema();
+  const db = getDbClient();
+  const row = await db(TABLE_NAME)
+    .select('entra_access_token', 'entra_refresh_token', 'stored_at')
+    .where({ username, session_id: sessionId })
+    .first();
+
+  if (!row) {
+    return null;
+  }
+
+  return {
+    entraAccessToken: row.entra_access_token as string,
+    entraRefreshToken: (row.entra_refresh_token as string | null) ?? null,
+    storedAt: Number(row.stored_at),
+  };
 }
 
-export function setTokens(username: string, entry: EntraTokenEntry): void {
-  getStore().set(username, entry);
+export async function setTokens(
+  username: string,
+  sessionId: string,
+  entry: EntraTokenEntry
+): Promise<void> {
+  await ensureSchema();
+  const db = getDbClient();
+  const now = Date.now();
+
+  await db(TABLE_NAME)
+    .insert({
+      username,
+      session_id: sessionId,
+      entra_access_token: entry.entraAccessToken,
+      entra_refresh_token: entry.entraRefreshToken,
+      stored_at: entry.storedAt,
+      updated_at: now,
+      last_used_at: now,
+    })
+    .onConflict(['username', 'session_id'])
+    .merge({
+      entra_access_token: entry.entraAccessToken,
+      entra_refresh_token: entry.entraRefreshToken,
+      stored_at: entry.storedAt,
+      updated_at: now,
+      last_used_at: now,
+    });
+
+  await runCleanupIfNeeded();
 }
 
-export function deleteTokens(username: string): void {
-  getStore().delete(username);
+export async function deleteTokens(username: string, sessionId: string): Promise<void> {
+  await ensureSchema();
+  const db = getDbClient();
+  await db(TABLE_NAME)
+    .where({ username, session_id: sessionId })
+    .delete();
 }
 
 /**
@@ -47,19 +168,26 @@ export function deleteTokens(username: string): void {
  *
  * Mirrors: FastAPI app/utils/auth.py get_fresh_entra_access_token()
  */
-export async function getFreshEntraToken(username: string): Promise<string> {
-  const entry = getTokens(username);
+export async function getFreshEntraToken(
+  username: string,
+  sessionId: string
+): Promise<string> {
+  const entry = await getTokens(username, sessionId);
   if (!entry) {
     throw new Error('No Entra credentials stored for user');
   }
 
   if (!isEntraTokenExpiring(entry.entraAccessToken)) {
+    const db = getDbClient();
+    await db(TABLE_NAME)
+      .where({ username, session_id: sessionId })
+      .update({ last_used_at: Date.now() });
     return entry.entraAccessToken;
   }
 
   // Token is expiring -- attempt refresh
   if (!entry.entraRefreshToken) {
-    deleteTokens(username);
+    await deleteTokens(username, sessionId);
     throw new Error('Entra refresh token missing; re-authentication required');
   }
 
@@ -70,10 +198,10 @@ export async function getFreshEntraToken(username: string): Promise<string> {
       entraRefreshToken: refreshed.refreshToken,
       storedAt: Date.now(),
     };
-    setTokens(username, updatedEntry);
+    await setTokens(username, sessionId, updatedEntry);
     return refreshed.accessToken;
   } catch (err) {
-    deleteTokens(username);
+    await deleteTokens(username, sessionId);
     throw new Error(
       `Entra token refresh failed: ${err instanceof Error ? err.message : String(err)}`
     );
diff --git a/lib/db/client.ts b/lib/db/client.ts
new file mode 100644
index 0000000..298423c
--- /dev/null
+++ b/lib/db/client.ts
@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import knex, { Knex } from 'knex';
+
+const globalKey = '__appDbClient';
+
+function getDatabaseUrl(): string {
+  return process.env.DATABASE_URL?.trim() || 'file:./data/app.sqlite';
+}
+
+function createSqliteClient(databaseUrl: string): Knex {
+  const raw = databaseUrl.slice('file:'.length);
+  const filePath = raw
+    ? normalizeSqlitePath(raw)
+    : path.resolve(/*turbopackIgnore: true*/ process.cwd(), 'data/app.sqlite');
+
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  return knex({
+    client: 'better-sqlite3',
+    connection: {
+      filename: filePath,
+    },
+    useNullAsDefault: true,
+  });
+}
+
+function normalizeSqlitePath(rawPath: string): string {
+  if (rawPath.startsWith('//')) {
+    // file:// style absolute paths become //abs/path after stripping `file:`
+    return path.normalize(rawPath);
+  }
+  if (path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  return path.resolve(/*turbopackIgnore: true*/ process.cwd(), rawPath);
+}
+
+function createDbClient(): Knex {
+  const databaseUrl = getDatabaseUrl();
+
+  if (databaseUrl.startsWith('postgres://') || databaseUrl.startsWith('postgresql://')) {
+    return knex({
+      client: 'pg',
+      connection: databaseUrl,
+      pool: {
+        min: 0,
+        max: 10,
+      },
+    });
+  }
+
+  if (databaseUrl.startsWith('file:')) {
+    return createSqliteClient(databaseUrl);
+  }
+
+  throw new Error(
+    `[db] Unsupported DATABASE_URL scheme. Expected postgres://, postgresql://, or file:, got: ${databaseUrl}`
+  );
+}
+
+export function getDbClient(): Knex {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[globalKey]) {
+    g[globalKey] = createDbClient();
+  }
+  return g[globalKey] as Knex;
+}
diff --git a/next.config.ts b/next.config.ts
index 0ed66da..bec134c 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -1,6 +1,7 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  serverExternalPackages: ['knex', 'pg', 'better-sqlite3'],
   images: {
     remotePatterns: [
       {
diff --git a/package-lock.json b/package-lock.json
index 6812188..ff24ae3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13,13 +13,16 @@
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
         "@niivue/niivue": "^0.68.2",
+        "better-sqlite3": "^12.10.0",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "framer-motion": "^12.34.3",
         "jose": "^6.2.3",
+        "knex": "^3.2.10",
         "lucide-react": "^0.575.0",
         "next": "^16.2.4",
         "next-ws": "^2.1.17",
+        "pg": "^8.21.0",
         "radix-ui": "^1.4.3",
         "react": "19.2.3",
         "react-dom": "19.2.3",
@@ -5162,6 +5165,26 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/baseline-browser-mapping": {
       "version": "2.10.0",
       "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.0.tgz",
@@ -5174,6 +5197,40 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/better-sqlite3": {
+      "version": "12.10.0",
+      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.10.0.tgz",
+      "integrity": "sha512-CyzaZRQKyHkB2ZInfTTl2nvT33EbDpjkLEbE8/Zck3Ll6O0qqvuGdrJ45HgtH+HykRg88ITY3AdreBGN70aBSQ==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "bindings": "^1.5.0",
+        "prebuild-install": "^7.1.1"
+      },
+      "engines": {
+        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
+      }
+    },
+    "node_modules/bindings": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
+      "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
+      "license": "MIT",
+      "dependencies": {
+        "file-uri-to-path": "1.0.0"
+      }
+    },
+    "node_modules/bl": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
+      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer": "^5.5.0",
+        "inherits": "^2.0.4",
+        "readable-stream": "^3.4.0"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -5254,6 +5311,30 @@
         "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
       }
     },
+    "node_modules/buffer": {
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
+      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "base64-js": "^1.3.1",
+        "ieee754": "^1.1.13"
+      }
+    },
     "node_modules/buffer-from": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz",
@@ -5383,6 +5464,12 @@
         "url": "https://github.com/chalk/chalk?sponsor=1"
       }
     },
+    "node_modules/chownr": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz",
+      "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==",
+      "license": "ISC"
+    },
     "node_modules/class-variance-authority": {
       "version": "0.7.1",
       "resolved": "https://registry.npmjs.org/class-variance-authority/-/class-variance-authority-0.7.1.tgz",
@@ -5568,6 +5655,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/colorette": {
+      "version": "2.0.19",
+      "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.19.tgz",
+      "integrity": "sha512-3tlv/dIP7FWvj3BsbHrGLJ6l/oKh1O3TcgBqMn+yyCagOxc23fyzDS6HypQbgxWbkpDnf52p1LuR4eWDQ/K9WQ==",
+      "license": "MIT"
+    },
     "node_modules/commander": {
       "version": "14.0.3",
       "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
@@ -5809,6 +5902,21 @@
         }
       }
     },
+    "node_modules/decompress-response": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
+      "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
+      "license": "MIT",
+      "dependencies": {
+        "mimic-response": "^3.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/dedent": {
       "version": "1.7.1",
       "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.7.1.tgz",
@@ -5824,6 +5932,15 @@
         }
       }
     },
+    "node_modules/deep-extend": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+      "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
     "node_modules/deep-is": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
@@ -5934,7 +6051,6 @@
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
       "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
-      "devOptional": true,
       "license": "Apache-2.0",
       "engines": {
         "node": ">=8"
@@ -6045,6 +6161,15 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
     "node_modules/enhanced-resolve": {
       "version": "5.20.0",
       "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.20.0.tgz",
@@ -6651,6 +6776,15 @@
         "url": "https://opencollective.com/eslint"
       }
     },
+    "node_modules/esm": {
+      "version": "3.2.25",
+      "resolved": "https://registry.npmjs.org/esm/-/esm-3.2.25.tgz",
+      "integrity": "sha512-U1suiZ2oDVWv4zPO56S0NcR5QriEahGtdN2OR6FiOG4WJvcjBVFB0qI4+eKoWFH483PKGuLuu6V8Z4T5g63UVA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/espree": {
       "version": "10.4.0",
       "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
@@ -6788,6 +6922,15 @@
         "url": "https://github.com/sindresorhus/execa?sponsor=1"
       }
     },
+    "node_modules/expand-template": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
+      "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==",
+      "license": "(MIT OR WTFPL)",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/express": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
@@ -6987,6 +7130,12 @@
         "node": ">=16.0.0"
       }
     },
+    "node_modules/file-uri-to-path": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
+      "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
+      "license": "MIT"
+    },
     "node_modules/fill-range": {
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
@@ -7157,6 +7306,12 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/fs-constants": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
+      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
+      "license": "MIT"
+    },
     "node_modules/fs-extra": {
       "version": "11.3.3",
       "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.3.tgz",
@@ -7176,7 +7331,6 @@
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
       "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
-      "dev": true,
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/ljharb"
@@ -7316,6 +7470,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/get-package-type": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/get-package-type/-/get-package-type-0.1.0.tgz",
+      "integrity": "sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/get-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
@@ -7378,6 +7541,18 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
+    "node_modules/getopts": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/getopts/-/getopts-2.3.0.tgz",
+      "integrity": "sha512-5eDf9fuSXwxBL6q5HX+dhDj+dslFGWzU5thZ9kNKUkcPtaPdatmUFKwHFrLb/uf/WpA4BHET+AX3Scl56cAjpA==",
+      "license": "MIT"
+    },
+    "node_modules/github-from-package": {
+      "version": "0.0.0",
+      "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
+      "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==",
+      "license": "MIT"
+    },
     "node_modules/gl-matrix": {
       "version": "3.4.4",
       "resolved": "https://registry.npmjs.org/gl-matrix/-/gl-matrix-3.4.4.tgz",
@@ -7541,7 +7716,6 @@
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
       "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "function-bind": "^1.1.2"
@@ -7645,6 +7819,26 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/ieee754": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
+      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/ignore": {
       "version": "5.3.2",
       "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
@@ -7685,7 +7879,12 @@
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
       "license": "ISC"
     },
     "node_modules/internal-slot": {
@@ -7703,6 +7902,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/interpret": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/interpret/-/interpret-2.2.0.tgz",
+      "integrity": "sha512-Ju0Bz/cEia55xDwUWEa8+olFpCiQoypjnQySseKtmjNrnps3P+xfpUmGr90T7yjlVJmOtybRvPXhKMbHr+fWnw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
     "node_modules/ip-address": {
       "version": "10.1.0",
       "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
@@ -7840,7 +8048,6 @@
       "version": "2.16.1",
       "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.16.1.tgz",
       "integrity": "sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "hasown": "^2.0.2"
@@ -8557,6 +8764,104 @@
         "node": ">=6"
       }
     },
+    "node_modules/knex": {
+      "version": "3.2.10",
+      "resolved": "https://registry.npmjs.org/knex/-/knex-3.2.10.tgz",
+      "integrity": "sha512-oypTHfrc9i72iyxaUQBKHOxhcr0xM65MPf6FpN02nimsftXwzXprIkLjfXdubvhbu4PMWLp023q8o8CYvHSuZw==",
+      "license": "MIT",
+      "dependencies": {
+        "colorette": "2.0.19",
+        "commander": "^10.0.0",
+        "debug": "4.3.4",
+        "escalade": "^3.1.1",
+        "esm": "^3.2.25",
+        "get-package-type": "^0.1.0",
+        "getopts": "2.3.0",
+        "interpret": "^2.2.0",
+        "lodash": "^4.18.1",
+        "pg-connection-string": "2.6.2",
+        "rechoir": "^0.8.0",
+        "resolve-from": "^5.0.0",
+        "tarn": "^3.0.2",
+        "tildify": "2.0.0"
+      },
+      "bin": {
+        "knex": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "peerDependencies": {
+        "pg-query-stream": "^4.14.0"
+      },
+      "peerDependenciesMeta": {
+        "better-sqlite3": {
+          "optional": true
+        },
+        "mysql": {
+          "optional": true
+        },
+        "mysql2": {
+          "optional": true
+        },
+        "pg": {
+          "optional": true
+        },
+        "pg-native": {
+          "optional": true
+        },
+        "pg-query-stream": {
+          "optional": true
+        },
+        "sqlite3": {
+          "optional": true
+        },
+        "tedious": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/knex/node_modules/commander": {
+      "version": "10.0.1",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-10.0.1.tgz",
+      "integrity": "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/knex/node_modules/debug": {
+      "version": "4.3.4",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz",
+      "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "2.1.2"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/knex/node_modules/ms": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+      "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+      "license": "MIT"
+    },
+    "node_modules/knex/node_modules/resolve-from": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz",
+      "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/language-subtag-registry": {
       "version": "0.3.23",
       "resolved": "https://registry.npmjs.org/language-subtag-registry/-/language-subtag-registry-0.3.23.tgz",
@@ -8875,6 +9180,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "license": "MIT"
+    },
     "node_modules/lodash.merge": {
       "version": "4.6.2",
       "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
@@ -9101,6 +9412,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/mimic-response": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
+      "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/minimatch": {
       "version": "3.1.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
@@ -9123,6 +9446,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/mkdirp-classic": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz",
+      "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==",
+      "license": "MIT"
+    },
     "node_modules/motion-dom": {
       "version": "12.34.3",
       "resolved": "https://registry.npmjs.org/motion-dom/-/motion-dom-12.34.3.tgz",
@@ -9231,6 +9560,12 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/napi-build-utils": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz",
+      "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==",
+      "license": "MIT"
+    },
     "node_modules/napi-postinstall": {
       "version": "0.3.4",
       "resolved": "https://registry.npmjs.org/napi-postinstall/-/napi-postinstall-0.3.4.tgz",
@@ -9541,6 +9876,30 @@
         "fflate": "^0.8.2"
       }
     },
+    "node_modules/node-abi": {
+      "version": "3.92.0",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.92.0.tgz",
+      "integrity": "sha512-KdHvFWZjEKDf0cakgFjebl371GPsISX2oZHcuyKqM7DtogIsHrqKeLTo8wBHxaXRAQlY2PsPlZmfo+9ZCxEREQ==",
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.3.5"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/node-abi/node_modules/semver": {
+      "version": "7.8.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz",
+      "integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/node-domexception": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz",
@@ -9795,7 +10154,6 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
       "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "wrappy": "1"
@@ -10052,7 +10410,6 @@
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz",
       "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/path-to-regexp": {
@@ -10062,6 +10419,101 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/pg": {
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/pg/-/pg-8.21.0.tgz",
+      "integrity": "sha512-AUP1EYJuHraQGsVoCQVIcM7TEJVGtDzxWtGFZd8rds9d+CCXlU5Js1rYgfLNvxy9iJrpHjGrRjoi/3BT9fRyiA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-connection-string": "^2.13.0",
+        "pg-pool": "^3.14.0",
+        "pg-protocol": "^1.14.0",
+        "pg-types": "2.2.0",
+        "pgpass": "1.0.5"
+      },
+      "engines": {
+        "node": ">= 16.0.0"
+      },
+      "optionalDependencies": {
+        "pg-cloudflare": "^1.4.0"
+      },
+      "peerDependencies": {
+        "pg-native": ">=3.0.1"
+      },
+      "peerDependenciesMeta": {
+        "pg-native": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/pg-cloudflare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.0.tgz",
+      "integrity": "sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/pg-connection-string": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.6.2.tgz",
+      "integrity": "sha512-ch6OwaeaPYcova4kKZ15sbJ2hKb/VP48ZD2gE7i1J+L4MspCtBMAx8nMgz7bksc7IojCIIWuEhHibSMFH8m8oA==",
+      "license": "MIT"
+    },
+    "node_modules/pg-int8": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
+      "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/pg-pool": {
+      "version": "3.14.0",
+      "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz",
+      "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "pg": ">=8.0"
+      }
+    },
+    "node_modules/pg-protocol": {
+      "version": "1.14.0",
+      "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.14.0.tgz",
+      "integrity": "sha512-n5taZ1kO3s9ngDTVxsEznOqCyToTgz0FLuPq0B33COy5pPpuWJpY3/2oRBVETuOgzdqRXfWpM9HIhp2LBBT1BA==",
+      "license": "MIT"
+    },
+    "node_modules/pg-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
+      "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-int8": "1.0.1",
+        "postgres-array": "~2.0.0",
+        "postgres-bytea": "~1.0.0",
+        "postgres-date": "~1.0.4",
+        "postgres-interval": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/pg/node_modules/pg-connection-string": {
+      "version": "2.13.0",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.13.0.tgz",
+      "integrity": "sha512-EMnU9E2fSULdsbErBbMaXJvFeD9B4+nPcM3f+4lsiCR0BHLPrLVjv3DbyM2hgQQviKJaTWIRRTjKjWlHg3p2ig==",
+      "license": "MIT"
+    },
+    "node_modules/pgpass": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz",
+      "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.1.0"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -10232,6 +10684,45 @@
         "node": ">=4"
       }
     },
+    "node_modules/postgres-array": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
+      "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postgres-bytea": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz",
+      "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-date": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
+      "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-interval": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
+      "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "xtend": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/powershell-utils": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/powershell-utils/-/powershell-utils-0.1.0.tgz",
@@ -10245,6 +10736,33 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/prebuild-install": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
+      "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==",
+      "deprecated": "No longer maintained. Please contact the author of the relevant native addon; alternatives are available.",
+      "license": "MIT",
+      "dependencies": {
+        "detect-libc": "^2.0.0",
+        "expand-template": "^2.0.3",
+        "github-from-package": "0.0.0",
+        "minimist": "^1.2.3",
+        "mkdirp-classic": "^0.5.3",
+        "napi-build-utils": "^2.0.0",
+        "node-abi": "^3.3.0",
+        "pump": "^3.0.0",
+        "rc": "^1.2.7",
+        "simple-get": "^4.0.0",
+        "tar-fs": "^2.0.0",
+        "tunnel-agent": "^0.6.0"
+      },
+      "bin": {
+        "prebuild-install": "bin.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/prelude-ls": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
@@ -10321,6 +10839,16 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/pump": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+      "license": "MIT",
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
     "node_modules/punycode": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
@@ -10471,6 +10999,30 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/rc": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
+      "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
+      "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
+      "dependencies": {
+        "deep-extend": "^0.6.0",
+        "ini": "~1.3.0",
+        "minimist": "^1.2.0",
+        "strip-json-comments": "~2.0.1"
+      },
+      "bin": {
+        "rc": "cli.js"
+      }
+    },
+    "node_modules/rc/node_modules/strip-json-comments": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
+      "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/react": {
       "version": "19.2.3",
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.3.tgz",
@@ -10568,6 +11120,20 @@
         }
       }
     },
+    "node_modules/readable-stream": {
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
+      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "^2.0.3",
+        "string_decoder": "^1.1.1",
+        "util-deprecate": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/recast": {
       "version": "0.23.11",
       "resolved": "https://registry.npmjs.org/recast/-/recast-0.23.11.tgz",
@@ -10584,6 +11150,18 @@
         "node": ">= 4"
       }
     },
+    "node_modules/rechoir": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.8.0.tgz",
+      "integrity": "sha512-/vxpCXddiX8NGfGO/mTafwjq4aFa/71pvamip0++IQk3zG8cbCj0fifNPrjjF1XMXUne91jL9OoxmdykoEtifQ==",
+      "license": "MIT",
+      "dependencies": {
+        "resolve": "^1.20.0"
+      },
+      "engines": {
+        "node": ">= 10.13.0"
+      }
+    },
     "node_modules/reference-spec-reader": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/reference-spec-reader/-/reference-spec-reader-0.2.0.tgz",
@@ -10658,7 +11236,6 @@
       "version": "1.22.11",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.11.tgz",
       "integrity": "sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "is-core-module": "^2.16.1",
@@ -10814,6 +11391,26 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/safe-push-apply": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/safe-push-apply/-/safe-push-apply-1.0.0.tgz",
@@ -11257,6 +11854,51 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/simple-concat": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
+      "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/simple-get": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz",
+      "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "decompress-response": "^6.0.0",
+        "once": "^1.3.1",
+        "simple-concat": "^1.0.0"
+      }
+    },
     "node_modules/sisteransi": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@@ -11292,6 +11934,15 @@
         "source-map": "^0.6.0"
       }
     },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
     "node_modules/stable-hash": {
       "version": "0.0.5",
       "resolved": "https://registry.npmjs.org/stable-hash/-/stable-hash-0.0.5.tgz",
@@ -11343,6 +11994,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/string_decoder": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
+      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.2.0"
+      }
+    },
     "node_modules/string-width": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
@@ -11591,7 +12251,6 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz",
       "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 0.4"
@@ -11644,6 +12303,52 @@
         "url": "https://opencollective.com/webpack"
       }
     },
+    "node_modules/tar-fs": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
+      "integrity": "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "chownr": "^1.1.1",
+        "mkdirp-classic": "^0.5.2",
+        "pump": "^3.0.0",
+        "tar-stream": "^2.1.4"
+      }
+    },
+    "node_modules/tar-stream": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
+      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "bl": "^4.0.3",
+        "end-of-stream": "^1.4.1",
+        "fs-constants": "^1.0.0",
+        "inherits": "^2.0.3",
+        "readable-stream": "^3.1.1"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/tarn": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/tarn/-/tarn-3.0.2.tgz",
+      "integrity": "sha512-51LAVKUSZSVfI05vjPESNc5vwqqZpbXCsU+/+wxlOrUjk2SnFTt97v9ZgQrD4YmxYW1Px6w2KjaDitCfkvgxMQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
+    "node_modules/tildify": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/tildify/-/tildify-2.0.0.tgz",
+      "integrity": "sha512-Cc+OraorugtXNfs50hU9KS369rFXCfgGLpfCfvlc+Ud5u6VWmUQsOAa9HbTvheQdYnrdJqqv1e5oIqXppMYnSw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/tiny-invariant": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz",
@@ -11827,6 +12532,18 @@
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
       "license": "0BSD"
     },
+    "node_modules/tunnel-agent": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
+      "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "safe-buffer": "^5.0.1"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/tw-animate-css": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/tw-animate-css/-/tw-animate-css-1.4.0.tgz",
@@ -12209,7 +12926,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
       "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/uzip-module": {
@@ -12427,7 +13143,6 @@
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/write-file-atomic": {
@@ -12481,6 +13196,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/xtend": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
+      "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.4"
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
diff --git a/package.json b/package.json
index 33f116d..26347b4 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "eslint",
+    "db:migrate": "node ./scripts/db-migrate.mjs",
     "postinstall": "next-ws-cli patch --yes || true"
   },
   "dependencies": {
@@ -14,13 +15,16 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@niivue/niivue": "^0.68.2",
+    "better-sqlite3": "^12.10.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "framer-motion": "^12.34.3",
     "jose": "^6.2.3",
+    "knex": "^3.2.10",
     "lucide-react": "^0.575.0",
     "next": "^16.2.4",
     "next-ws": "^2.1.17",
+    "pg": "^8.21.0",
     "radix-ui": "^1.4.3",
     "react": "19.2.3",
     "react-dom": "19.2.3",
diff --git a/scripts/db-migrate.mjs b/scripts/db-migrate.mjs
new file mode 100644
index 0000000..e050e2a
--- /dev/null
+++ b/scripts/db-migrate.mjs
@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import knex from 'knex';
+
+function getDatabaseUrl() {
+  return (process.env.DATABASE_URL || '').trim() || 'file:./data/app.sqlite';
+}
+
+function normalizeSqlitePath(rawPath) {
+  if (rawPath.startsWith('//')) {
+    return path.normalize(rawPath);
+  }
+  if (path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  return path.resolve(process.cwd(), rawPath);
+}
+
+function createSqliteClient(databaseUrl) {
+  const raw = databaseUrl.slice('file:'.length);
+  const filename = raw
+    ? normalizeSqlitePath(raw)
+    : path.resolve(process.cwd(), 'data/app.sqlite');
+
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+
+  return knex({
+    client: 'better-sqlite3',
+    connection: { filename },
+    useNullAsDefault: true,
+  });
+}
+
+function createDbClient() {
+  const databaseUrl = getDatabaseUrl();
+
+  if (databaseUrl.startsWith('postgres://') || databaseUrl.startsWith('postgresql://')) {
+    return knex({
+      client: 'pg',
+      connection: databaseUrl,
+      pool: { min: 0, max: 10 },
+    });
+  }
+
+  if (databaseUrl.startsWith('file:')) {
+    return createSqliteClient(databaseUrl);
+  }
+
+  throw new Error(
+    `[db:migrate] Unsupported DATABASE_URL scheme. Expected postgres://, postgresql://, or file:, got: ${databaseUrl}`
+  );
+}
+
+async function migrate(db) {
+  const tableName = 'entra_credentials';
+  const exists = await db.schema.hasTable(tableName);
+  if (!exists) {
+    await db.schema.createTable(tableName, (table) => {
+      table.string('username').notNullable();
+      table.string('session_id').notNullable();
+      table.text('entra_access_token').notNullable();
+      table.text('entra_refresh_token').nullable();
+      table.bigInteger('stored_at').notNullable();
+      table.bigInteger('updated_at').notNullable();
+      table.bigInteger('last_used_at').notNullable();
+      table.primary(['username', 'session_id']);
+      table.index(['updated_at']);
+      table.index(['last_used_at']);
+    });
+    console.log('[db:migrate] Created table:', tableName);
+  } else {
+    console.log('[db:migrate] Table already exists:', tableName);
+  }
+}
+
+async function main() {
+  const db = createDbClient();
+  try {
+    await migrate(db);
+    console.log('[db:migrate] Complete');
+  } finally {
+    await db.destroy();
+  }
+}
+
+main().catch((err) => {
+  console.error('[db:migrate] Failed:', err instanceof Error ? err.message : err);
+  process.exit(1);
+});

From 96f64d517a31de4dda6e65c1e37bd863ee25640b Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 14:15:57 -0400
Subject: [PATCH 16/19] Added server only guards to auth files

---
 lib/auth/config.ts      | 1 +
 lib/auth/cookies.ts     | 1 +
 lib/auth/entra.ts       | 1 +
 lib/auth/jwt.ts         | 1 +
 lib/auth/obo.ts         | 1 +
 lib/auth/oidc-flow.ts   | 1 +
 lib/auth/token-store.ts | 5 +++--
 lib/db/client.ts        | 1 +
 8 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/lib/auth/config.ts b/lib/auth/config.ts
index 19c7ca8..0e23fd5 100644
--- a/lib/auth/config.ts
+++ b/lib/auth/config.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { NextRequest } from 'next/server';
 
 // ---------------------------------------------------------------------------
diff --git a/lib/auth/cookies.ts b/lib/auth/cookies.ts
index db1e9db..43a0056 100644
--- a/lib/auth/cookies.ts
+++ b/lib/auth/cookies.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { NextRequest, NextResponse } from 'next/server';
 import { ACCESS_COOKIE, REFRESH_COOKIE, ACCESS_TOKEN_LIFETIME, REFRESH_TOKEN_LIFETIME } from './config';
 import { decodeSessionToken } from './jwt';
diff --git a/lib/auth/entra.ts b/lib/auth/entra.ts
index b96281c..55b84df 100644
--- a/lib/auth/entra.ts
+++ b/lib/auth/entra.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { createRemoteJWKSet, jwtVerify, decodeJwt } from 'jose';
 import {
   JWKS_URL,
diff --git a/lib/auth/jwt.ts b/lib/auth/jwt.ts
index cc0283c..dfef29c 100644
--- a/lib/auth/jwt.ts
+++ b/lib/auth/jwt.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { SignJWT, jwtVerify } from 'jose';
 import {
   SESSION_SECRET,
diff --git a/lib/auth/obo.ts b/lib/auth/obo.ts
index 8942ce5..95291a3 100644
--- a/lib/auth/obo.ts
+++ b/lib/auth/obo.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { TOKEN_ENDPOINT, CLIENT_ID, CLIENT_SECRET, TILED_SCOPE } from './config';
 import { getFreshEntraToken } from './token-store';
 
diff --git a/lib/auth/oidc-flow.ts b/lib/auth/oidc-flow.ts
index 3d20a79..52ce0f2 100644
--- a/lib/auth/oidc-flow.ts
+++ b/lib/auth/oidc-flow.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { NextRequest, NextResponse } from 'next/server';
 import { SignJWT, jwtVerify } from 'jose';
 import { SESSION_SECRET } from './config';
diff --git a/lib/auth/token-store.ts b/lib/auth/token-store.ts
index 37b17c2..8a39963 100644
--- a/lib/auth/token-store.ts
+++ b/lib/auth/token-store.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import { isEntraTokenExpiring, refreshEntraAccessToken } from './entra';
 import { getDbClient } from '@/lib/db/client';
 
@@ -69,7 +70,7 @@ async function runCleanupIfNeeded(): Promise<void> {
   // TTL eviction
   const cutoff = now - maxAgeSeconds() * 1000;
   await db(TABLE_NAME)
-    .where('updated_at', '<', cutoff)
+    .where('last_used_at', '<', cutoff)
     .delete();
 
   // Size eviction
@@ -83,7 +84,7 @@ async function runCleanupIfNeeded(): Promise<void> {
   const toDelete = totalCount - limit;
   const rows = await db(TABLE_NAME)
     .select('username', 'session_id')
-    .orderBy('updated_at', 'asc')
+    .orderBy('last_used_at', 'asc')
     .limit(toDelete);
 
   if (rows.length > 0) {
diff --git a/lib/db/client.ts b/lib/db/client.ts
index 298423c..f50e617 100644
--- a/lib/db/client.ts
+++ b/lib/db/client.ts
@@ -1,3 +1,4 @@
+import 'server-only';
 import fs from 'node:fs';
 import path from 'node:path';
 import knex, { Knex } from 'knex';

From a9276038eeffdfa3e0bc440fc0d43138706ef53e Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 15:10:02 -0400
Subject: [PATCH 17/19] Added copilot recommendations

---
 app/api/auth/entra/refresh/route.ts |  4 +-
 lib/auth/token-store.ts             | 52 +++++++++++++++-----
 lib/db/client.ts                    | 16 +------
 lib/db/url-utils.mjs                | 15 ++++++
 scripts/db-migrate.mjs              | 74 +++++++++++++++++------------
 5 files changed, 102 insertions(+), 59 deletions(-)
 create mode 100644 lib/db/url-utils.mjs

diff --git a/app/api/auth/entra/refresh/route.ts b/app/api/auth/entra/refresh/route.ts
index 36e6456..cbfc5df 100644
--- a/app/api/auth/entra/refresh/route.ts
+++ b/app/api/auth/entra/refresh/route.ts
@@ -11,7 +11,9 @@ export async function POST(request: NextRequest) {
   const refreshCookie = request.cookies.get(REFRESH_COOKIE)?.value;
 
   if (!refreshCookie) {
-    return NextResponse.json({ error: 'missing refresh token' }, { status: 401 });
+    const response = NextResponse.json({ error: 'missing refresh token' }, { status: 401 });
+    clearSessionCookies(response);
+    return response;
   }
 
   let username: string;
diff --git a/lib/auth/token-store.ts b/lib/auth/token-store.ts
index 8a39963..e456a38 100644
--- a/lib/auth/token-store.ts
+++ b/lib/auth/token-store.ts
@@ -31,6 +31,28 @@ function maxRows(): number {
   return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 10_000;
 }
 
+function isTableAlreadyExistsError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') {
+    return false;
+  }
+
+  const code = (err as { code?: unknown }).code;
+  if (code === '42P07') {
+    return true;
+  }
+
+  const message = (err as { message?: unknown }).message;
+  if (typeof message === 'string') {
+    const lower = message.toLowerCase();
+    return (
+      lower.includes('already exists') &&
+      (lower.includes('table') || lower.includes('relation'))
+    );
+  }
+
+  return false;
+}
+
 async function ensureSchema(): Promise<void> {
   const g = globalThis as Record<string, unknown>;
   if (!g[initKey]) {
@@ -38,18 +60,24 @@ async function ensureSchema(): Promise<void> {
       const db = getDbClient();
       const exists = await db.schema.hasTable(TABLE_NAME);
       if (!exists) {
-        await db.schema.createTable(TABLE_NAME, (table) => {
-          table.string('username').notNullable();
-          table.string('session_id').notNullable();
-          table.text('entra_access_token').notNullable();
-          table.text('entra_refresh_token').nullable();
-          table.bigInteger('stored_at').notNullable();
-          table.bigInteger('updated_at').notNullable();
-          table.bigInteger('last_used_at').notNullable();
-          table.primary(['username', 'session_id']);
-          table.index(['updated_at']);
-          table.index(['last_used_at']);
-        });
+        try {
+          await db.schema.createTable(TABLE_NAME, (table) => {
+            table.string('username').notNullable();
+            table.string('session_id').notNullable();
+            table.text('entra_access_token').notNullable();
+            table.text('entra_refresh_token').nullable();
+            table.bigInteger('stored_at').notNullable();
+            table.bigInteger('updated_at').notNullable();
+            table.bigInteger('last_used_at').notNullable();
+            table.primary(['username', 'session_id']);
+            table.index(['updated_at']);
+            table.index(['last_used_at']);
+          });
+        } catch (err) {
+          if (!isTableAlreadyExistsError(err)) {
+            throw err;
+          }
+        }
       }
     })();
   }
diff --git a/lib/db/client.ts b/lib/db/client.ts
index f50e617..3913955 100644
--- a/lib/db/client.ts
+++ b/lib/db/client.ts
@@ -2,13 +2,10 @@ import 'server-only';
 import fs from 'node:fs';
 import path from 'node:path';
 import knex, { Knex } from 'knex';
+import { getDatabaseUrl, normalizeSqlitePath } from './url-utils.mjs';
 
 const globalKey = '__appDbClient';
 
-function getDatabaseUrl(): string {
-  return process.env.DATABASE_URL?.trim() || 'file:./data/app.sqlite';
-}
-
 function createSqliteClient(databaseUrl: string): Knex {
   const raw = databaseUrl.slice('file:'.length);
   const filePath = raw
@@ -27,17 +24,6 @@ function createSqliteClient(databaseUrl: string): Knex {
   });
 }
 
-function normalizeSqlitePath(rawPath: string): string {
-  if (rawPath.startsWith('//')) {
-    // file:// style absolute paths become //abs/path after stripping `file:`
-    return path.normalize(rawPath);
-  }
-  if (path.isAbsolute(rawPath)) {
-    return rawPath;
-  }
-  return path.resolve(/*turbopackIgnore: true*/ process.cwd(), rawPath);
-}
-
 function createDbClient(): Knex {
   const databaseUrl = getDatabaseUrl();
 
diff --git a/lib/db/url-utils.mjs b/lib/db/url-utils.mjs
new file mode 100644
index 0000000..a1bdefe
--- /dev/null
+++ b/lib/db/url-utils.mjs
@@ -0,0 +1,15 @@
+import path from 'node:path';
+
+export function getDatabaseUrl() {
+  return (process.env.DATABASE_URL || '').trim() || 'file:./data/app.sqlite';
+}
+
+export function normalizeSqlitePath(rawPath) {
+  if (rawPath.startsWith('//')) {
+    return path.normalize(rawPath);
+  }
+  if (path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  return path.resolve(/*turbopackIgnore: true*/ process.cwd(), rawPath);
+}
diff --git a/scripts/db-migrate.mjs b/scripts/db-migrate.mjs
index e050e2a..0b70444 100644
--- a/scripts/db-migrate.mjs
+++ b/scripts/db-migrate.mjs
@@ -1,26 +1,10 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import knex from 'knex';
-
-function getDatabaseUrl() {
-  return (process.env.DATABASE_URL || '').trim() || 'file:./data/app.sqlite';
-}
-
-function normalizeSqlitePath(rawPath) {
-  if (rawPath.startsWith('//')) {
-    return path.normalize(rawPath);
-  }
-  if (path.isAbsolute(rawPath)) {
-    return rawPath;
-  }
-  return path.resolve(process.cwd(), rawPath);
-}
+import { getDatabaseUrl, normalizeSqlitePath } from '../lib/db/url-utils.mjs';
 
 function createSqliteClient(databaseUrl) {
   const raw = databaseUrl.slice('file:'.length);
-  const filename = raw
-    ? normalizeSqlitePath(raw)
-    : path.resolve(process.cwd(), 'data/app.sqlite');
+  const filename = normalizeSqlitePath(raw || './data/app.sqlite');
 
   fs.mkdirSync(path.dirname(filename), { recursive: true });
 
@@ -51,23 +35,51 @@ function createDbClient() {
   );
 }
 
+function isTableAlreadyExistsError(err) {
+  if (!err || typeof err !== 'object') {
+    return false;
+  }
+
+  if (err.code === '42P07') {
+    return true;
+  }
+
+  if (typeof err.message === 'string') {
+    const lower = err.message.toLowerCase();
+    return (
+      lower.includes('already exists') &&
+      (lower.includes('table') || lower.includes('relation'))
+    );
+  }
+
+  return false;
+}
+
 async function migrate(db) {
   const tableName = 'entra_credentials';
   const exists = await db.schema.hasTable(tableName);
   if (!exists) {
-    await db.schema.createTable(tableName, (table) => {
-      table.string('username').notNullable();
-      table.string('session_id').notNullable();
-      table.text('entra_access_token').notNullable();
-      table.text('entra_refresh_token').nullable();
-      table.bigInteger('stored_at').notNullable();
-      table.bigInteger('updated_at').notNullable();
-      table.bigInteger('last_used_at').notNullable();
-      table.primary(['username', 'session_id']);
-      table.index(['updated_at']);
-      table.index(['last_used_at']);
-    });
-    console.log('[db:migrate] Created table:', tableName);
+    try {
+      await db.schema.createTable(tableName, (table) => {
+        table.string('username').notNullable();
+        table.string('session_id').notNullable();
+        table.text('entra_access_token').notNullable();
+        table.text('entra_refresh_token').nullable();
+        table.bigInteger('stored_at').notNullable();
+        table.bigInteger('updated_at').notNullable();
+        table.bigInteger('last_used_at').notNullable();
+        table.primary(['username', 'session_id']);
+        table.index(['updated_at']);
+        table.index(['last_used_at']);
+      });
+      console.log('[db:migrate] Created table:', tableName);
+    } catch (err) {
+      if (isTableAlreadyExistsError(err)) {
+        console.log('[db:migrate] Table already exists (race-safe):', tableName);
+      } else {
+        throw err;
+      }
+    }
   } else {
     console.log('[db:migrate] Table already exists:', tableName);
   }

From 913c7de81ccb342150073e6079d118cc85e7d977 Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 16:03:13 -0400
Subject: [PATCH 18/19] Encrypt entra tokens in db

---
 README.md                |  7 +++
 lib/auth/config.ts       |  2 +
 lib/auth/token-crypto.ts | 93 ++++++++++++++++++++++++++++++++++++++++
 lib/auth/token-store.ts  | 19 +++++---
 lib/db/client.ts         |  2 +-
 lib/db/url-utils.ts      | 12 ++++++
 scripts/db-migrate.mjs   |  1 +
 7 files changed, 129 insertions(+), 7 deletions(-)
 create mode 100644 lib/auth/token-crypto.ts
 create mode 100644 lib/db/url-utils.ts

diff --git a/README.md b/README.md
index 4bc8831..2819b5b 100644
--- a/README.md
+++ b/README.md
@@ -158,6 +158,13 @@ The app uses a single `DATABASE_URL` for persistence. Supported values:
 - `file:./data/app.sqlite` (default fallback)
 - `postgres://...` or `postgresql://...`
 
+Security note:
+
+- Persisted Entra credentials are encrypted at the application layer.
+- You must provide `ENTRA_TOKEN_ENCRYPTION_KEY` (base64-encoded 32 bytes).
+- Generate with: `openssl rand -base64 32`
+- Keep this key stable across restarts/deploys, or stored credentials become unreadable.
+
 Initialize schema during deploy:
 
 ```bash
diff --git a/lib/auth/config.ts b/lib/auth/config.ts
index 0e23fd5..ea7e189 100644
--- a/lib/auth/config.ts
+++ b/lib/auth/config.ts
@@ -21,6 +21,7 @@ export const TENANT_ID = process.env.ENTRA_TENANT_ID ?? '';
 export const CLIENT_ID = process.env.ENTRA_CLIENT_ID ?? '';
 export const CLIENT_SECRET = process.env.ENTRA_CLIENT_SECRET ?? '';
 export const SESSION_SECRET = process.env.SESSION_SECRET ?? '';
+export const ENTRA_TOKEN_ENCRYPTION_KEY = process.env.ENTRA_TOKEN_ENCRYPTION_KEY ?? '';
 export const TILED_SCOPE = process.env.TILED_SCOPE ?? '';
 export const APP_BASE_URL = process.env.APP_BASE_URL || null;
 export const REDIRECT_ORIGIN_ALLOWLIST: string[] = (
@@ -58,6 +59,7 @@ export function assertAuthConfig(): void {
   if (!CLIENT_ID) missing.push('ENTRA_CLIENT_ID');
   if (!CLIENT_SECRET) missing.push('ENTRA_CLIENT_SECRET');
   if (!SESSION_SECRET) missing.push('SESSION_SECRET');
+  if (!ENTRA_TOKEN_ENCRYPTION_KEY) missing.push('ENTRA_TOKEN_ENCRYPTION_KEY');
   if (!TILED_SCOPE) missing.push('TILED_SCOPE');
   if (missing.length > 0) {
     throw new Error(
diff --git a/lib/auth/token-crypto.ts b/lib/auth/token-crypto.ts
new file mode 100644
index 0000000..497b465
--- /dev/null
+++ b/lib/auth/token-crypto.ts
@@ -0,0 +1,93 @@
+import 'server-only';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { ENTRA_TOKEN_ENCRYPTION_KEY } from './config';
+
+const ENC_PREFIX = 'enc:v1';
+const AES_ALGO = 'aes-256-gcm';
+const IV_LEN = 12;
+const AUTH_TAG_LEN = 16;
+
+let cachedKey: Buffer | null = null;
+
+function getEncryptionKey(): Buffer {
+  if (cachedKey) {
+    return cachedKey;
+  }
+
+  let key: Buffer;
+  try {
+    key = Buffer.from(ENTRA_TOKEN_ENCRYPTION_KEY, 'base64');
+  } catch {
+    throw new Error('[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must be valid base64');
+  }
+
+  if (key.length !== 32) {
+    throw new Error(
+      '[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must decode to exactly 32 bytes'
+    );
+  }
+
+  cachedKey = key;
+  return key;
+}
+
+function encodePart(data: Uint8Array): string {
+  return Buffer.from(data).toString('base64url');
+}
+
+function decodePart(part: string, fieldName: string): Buffer {
+  try {
+    return Buffer.from(part, 'base64url');
+  } catch {
+    throw new Error(`[auth/token-crypto] Invalid encrypted token ${fieldName} encoding`);
+  }
+}
+
+export function encryptToken(plainText: string): string {
+  const key = getEncryptionKey();
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(AES_ALGO, key, iv, { authTagLength: AUTH_TAG_LEN });
+
+  const encrypted = Buffer.concat([
+    cipher.update(plainText, 'utf8'),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  return `${ENC_PREFIX}:${encodePart(iv)}:${encodePart(authTag)}:${encodePart(encrypted)}`;
+}
+
+export function decryptToken(encryptedToken: string): string {
+  if (!encryptedToken.startsWith(`${ENC_PREFIX}:`)) {
+    throw new Error('[auth/token-crypto] Token is not encrypted with supported format (enc:v1)');
+  }
+
+  const parts = encryptedToken.split(':');
+  if (parts.length !== 5 || parts[0] !== 'enc' || parts[1] !== 'v1') {
+    throw new Error('[auth/token-crypto] Invalid encrypted token format');
+  }
+
+  const key = getEncryptionKey();
+  const iv = decodePart(parts[2], 'iv');
+  const authTag = decodePart(parts[3], 'auth tag');
+  const ciphertext = decodePart(parts[4], 'ciphertext');
+
+  if (iv.length !== IV_LEN) {
+    throw new Error('[auth/token-crypto] Invalid encrypted token IV length');
+  }
+  if (authTag.length !== AUTH_TAG_LEN) {
+    throw new Error('[auth/token-crypto] Invalid encrypted token auth tag length');
+  }
+
+  try {
+    const decipher = createDecipheriv(AES_ALGO, key, iv, { authTagLength: AUTH_TAG_LEN });
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+  } catch {
+    throw new Error('[auth/token-crypto] Failed to decrypt token (invalid key or corrupted data)');
+  }
+}
diff --git a/lib/auth/token-store.ts b/lib/auth/token-store.ts
index e456a38..d26c167 100644
--- a/lib/auth/token-store.ts
+++ b/lib/auth/token-store.ts
@@ -1,5 +1,6 @@
 import 'server-only';
 import { isEntraTokenExpiring, refreshEntraAccessToken } from './entra';
+import { decryptToken, encryptToken } from './token-crypto';
 import { getDbClient } from '@/lib/db/client';
 
 // ---------------------------------------------------------------------------
@@ -144,9 +145,11 @@ export async function getTokens(
     return null;
   }
 
+  const encryptedRefreshToken = (row.entra_refresh_token as string | null) ?? null;
+
   return {
-    entraAccessToken: row.entra_access_token as string,
-    entraRefreshToken: (row.entra_refresh_token as string | null) ?? null,
+    entraAccessToken: decryptToken(row.entra_access_token as string),
+    entraRefreshToken: encryptedRefreshToken ? decryptToken(encryptedRefreshToken) : null,
     storedAt: Number(row.stored_at),
   };
 }
@@ -159,21 +162,25 @@ export async function setTokens(
   await ensureSchema();
   const db = getDbClient();
   const now = Date.now();
+  const encryptedAccessToken = encryptToken(entry.entraAccessToken);
+  const encryptedRefreshToken = entry.entraRefreshToken
+    ? encryptToken(entry.entraRefreshToken)
+    : null;
 
   await db(TABLE_NAME)
     .insert({
       username,
       session_id: sessionId,
-      entra_access_token: entry.entraAccessToken,
-      entra_refresh_token: entry.entraRefreshToken,
+      entra_access_token: encryptedAccessToken,
+      entra_refresh_token: encryptedRefreshToken,
       stored_at: entry.storedAt,
       updated_at: now,
       last_used_at: now,
     })
     .onConflict(['username', 'session_id'])
     .merge({
-      entra_access_token: entry.entraAccessToken,
-      entra_refresh_token: entry.entraRefreshToken,
+      entra_access_token: encryptedAccessToken,
+      entra_refresh_token: encryptedRefreshToken,
       stored_at: entry.storedAt,
       updated_at: now,
       last_used_at: now,
diff --git a/lib/db/client.ts b/lib/db/client.ts
index 3913955..ed8c78d 100644
--- a/lib/db/client.ts
+++ b/lib/db/client.ts
@@ -2,7 +2,7 @@ import 'server-only';
 import fs from 'node:fs';
 import path from 'node:path';
 import knex, { Knex } from 'knex';
-import { getDatabaseUrl, normalizeSqlitePath } from './url-utils.mjs';
+import { getDatabaseUrl, normalizeSqlitePath } from './url-utils';
 
 const globalKey = '__appDbClient';
 
diff --git a/lib/db/url-utils.ts b/lib/db/url-utils.ts
new file mode 100644
index 0000000..c3469cb
--- /dev/null
+++ b/lib/db/url-utils.ts
@@ -0,0 +1,12 @@
+import {
+  getDatabaseUrl as getDatabaseUrlUntyped,
+  normalizeSqlitePath as normalizeSqlitePathUntyped,
+} from './url-utils.mjs';
+
+export function getDatabaseUrl(): string {
+  return getDatabaseUrlUntyped();
+}
+
+export function normalizeSqlitePath(rawPath: string): string {
+  return normalizeSqlitePathUntyped(rawPath);
+}
diff --git a/scripts/db-migrate.mjs b/scripts/db-migrate.mjs
index 0b70444..b30d080 100644
--- a/scripts/db-migrate.mjs
+++ b/scripts/db-migrate.mjs
@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import knex from 'knex';
 import { getDatabaseUrl, normalizeSqlitePath } from '../lib/db/url-utils.mjs';
 

From 8d411d39ded45dda5444557b214749d1ae13b3fc Mon Sep 17 00:00:00 2001
From: Shekar V <vshekar1@bnl.gov>
Date: Fri, 12 Jun 2026 16:30:26 -0400
Subject: [PATCH 19/19] More copilot fixes

---
 components/providers/auth-provider.tsx |  7 ++-
 lib/auth/obo.ts                        | 78 +++++++++++++++++++++++++-
 lib/auth/token-crypto.ts               | 27 +++++++--
 3 files changed, 102 insertions(+), 10 deletions(-)

diff --git a/components/providers/auth-provider.tsx b/components/providers/auth-provider.tsx
index 2ad7c87..61a2f5a 100644
--- a/components/providers/auth-provider.tsx
+++ b/components/providers/auth-provider.tsx
@@ -78,8 +78,11 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         });
         return;
       }
-      // Non-200: clear stale Entra marker
-      clearEntraAuthMarker();
+
+      // Clear stale Entra marker only on explicit auth failures.
+      if (sessionResponse.status === 401 || sessionResponse.status === 403) {
+        clearEntraAuthMarker();
+      }
     } catch {
       // Network error: keep marker unchanged, continue to fallback
     }
diff --git a/lib/auth/obo.ts b/lib/auth/obo.ts
index 95291a3..9511ce7 100644
--- a/lib/auth/obo.ts
+++ b/lib/auth/obo.ts
@@ -9,6 +9,7 @@ import { getFreshEntraToken } from './token-store';
 interface OboTokenEntry {
   token: string;
   expiresAt: number; // Unix ms
+  lastUsedAt: number; // Unix ms
 }
 
 // ---------------------------------------------------------------------------
@@ -17,6 +18,17 @@ interface OboTokenEntry {
 
 const OBO_CACHE_BUFFER_MS = 60_000; // Evict 1 min before actual expiry
 const oboCacheKey = '__oboCacheStore';
+const oboCacheLastCleanupKey = '__oboCacheLastCleanup';
+
+function oboCacheMaxEntries(): number {
+  const raw = Number(process.env.OBO_CACHE_MAX_ENTRIES ?? 2000);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 2000;
+}
+
+function oboCacheCleanupIntervalMs(): number {
+  const raw = Number(process.env.OBO_CACHE_CLEANUP_INTERVAL_MS ?? 60_000);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 60_000;
+}
 
 function getOboCache(): Map<string, OboTokenEntry> {
   const g = globalThis as Record<string, unknown>;
@@ -26,6 +38,57 @@ function getOboCache(): Map<string, OboTokenEntry> {
   return g[oboCacheKey] as Map<string, OboTokenEntry>;
 }
 
+function isEntryUsable(entry: OboTokenEntry, now: number): boolean {
+  return now < entry.expiresAt - OBO_CACHE_BUFFER_MS;
+}
+
+function removeExpiredEntries(cache: Map<string, OboTokenEntry>, now: number): void {
+  for (const [key, entry] of cache.entries()) {
+    if (!isEntryUsable(entry, now)) {
+      cache.delete(key);
+    }
+  }
+}
+
+function enforceCacheSizeLimit(cache: Map<string, OboTokenEntry>): void {
+  const maxEntries = oboCacheMaxEntries();
+  while (cache.size > maxEntries) {
+    const oldestKey = cache.keys().next().value as string | undefined;
+    if (!oldestKey) {
+      break;
+    }
+    cache.delete(oldestKey);
+  }
+}
+
+function maybeRunCacheCleanup(cache: Map<string, OboTokenEntry>, now: number): void {
+  const g = globalThis as Record<string, unknown>;
+  const lastCleanup = (g[oboCacheLastCleanupKey] as number | undefined) ?? 0;
+  if (now - lastCleanup < oboCacheCleanupIntervalMs()) {
+    return;
+  }
+
+  g[oboCacheLastCleanupKey] = now;
+  removeExpiredEntries(cache, now);
+  enforceCacheSizeLimit(cache);
+}
+
+function touchCacheEntry(
+  cache: Map<string, OboTokenEntry>,
+  key: string,
+  entry: OboTokenEntry,
+  now: number
+): void {
+  const updated: OboTokenEntry = {
+    ...entry,
+    lastUsedAt: now,
+  };
+
+  // Reinsert to refresh insertion order for LRU-style eviction.
+  cache.delete(key);
+  cache.set(key, updated);
+}
+
 // ---------------------------------------------------------------------------
 // OBO exchange
 // ---------------------------------------------------------------------------
@@ -85,23 +148,34 @@ export async function getOboTokenForUser(
 ): Promise<string> {
   const cache = getOboCache();
   const cacheKey = `${username}:${sessionId}:${TILED_SCOPE}`;
+  const now = Date.now();
+
+  maybeRunCacheCleanup(cache, now);
 
   const cached = cache.get(cacheKey);
-  if (cached && Date.now() < cached.expiresAt - OBO_CACHE_BUFFER_MS) {
+  if (cached && isEntryUsable(cached, now)) {
+    touchCacheEntry(cache, cacheKey, cached, now);
     return cached.token;
   }
 
+  if (cached) {
+    cache.delete(cacheKey);
+  }
+
   // Get a fresh Entra token for this user
   const entraToken = await getFreshEntraToken(username, sessionId);
 
   // Exchange for Tiled token
   const oboResult = await exchangeTokenObo(entraToken);
+  const cachedAt = Date.now();
 
   // Cache it
   cache.set(cacheKey, {
     token: oboResult.access_token,
-    expiresAt: Date.now() + oboResult.expires_in * 1000,
+    expiresAt: cachedAt + oboResult.expires_in * 1000,
+    lastUsedAt: cachedAt,
   });
+  enforceCacheSizeLimit(cache);
 
   return oboResult.access_token;
 }
diff --git a/lib/auth/token-crypto.ts b/lib/auth/token-crypto.ts
index 497b465..1435d56 100644
--- a/lib/auth/token-crypto.ts
+++ b/lib/auth/token-crypto.ts
@@ -9,21 +9,36 @@ const AUTH_TAG_LEN = 16;
 
 let cachedKey: Buffer | null = null;
 
+function isStrictBase64(value: string): boolean {
+  if (value.length === 0 || value.length % 4 !== 0) {
+    return false;
+  }
+
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+    return false;
+  }
+
+  const decoded = Buffer.from(value, 'base64');
+  return decoded.toString('base64') === value;
+}
+
 function getEncryptionKey(): Buffer {
   if (cachedKey) {
     return cachedKey;
   }
 
-  let key: Buffer;
-  try {
-    key = Buffer.from(ENTRA_TOKEN_ENCRYPTION_KEY, 'base64');
-  } catch {
-    throw new Error('[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must be valid base64');
+  const keyBase64 = ENTRA_TOKEN_ENCRYPTION_KEY.trim();
+  if (!isStrictBase64(keyBase64)) {
+    throw new Error(
+      '[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must be canonical base64'
+    );
   }
 
+  const key = Buffer.from(keyBase64, 'base64');
+
   if (key.length !== 32) {
     throw new Error(
-      '[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must decode to exactly 32 bytes'
+      '[auth/token-crypto] ENTRA_TOKEN_ENCRYPTION_KEY must decode to exactly 32 bytes (base64)'
     );
   }