From 88e89c02fc7b71f7b661fe2fe5e946d4ff192278 Mon Sep 17 00:00:00 2001
From: Til Wegener <38760774+tilwegener@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:10:41 +0200
Subject: [PATCH 1/5] Refactor OIDC callback handling and remove manual
 exchange

---
 frontend/src/routes/callback.tsx | 184 +++++++------------------------
 1 file changed, 37 insertions(+), 147 deletions(-)

diff --git a/frontend/src/routes/callback.tsx b/frontend/src/routes/callback.tsx
index ebd74478..73d1aa91 100644
--- a/frontend/src/routes/callback.tsx
+++ b/frontend/src/routes/callback.tsx
@@ -1,173 +1,55 @@
 /**
  * OIDC Callback Route
  *
- * Handles the redirect from the OIDC provider after authentication.
- * Exchanges authorization code for tokens and redirects to the original destination.
- *
- * Reference: decision-009 - OIDC Authentication Implementation
+ * The actual authorization-code exchange, PKCE validation and token storage
+ * are handled by react-oidc-context / oidc-client-ts.
  */
 
 import { createFileRoute, useNavigate } from '@tanstack/react-router';
-import { useAuth, getAuthority, getClientId } from '@/lib/auth';
-import { useEffect, useState } from 'react';
+import { useAuth } from 'react-oidc-context';
+import { useEffect } from 'react';
 
 export const Route = createFileRoute('/callback')({
   component: CallbackRoute,
 });
 
-interface TokenResponse {
-  access_token: string;
-  id_token: string;
-  refresh_token?: string;
-  token_type: string;
-  expires_in: number;
-}
-
-async function exchangeCodeForTokens(code: string): Promise<TokenResponse> {
-  const authority = await getAuthority();
-  const clientId = await getClientId();
-  const redirectUri = window.location.origin + '/callback';
-
-  const response = await fetch(`${authority}/protocol/openid-connect/token`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded',
-    },
-    body: new URLSearchParams({
-      grant_type: 'authorization_code',
-      client_id: clientId,
-      code,
-      redirect_uri: redirectUri,
-    }),
-  });
-
-  if (!response.ok) {
-    const error = await response.text();
-    throw new Error(`Token exchange failed: ${error}`);
-  }
-
-  return response.json();
-}
-
 function CallbackRoute() {
   const auth = useAuth();
   const navigate = useNavigate();
-  const [manualError, setManualError] = useState<string | null>(null);
-  const [manualLoading, setManualLoading] = useState(false);
 
-  // Handle manual token exchange if library's callback fails
   useEffect(() => {
-    // If there's an error from the library (state mismatch), try manual exchange
-    if (auth.error?.message?.includes('state')) {
-      const params = new URLSearchParams(window.location.search);
-      const code = params.get('code');
-      const storedState = sessionStorage.getItem('oidc_state');
-      const returnedState = params.get('state');
-
-      // Verify our custom state if present
-      if (storedState && returnedState && storedState === returnedState && code) {
-        console.log('[Callback] Library state failed, attempting manual token exchange...');
-        setManualLoading(true);
-
-        (async () => {
-          try {
-            const tokens = await exchangeCodeForTokens(code);
-            console.log('[Callback] Manual token exchange successful');
-            // Store tokens in localStorage for the app to use
-            const [authority, clientId] = await Promise.all([getAuthority(), getClientId()]);
-            const storageKey = `oidc.user:${authority}:${clientId}`;
-            localStorage.setItem(storageKey, JSON.stringify({
-              access_token: tokens.access_token,
-              id_token: tokens.id_token,
-              refresh_token: tokens.refresh_token,
-              token_type: tokens.token_type,
-              expires_at: Math.floor(Date.now() / 1000) + tokens.expires_in,
-            }));
-
-            // Clean up
-            sessionStorage.removeItem('oidc_state');
-            sessionStorage.removeItem('oidc_nonce');
-
-            // Redirect to return URL
-            const returnUrl = sessionStorage.getItem('returnUrl') || '/';
-            sessionStorage.removeItem('returnUrl');
-            window.location.href = returnUrl;
-          } catch (err) {
-            console.error('[Callback] Manual token exchange failed:', err);
-            setManualError(err instanceof Error ? err.message : 'Token exchange failed');
-            setManualLoading(false);
-          }
-        })();
-      }
+    if (!auth.isAuthenticated) {
+      return;
     }
-  }, [auth.error]);
 
-  useEffect(() => {
-    // Once authenticated via library, redirect to stored return URL or home
-    if (auth.isAuthenticated) {
-      const returnUrl = sessionStorage.getItem('returnUrl') || '/';
-      sessionStorage.removeItem('returnUrl');
-      navigate({ to: returnUrl });
-    }
+    const returnUrl = sessionStorage.getItem('returnUrl') || '/';
+    sessionStorage.removeItem('returnUrl');
+
+    navigate({ to: returnUrl });
   }, [auth.isAuthenticated, navigate]);
 
-  // Manual exchange loading
-  if (manualLoading) {
-    return (
-      <div className="min-h-[60vh] flex items-center justify-center">
-        <div className="text-center">
-          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-          <h1 className="text-xl font-semibold mb-2">Completing sign-in...</h1>
-          <p className="text-muted-foreground">Exchanging credentials...</p>
-        </div>
-      </div>
-    );
-  }
+  const handleReturnHome = () => {
+    sessionStorage.removeItem('returnUrl');
+    navigate({ to: '/' });
+  };
 
-  // Manual exchange error
-  if (manualError) {
+  if (auth.error) {
     return (
       <div className="min-h-[60vh] flex items-center justify-center">
         <div className="text-center max-w-md p-6">
           <div className="text-destructive text-5xl mb-4">⚠</div>
-          <h1 className="text-xl font-semibold mb-2">Authentication Failed</h1>
-          <p className="text-muted-foreground mb-4">{manualError}</p>
-          <button
-            onClick={() => navigate({ to: '/' })}
-            className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors"
-          >
-            Return Home
-          </button>
-        </div>
-      </div>
-    );
-  }
 
-  // Loading state during token exchange
-  if (auth.isLoading) {
-    return (
-      <div className="min-h-[60vh] flex items-center justify-center">
-        <div className="text-center">
-          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-          <h1 className="text-xl font-semibold mb-2">Completing sign-in...</h1>
-          <p className="text-muted-foreground">
-            Please wait while we verify your credentials.
+          <h1 className="text-xl font-semibold mb-2">
+            Authentication Failed
+          </h1>
+
+          <p className="text-muted-foreground mb-4">
+            {auth.error.message}
           </p>
-        </div>
-      </div>
-    );
-  }
 
-  // Error state from library (will trigger manual exchange if state-related)
-  if (auth.error && !auth.error.message?.includes('state')) {
-    return (
-      <div className="min-h-[60vh] flex items-center justify-center">
-        <div className="text-center max-w-md p-6">
-          <div className="text-destructive text-5xl mb-4">⚠</div>
-          <h1 className="text-xl font-semibold mb-2">Authentication Failed</h1>
-          <p className="text-muted-foreground mb-4">{auth.error.message}</p>
           <button
-            onClick={() => navigate({ to: '/' })}
+            type="button"
+            onClick={handleReturnHome}
             className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors"
           >
             Return Home
@@ -177,27 +59,35 @@ function CallbackRoute() {
     );
   }
 
-  // Authenticated - showing redirect message
   if (auth.isAuthenticated) {
     return (
       <div className="min-h-[60vh] flex items-center justify-center">
         <div className="text-center">
           <div className="text-green-500 text-5xl mb-4">✓</div>
-          <h1 className="text-xl font-semibold mb-2">Sign-in Successful</h1>
-          <p className="text-muted-foreground">Redirecting...</p>
+
+          <h1 className="text-xl font-semibold mb-2">
+            Sign-in Successful
+          </h1>
+
+          <p className="text-muted-foreground">
+            Redirecting...
+          </p>
         </div>
       </div>
     );
   }
 
-  // Default state - waiting for auth callback to complete
   return (
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-        <h1 className="text-xl font-semibold mb-2">Processing...</h1>
+
+        <h1 className="text-xl font-semibold mb-2">
+          Completing sign-in...
+        </h1>
+
         <p className="text-muted-foreground">
-          Completing authentication.
+          Please wait while we verify your credentials.
         </p>
       </div>
     </div>

From 1f422f3a8f2a1f16476865e731cb9866be74ec83 Mon Sep 17 00:00:00 2001
From: Til Wegener <38760774+tilwegener@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:12:04 +0200
Subject: [PATCH 2/5] Refactor AuthGuard for OIDC redirection

Refactored authentication redirection logic to use signinRedirect method and removed unused OIDC config fetching.
---
 frontend/src/lib/auth/AuthGuard.tsx | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/frontend/src/lib/auth/AuthGuard.tsx b/frontend/src/lib/auth/AuthGuard.tsx
index 1bce127e..2570ca86 100644
--- a/frontend/src/lib/auth/AuthGuard.tsx
+++ b/frontend/src/lib/auth/AuthGuard.tsx
@@ -9,7 +9,7 @@
 
 import { useEffect, useState, type ReactNode } from 'react';
 import { useAuth } from 'react-oidc-context';
-import { isOIDCEnabledAsync, hasValidManualTokensAsync, getAuthority, getClientId, getScope } from './config';
+import { isOIDCEnabledAsync, hasValidManualTokensAsync } from './config';
 
 interface AuthGuardProps {
   children: ReactNode;
@@ -79,22 +79,11 @@ function AuthGuardInner({ children }: AuthGuardProps) {
       console.log('[AuthGuard] User not authenticated, redirecting to login...');
 
       // Fetch OIDC config asynchronously (supports runtime config.json)
-      Promise.all([getAuthority(), getClientId(), getScope()]).then(([authority, clientId, scope]) => {
-        const redirectUri = encodeURIComponent(window.location.origin + '/callback');
-        const encodedScope = encodeURIComponent(scope);
-        // Generate random state and nonce (works in non-HTTPS contexts)
-        const randomString = () => Math.random().toString(36).substring(2) + Date.now().toString(36);
-        const state = randomString();
-        const nonce = randomString();
-
-        // Store state for validation
-        sessionStorage.setItem('oidc_state', state);
-        sessionStorage.setItem('oidc_nonce', nonce);
-
-        const url = `${authority}/protocol/openid-connect/auth?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code&scope=${encodedScope}&state=${state}&nonce=${nonce}`;
-        console.log('[AuthGuard] Redirecting to:', url);
-        window.location.href = url;
+      auth.signinRedirect().catch((error) => {
+        console.error('[AuthGuard] OIDC redirect failed:', error);
+        setIsRedirecting(false);
       });
+      
     }
   }, [isCallbackRoute, auth.isLoading, tokensChecked, isAuthenticated, auth.activeNavigator, isRedirecting]);
 

From 059f856f21ee5ab3fce1f8b8b39d92e19af0de0c Mon Sep 17 00:00:00 2001
From: Til Wegener <38760774+tilwegener@users.noreply.github.com>
Date: Mon, 27 Jul 2026 22:21:44 +0200
Subject: [PATCH 3/5] Refactor AuthGuard for improved readability and structure

---
 frontend/src/lib/auth/AuthGuard.tsx | 154 ++++++++++++++++++++--------
 1 file changed, 111 insertions(+), 43 deletions(-)

diff --git a/frontend/src/lib/auth/AuthGuard.tsx b/frontend/src/lib/auth/AuthGuard.tsx
index 2570ca86..58fa8f40 100644
--- a/frontend/src/lib/auth/AuthGuard.tsx
+++ b/frontend/src/lib/auth/AuthGuard.tsx
@@ -9,7 +9,10 @@
 
 import { useEffect, useState, type ReactNode } from 'react';
 import { useAuth } from 'react-oidc-context';
-import { isOIDCEnabledAsync, hasValidManualTokensAsync } from './config';
+import {
+  hasValidManualTokensAsync,
+  isOIDCEnabledAsync,
+} from './config';
 
 interface AuthGuardProps {
   children: ReactNode;
@@ -23,112 +26,177 @@ function AuthLoading() {
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-        <h1 className="text-xl font-semibold mb-2">Checking authentication...</h1>
-        <p className="text-muted-foreground">Please wait.</p>
+
+        <h1 className="text-xl font-semibold mb-2">
+          Checking authentication...
+        </h1>
+
+        <p className="text-muted-foreground">
+          Please wait.
+        </p>
       </div>
     </div>
   );
 }
 
 /**
- * Redirecting message shown while navigating to OIDC provider
+ * Redirecting message shown while navigating to the OIDC provider
  */
 function AuthRedirecting() {
   return (
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-        <h1 className="text-xl font-semibold mb-2">Authentication Required</h1>
-        <p className="text-muted-foreground">Redirecting to login...</p>
+
+        <h1 className="text-xl font-semibold mb-2">
+          Authentication Required
+        </h1>
+
+        <p className="text-muted-foreground">
+          Redirecting to login...
+        </p>
       </div>
     </div>
   );
 }
 
 /**
- * Inner component that uses hooks - only rendered when OIDC is enabled
+ * Inner component that uses authentication hooks.
+ * Only rendered when OIDC is enabled.
  */
 function AuthGuardInner({ children }: AuthGuardProps) {
   const auth = useAuth();
-  // Check for manually stored tokens (from our custom callback handler)
+
+  // Check for previously stored tokens.
   const [hasManualTokens, setHasManualTokens] = useState(false);
   const [tokensChecked, setTokensChecked] = useState(false);
   const [isRedirecting, setIsRedirecting] = useState(false);
 
-  // Check if we're on the callback route (don't redirect during OIDC callback)
+  // Do not start another redirect while processing the OIDC callback.
   const isCallbackRoute = window.location.pathname === '/callback';
 
-  // Re-check manual tokens when component mounts or auth state changes
+  // Re-check stored tokens when the component mounts or auth state changes.
   useEffect(() => {
-    hasValidManualTokensAsync().then((hasTokens) => {
-      setHasManualTokens(hasTokens);
-      setTokensChecked(true);
-    });
+    hasValidManualTokensAsync()
+      .then((hasTokens) => {
+        setHasManualTokens(hasTokens);
+        setTokensChecked(true);
+      })
+      .catch((error) => {
+        console.error(
+          '[AuthGuard] Failed to check stored tokens:',
+          error,
+        );
+
+        setHasManualTokens(false);
+        setTokensChecked(true);
+      });
   }, [auth.isAuthenticated]);
 
-  // Consider authenticated if library says so OR we have valid manual tokens
-  const isAuthenticated = auth.isAuthenticated || hasManualTokens;
+  // Consider the user authenticated if the OIDC client or existing tokens
+  // indicate a valid authenticated session.
+  const isAuthenticated =
+    auth.isAuthenticated || hasManualTokens;
 
-  // Redirect to login if not authenticated (wait for token check to complete)
+  // Redirect to the OIDC provider when authentication is required.
   useEffect(() => {
-    if (!isCallbackRoute && !auth.isLoading && tokensChecked && !isAuthenticated && !auth.activeNavigator && !isRedirecting) {
-      setIsRedirecting(true);
+    if (
+      isCallbackRoute ||
+      auth.isLoading ||
+      !tokensChecked ||
+      isAuthenticated ||
+      auth.activeNavigator ||
+      isRedirecting
+    ) {
+      return;
+    }
 
-      // Store current path for redirect after login
-      sessionStorage.setItem('returnUrl', window.location.pathname + window.location.search);
-      console.log('[AuthGuard] User not authenticated, redirecting to login...');
+    setIsRedirecting(true);
 
-      // Fetch OIDC config asynchronously (supports runtime config.json)
-      auth.signinRedirect().catch((error) => {
-        console.error('[AuthGuard] OIDC redirect failed:', error);
-        setIsRedirecting(false);
-      });
-      
-    }
-  }, [isCallbackRoute, auth.isLoading, tokensChecked, isAuthenticated, auth.activeNavigator, isRedirecting]);
+    // Store the current URL so the callback route can restore it after login.
+    sessionStorage.setItem(
+      'returnUrl',
+      window.location.pathname + window.location.search,
+    );
+
+    console.log(
+      '[AuthGuard] User not authenticated, redirecting to login...',
+    );
+
+    // Let oidc-client-ts discover the provider endpoints and handle PKCE.
+    auth.signinRedirect().catch((error) => {
+      console.error(
+        '[AuthGuard] OIDC redirect failed:',
+        error,
+      );
 
-  // Allow callback route to render without auth check
+      setIsRedirecting(false);
+    });
+  }, [
+    isCallbackRoute,
+    auth.isLoading,
+    auth.activeNavigator,
+    auth.signinRedirect,
+    tokensChecked,
+    isAuthenticated,
+    isRedirecting,
+  ]);
+
+  // Allow the callback route to render while authentication is processed.
   if (isCallbackRoute) {
     return <>{children}</>;
   }
 
-  // Loading state (waiting for auth library or token check)
+  // Wait for the OIDC client and stored-token check.
   if (auth.isLoading || !tokensChecked) {
     return <AuthLoading />;
   }
 
-  // Not authenticated - show redirecting message
+  // Show a loading state while redirecting to the OIDC provider.
   if (!isAuthenticated) {
     return <AuthRedirecting />;
   }
 
-  // Authenticated - render children
   return <>{children}</>;
 }
 
 /**
- * AuthGuard enforces authentication for wrapped content.
+ * Enforces authentication for wrapped content.
  *
- * - If OIDC is disabled, renders children without auth check
- * - If authenticated, renders children
- * - If not authenticated, redirects to OIDC login
+ * - If OIDC is disabled, renders children without an authentication check.
+ * - If authenticated, renders children.
+ * - If unauthenticated, redirects to the OIDC provider.
  */
 export function AuthGuard({ children }: AuthGuardProps) {
-  const [oidcEnabled, setOidcEnabled] = useState<boolean | null>(null);
+  const [oidcEnabled, setOidcEnabled] =
+    useState<boolean | null>(null);
 
   useEffect(() => {
-    isOIDCEnabledAsync().then(setOidcEnabled);
+    isOIDCEnabledAsync()
+      .then(setOidcEnabled)
+      .catch((error) => {
+        console.error(
+          '[AuthGuard] Failed to load OIDC configuration:',
+          error,
+        );
+
+        setOidcEnabled(false);
+      });
   }, []);
 
-  // Still checking if OIDC is enabled
+  // OIDC configuration is still loading.
   if (oidcEnabled === null) {
     return <AuthLoading />;
   }
 
-  // If OIDC is not enabled, render children without auth check
+  // Render without authentication when OIDC is disabled.
   if (!oidcEnabled) {
     return <>{children}</>;
   }
 
-  return <AuthGuardInner>{children}</AuthGuardInner>;
+  return (
+    <AuthGuardInner>
+      {children}
+    </AuthGuardInner>
+  );
 }

From 8961cde160825baf9a106cf4555b20349e4e1006 Mon Sep 17 00:00:00 2001
From: Oriol Rius <oriol@joor.net>
Date: Wed, 21 Oct 2026 17:11:17 +0200
Subject: [PATCH 4/5] feat(auth): finish provider-agnostic OIDC on top of PR #7

PR #7 moved login and callback onto react-oidc-context. This finishes the
migration so no Keycloak-specific or hand-rolled protocol code is left:

- Share one oidc-client-ts UserManager (token.ts) between AuthProvider (via
  its userManager prop) and the tRPC token lookup. One store and one renewal
  timer.
- getAccessToken() renews an expiring token through the library
  (signinSilent, single-flight, 60s buffer). This replaces the hard-coded
  Keycloak /protocol/openid-connect/token refresh.
- Keep the session in localStorage (userStore) so tabs share it, and clean
  up the legacy hand-rolled token blob stored under the same key.
- UserMenu: login and logout through signinRedirect/signoutRedirect. Logout
  previously left the library user behind, so the app still looked signed
  in. The Account Settings link is only shown for Keycloak authorities.
- Remove the manual token helpers (hasValidManualTokens*, getStorageKey*).
- AuthProvider: show an explicit "secure context required" error over plain
  HTTP on non-localhost origins, because PKCE needs crypto.subtle.
- AuthGuard: guard the redirect with a ref. React StrictMode fired two
  signinRedirect() calls (two racing auth requests made the login form fail
  intermittently). Drop the PR's fail-open catch on the OIDC config check.
- E2E: logout no longer shows Keycloak's confirmation page (id_token_hint is
  sent). New test: an expiring token is renewed without re-login and
  without 401s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frontend/CLAUDE.md                     |  22 +--
 frontend/src/components/UserMenu.tsx   | 124 +++----------
 frontend/src/lib/auth/AuthGuard.tsx    | 118 +++---------
 frontend/src/lib/auth/AuthProvider.tsx |  29 +--
 frontend/src/lib/auth/config.ts        |  76 ++------
 frontend/src/lib/auth/index.ts         |   4 +-
 frontend/src/lib/auth/token.test.ts    | 174 +++++++++---------
 frontend/src/lib/auth/token.ts         | 238 ++++++++-----------------
 frontend/src/routes/callback.tsx       |  45 ++---
 tests/auth.spec.ts                     |  60 +++++--
 10 files changed, 315 insertions(+), 575 deletions(-)

diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md
index fd4b9a84..af9c9c9f 100644
--- a/frontend/CLAUDE.md
+++ b/frontend/CLAUDE.md
@@ -2,7 +2,7 @@
 
 React 19 SPA: **TanStack Router** (file-based) + **TanStack Query** + a **tRPC v11** client
 that imports the backend's `AppRouter` type for end-to-end type safety. **OIDC** auth
-(oidc-client-ts + react-oidc-context, Keycloak-shaped), **Tailwind 4**, **Vite 7**, Vitest +
+(oidc-client-ts + react-oidc-context, provider-agnostic), **Tailwind 4**, **Vite 7**, Vitest +
 RTL. See the root `CLAUDE.md` for repo-wide rules.
 
 ## Commands
@@ -50,11 +50,15 @@ runtime `public/config.json` (fetched at startup; `apiUrl` + optional `oidc` blo
 with placeholder `{"apiUrl":"__API_URL__"}` substituted at deploy time. **OIDC is optional**
 — enabled only when an authority is set; otherwise the app runs unauthenticated.
 
-The library's PKCE/`signinRedirect` is unreliable over non-HTTPS, so `src/lib/auth/` has a
-**hand-rolled fallback**: a manual `/protocol/openid-connect/auth` URL with self-generated
-`state`/`nonce`; `callback.tsx` falls back to a manual token POST → `localStorage`;
-`token.ts` `getAccessToken()` tries the library `UserManager` then the manual token. Silent
-renew uses `public/silent-renew.html` (loads oidc-client-ts from a **CDN**).
+The whole flow is the library's (PR #7): endpoints come from OIDC discovery, login/logout are
+`signinRedirect`/`signoutRedirect`, PKCE + state/nonce are validated by oidc-client-ts. One
+**shared `UserManager`** (`token.ts` `getUserManager()`) feeds both `AuthProvider` (via its
+`userManager` prop) and the tRPC `getAccessToken()`, which renews on demand (`signinSilent`,
+single-flight, 60 s buffer). The session lives in **`localStorage`** (`userStore`), key
+`oidc.user:<authority>:<clientId>`. **Requires a secure context** (HTTPS or
+`http://localhost`): `AuthProvider` shows an explicit error otherwise. There is no
+non-HTTPS fallback any more — don't reintroduce one. Silent renew prefers the refresh
+token; the iframe fallback uses `public/silent-renew.html` (loads oidc-client-ts from a **CDN**).
 
 ## Styling
 
@@ -64,9 +68,7 @@ Tailwind **4** via PostCSS (no `tailwind.config.js`; tokens are CSS-first in `sr
 
 ## Gotchas
 
-- **Dev port `52080`**; `vite.config.ts` `allowedHosts` = `wsl.ymbihq.local`, `localhost`,
-  `.ymbihq.local` (wildcard) — other hostnames are blocked. Committed `.env` points at
-  `wsl.ymbihq.local` hosts; change it for local-only dev.
+- **Dev port `52080`, open it as `http://localhost:52080`.** `vite.config.ts` has no
+  `allowedHosts`, so only localhost/IPs are accepted, and only localhost is a secure context.
 - `build:docker`/`tsconfig.build.json` **relax strictness** — run `npm run typecheck` to catch real type errors.
-- Two token stores coexist (library `UserManager` + manual `localStorage`) — check both when debugging auth.
 - `silent-renew.html` pulls oidc-client-ts from a public CDN — silent renew breaks in air-gapped envs.
diff --git a/frontend/src/components/UserMenu.tsx b/frontend/src/components/UserMenu.tsx
index 68b360d0..176bfcd8 100644
--- a/frontend/src/components/UserMenu.tsx
+++ b/frontend/src/components/UserMenu.tsx
@@ -10,7 +10,7 @@
  * Reference: decision-009 - OIDC Authentication Implementation
  */
 
-import { useAuth, isOIDCEnabledAsync, hasValidManualTokensAsync, getStorageKeyAsync, getAuthority, getClientId, getScope } from '@/lib/auth';
+import { useAuth, isOIDCEnabledAsync, getAuthority } from '@/lib/auth';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import {
   faUser,
@@ -21,30 +21,6 @@ import {
 } from '@fortawesome/free-solid-svg-icons';
 import { useState, useRef, useEffect } from 'react';
 
-/**
- * Gets user info from manually stored tokens using a specific storage key
- */
-function getManualUserInfoFromStorage(storageKey: string): { name?: string; email?: string } | null {
-  try {
-    const stored = localStorage.getItem(storageKey);
-    if (!stored) return null;
-
-    const data = JSON.parse(stored);
-    if (!data.id_token) return null;
-
-    // Decode JWT payload (id_token contains user claims)
-    const payload = data.id_token.split('.')[1];
-    const decoded = JSON.parse(atob(payload));
-
-    return {
-      name: decoded.name || decoded.preferred_username,
-      email: decoded.email,
-    };
-  } catch {
-    return null;
-  }
-}
-
 export function UserMenu() {
   // useAuth() throws/returns undefined when no OIDCAuthProvider wraps the tree
   // (i.e. OIDC disabled). Guard so the rest of the component is safe.
@@ -57,52 +33,20 @@ export function UserMenu() {
   const [isOpen, setIsOpen] = useState(false);
   const menuRef = useRef<HTMLDivElement>(null);
   const [oidcEnabled, setOidcEnabled] = useState<boolean | null>(null);
-  const [oidcConfig, setOidcConfig] = useState<{ authority: string; clientId: string; scope: string } | null>(null);
+  const [authority, setAuthority] = useState<string | null>(null);
 
-  // Check for manual tokens
-  const [hasManualTokens, setHasManualTokens] = useState(false);
-  const [manualUserInfo, setManualUserInfo] = useState<{ name?: string; email?: string } | null>(null);
-
-  // Check if OIDC is enabled and load config (supports runtime config)
+  // Check if OIDC is enabled and load the authority (supports runtime config)
   useEffect(() => {
     async function loadOIDCConfig() {
       const enabled = await isOIDCEnabledAsync();
       setOidcEnabled(enabled);
       if (enabled) {
-        const [authority, clientId, scope] = await Promise.all([
-          getAuthority(),
-          getClientId(),
-          getScope(),
-        ]);
-        setOidcConfig({ authority, clientId, scope });
-
-        // Check for manual tokens
-        const hasTokens = await hasValidManualTokensAsync();
-        setHasManualTokens(hasTokens);
-        if (hasTokens) {
-          const storageKey = await getStorageKeyAsync();
-          setManualUserInfo(getManualUserInfoFromStorage(storageKey));
-        }
+        setAuthority(await getAuthority());
       }
     }
     loadOIDCConfig();
   }, []);
 
-  // Re-check manual tokens when auth state changes
-  useEffect(() => {
-    async function checkTokens() {
-      const hasTokens = await hasValidManualTokensAsync();
-      setHasManualTokens(hasTokens);
-      if (hasTokens) {
-        const storageKey = await getStorageKeyAsync();
-        setManualUserInfo(getManualUserInfoFromStorage(storageKey));
-      } else {
-        setManualUserInfo(null);
-      }
-    }
-    checkTokens();
-  }, [auth?.isAuthenticated]);
-
   // Close menu when clicking outside
   useEffect(() => {
     function handleClickOutside(event: MouseEvent) {
@@ -121,7 +65,7 @@ export function UserMenu() {
   }
 
   // Still loading OIDC config
-  if (oidcEnabled === null || !oidcConfig) {
+  if (oidcEnabled === null || authority === null || !auth) {
     return (
       <div className="flex items-center gap-2 px-3 py-2 text-muted-foreground">
         <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-current" />
@@ -129,52 +73,33 @@ export function UserMenu() {
     );
   }
 
-  // Handle login - redirect to OIDC provider
+  // Handle login - redirect to OIDC provider (discovery + PKCE handled by the library)
   const handleLogin = () => {
     // Store current path for redirect after login
-    sessionStorage.setItem('returnUrl', window.location.pathname);
-
-    // Use manual redirect (signinRedirect doesn't work reliably in non-HTTPS)
-    const redirectUri = encodeURIComponent(window.location.origin + '/callback');
-    const encodedScope = encodeURIComponent(oidcConfig.scope);
-    const randomString = () => Math.random().toString(36).substring(2) + Date.now().toString(36);
-    const state = randomString();
-    const nonce = randomString();
-
-    sessionStorage.setItem('oidc_state', state);
-    sessionStorage.setItem('oidc_nonce', nonce);
-
-    const url = `${oidcConfig.authority}/protocol/openid-connect/auth?client_id=${oidcConfig.clientId}&redirect_uri=${redirectUri}&response_type=code&scope=${encodedScope}&state=${state}&nonce=${nonce}`;
-    window.location.href = url;
+    sessionStorage.setItem('returnUrl', window.location.pathname + window.location.search);
+    auth.signinRedirect().catch((error) => console.error('[UserMenu] Login redirect failed:', error));
   };
 
-  // Handle logout - clear tokens and redirect to OIDC provider logout
+  // Handle logout - end the provider session (end_session_endpoint from discovery). The
+  // library drops the local user first, so the app never shows a stale signed-in state.
   const handleLogout = () => {
-    // Clear manual tokens (use oidcConfig which is already loaded)
-    const storageKey = `oidc.user:${oidcConfig.authority}:${oidcConfig.clientId}`;
-    localStorage.removeItem(storageKey);
-    sessionStorage.removeItem('oidc_state');
-    sessionStorage.removeItem('oidc_nonce');
     sessionStorage.removeItem('returnUrl');
-
-    // Redirect to Keycloak logout
-    const redirectUri = encodeURIComponent(window.location.origin);
-    const logoutUrl = `${oidcConfig.authority}/protocol/openid-connect/logout?post_logout_redirect_uri=${redirectUri}&client_id=${oidcConfig.clientId}`;
-    window.location.href = logoutUrl;
+    auth.signoutRedirect().catch(async (error) => {
+      // Provider without RP-initiated logout: at least end the local session.
+      console.warn('[UserMenu] Provider logout failed, clearing local session:', error);
+      await auth.removeUser();
+      window.location.assign('/');
+    });
   };
 
-  // Gets the account management URL for the OIDC provider
-  const getAccountUrl = (): string | null => {
-    if (!oidcConfig.authority) return null;
-    // For Keycloak, account page is at /account
-    return `${oidcConfig.authority}/account`;
-  };
+  // Account management page — only Keycloak has a well-known one (<realm>/account).
+  const getAccountUrl = (): string | null =>
+    /\/realms\/[^/]+\/?$/.test(authority) ? `${authority.replace(/\/$/, '')}/account` : null;
 
-  // Consider authenticated if library says so OR we have valid manual tokens
-  const isAuthenticated = auth?.isAuthenticated || hasManualTokens;
+  const isAuthenticated = auth.isAuthenticated;
 
   // Loading state
-  if (auth?.isLoading) {
+  if (auth.isLoading) {
     return (
       <div className="flex items-center gap-2 px-3 py-2 text-muted-foreground">
         <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-current" />
@@ -196,10 +121,9 @@ export function UserMenu() {
   }
 
   // Authenticated - show user menu
-  // Use library user info if available, otherwise use manual token info
-  const user = auth?.user;
-  const displayName = user?.profile?.name || user?.profile?.preferred_username || user?.profile?.email || manualUserInfo?.name || 'User';
-  const email = user?.profile?.email || manualUserInfo?.email;
+  const user = auth.user;
+  const displayName = user?.profile?.name || user?.profile?.preferred_username || user?.profile?.email || 'User';
+  const email = user?.profile?.email;
   const accountUrl = getAccountUrl();
 
   return (
diff --git a/frontend/src/lib/auth/AuthGuard.tsx b/frontend/src/lib/auth/AuthGuard.tsx
index 58fa8f40..da0f4f85 100644
--- a/frontend/src/lib/auth/AuthGuard.tsx
+++ b/frontend/src/lib/auth/AuthGuard.tsx
@@ -1,18 +1,15 @@
 /**
  * AuthGuard Component
  *
- * Enforces authentication at the application level.
+ * Enforces authentication at the application root level.
  * Redirects unauthenticated users to the OIDC provider login.
  *
  * Reference: decision-009 - OIDC Authentication Implementation
  */
 
-import { useEffect, useState, type ReactNode } from 'react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
 import { useAuth } from 'react-oidc-context';
-import {
-  hasValidManualTokensAsync,
-  isOIDCEnabledAsync,
-} from './config';
+import { isOIDCEnabledAsync } from './config';
 
 interface AuthGuardProps {
   children: ReactNode;
@@ -26,14 +23,8 @@ function AuthLoading() {
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-
-        <h1 className="text-xl font-semibold mb-2">
-          Checking authentication...
-        </h1>
-
-        <p className="text-muted-foreground">
-          Please wait.
-        </p>
+        <h1 className="text-xl font-semibold mb-2">Checking authentication...</h1>
+        <p className="text-muted-foreground">Please wait.</p>
       </div>
     </div>
   );
@@ -47,14 +38,8 @@ function AuthRedirecting() {
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-
-        <h1 className="text-xl font-semibold mb-2">
-          Authentication Required
-        </h1>
-
-        <p className="text-muted-foreground">
-          Redirecting to login...
-        </p>
+        <h1 className="text-xl font-semibold mb-2">Authentication Required</h1>
+        <p className="text-muted-foreground">Redirecting to login...</p>
       </div>
     </div>
   );
@@ -66,80 +51,42 @@ function AuthRedirecting() {
  */
 function AuthGuardInner({ children }: AuthGuardProps) {
   const auth = useAuth();
-
-  // Check for previously stored tokens.
-  const [hasManualTokens, setHasManualTokens] = useState(false);
-  const [tokensChecked, setTokensChecked] = useState(false);
-  const [isRedirecting, setIsRedirecting] = useState(false);
+  // A ref, not state: StrictMode runs effects twice before a state update lands, which
+  // fired two signinRedirect() calls (two auth requests racing on the login page).
+  const redirectStarted = useRef(false);
 
   // Do not start another redirect while processing the OIDC callback.
   const isCallbackRoute = window.location.pathname === '/callback';
 
-  // Re-check stored tokens when the component mounts or auth state changes.
-  useEffect(() => {
-    hasValidManualTokensAsync()
-      .then((hasTokens) => {
-        setHasManualTokens(hasTokens);
-        setTokensChecked(true);
-      })
-      .catch((error) => {
-        console.error(
-          '[AuthGuard] Failed to check stored tokens:',
-          error,
-        );
-
-        setHasManualTokens(false);
-        setTokensChecked(true);
-      });
-  }, [auth.isAuthenticated]);
-
-  // Consider the user authenticated if the OIDC client or existing tokens
-  // indicate a valid authenticated session.
-  const isAuthenticated =
-    auth.isAuthenticated || hasManualTokens;
-
   // Redirect to the OIDC provider when authentication is required.
   useEffect(() => {
     if (
       isCallbackRoute ||
       auth.isLoading ||
-      !tokensChecked ||
-      isAuthenticated ||
+      auth.isAuthenticated ||
       auth.activeNavigator ||
-      isRedirecting
+      redirectStarted.current
     ) {
       return;
     }
 
-    setIsRedirecting(true);
+    redirectStarted.current = true;
 
     // Store the current URL so the callback route can restore it after login.
-    sessionStorage.setItem(
-      'returnUrl',
-      window.location.pathname + window.location.search,
-    );
-
-    console.log(
-      '[AuthGuard] User not authenticated, redirecting to login...',
-    );
+    sessionStorage.setItem('returnUrl', window.location.pathname + window.location.search);
+    console.log('[AuthGuard] User not authenticated, redirecting to login...');
 
     // Let oidc-client-ts discover the provider endpoints and handle PKCE.
     auth.signinRedirect().catch((error) => {
-      console.error(
-        '[AuthGuard] OIDC redirect failed:',
-        error,
-      );
-
-      setIsRedirecting(false);
+      console.error('[AuthGuard] OIDC redirect failed:', error);
+      redirectStarted.current = false;
     });
   }, [
     isCallbackRoute,
     auth.isLoading,
+    auth.isAuthenticated,
     auth.activeNavigator,
     auth.signinRedirect,
-    tokensChecked,
-    isAuthenticated,
-    isRedirecting,
   ]);
 
   // Allow the callback route to render while authentication is processed.
@@ -147,13 +94,11 @@ function AuthGuardInner({ children }: AuthGuardProps) {
     return <>{children}</>;
   }
 
-  // Wait for the OIDC client and stored-token check.
-  if (auth.isLoading || !tokensChecked) {
+  if (auth.isLoading) {
     return <AuthLoading />;
   }
 
-  // Show a loading state while redirecting to the OIDC provider.
-  if (!isAuthenticated) {
+  if (!auth.isAuthenticated) {
     return <AuthRedirecting />;
   }
 
@@ -168,20 +113,13 @@ function AuthGuardInner({ children }: AuthGuardProps) {
  * - If unauthenticated, redirects to the OIDC provider.
  */
 export function AuthGuard({ children }: AuthGuardProps) {
-  const [oidcEnabled, setOidcEnabled] =
-    useState<boolean | null>(null);
+  const [oidcEnabled, setOidcEnabled] = useState<boolean | null>(null);
 
   useEffect(() => {
-    isOIDCEnabledAsync()
-      .then(setOidcEnabled)
-      .catch((error) => {
-        console.error(
-          '[AuthGuard] Failed to load OIDC configuration:',
-          error,
-        );
-
-        setOidcEnabled(false);
-      });
+    // No catch on purpose: falling back to "OIDC disabled" on an error would render the
+    // app unauthenticated (fail-open). isOIDCEnabledAsync already treats a missing
+    // config.json as "use build-time settings".
+    isOIDCEnabledAsync().then(setOidcEnabled);
   }, []);
 
   // OIDC configuration is still loading.
@@ -194,9 +132,5 @@ export function AuthGuard({ children }: AuthGuardProps) {
     return <>{children}</>;
   }
 
-  return (
-    <AuthGuardInner>
-      {children}
-    </AuthGuardInner>
-  );
+  return <AuthGuardInner>{children}</AuthGuardInner>;
 }
diff --git a/frontend/src/lib/auth/AuthProvider.tsx b/frontend/src/lib/auth/AuthProvider.tsx
index f015552b..e5efeee6 100644
--- a/frontend/src/lib/auth/AuthProvider.tsx
+++ b/frontend/src/lib/auth/AuthProvider.tsx
@@ -9,8 +9,9 @@
 
 import { useState, useEffect, type ReactNode } from 'react';
 import { AuthProvider as OIDCAuthProvider } from 'react-oidc-context';
-import type { UserManagerSettings } from 'oidc-client-ts';
-import { buildOIDCSettings, isOIDCEnabledAsync } from './config';
+import type { UserManager } from 'oidc-client-ts';
+import { isOIDCEnabledAsync, isSecureContextForOIDC } from './config';
+import { getUserManager } from './token';
 
 interface AuthProviderProps {
   children: ReactNode;
@@ -52,7 +53,7 @@ function AuthError({ message }: { message: string }) {
  * without authentication wrapper, allowing the app to run in unauthenticated mode.
  */
 export function AuthProvider({ children }: AuthProviderProps) {
-  const [settings, setSettings] = useState<UserManagerSettings | null>(null);
+  const [userManager, setUserManager] = useState<UserManager | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
 
@@ -65,9 +66,18 @@ export function AuthProvider({ children }: AuthProviderProps) {
         return;
       }
 
+      // Fail with an actionable message instead of a cryptic crypto error at login time.
+      if (!isSecureContextForOIDC()) {
+        setError(
+          `Login requires a secure context. Open this app over HTTPS or via http://localhost ` +
+            `(current origin: ${window.location.origin}).`
+        );
+        setLoading(false);
+        return;
+      }
+
       try {
-        const oidcSettings = await buildOIDCSettings();
-        setSettings(oidcSettings);
+        setUserManager(await getUserManager());
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load OIDC configuration');
       } finally {
@@ -89,7 +99,7 @@ export function AuthProvider({ children }: AuthProviderProps) {
   }
 
   // If OIDC is not enabled, render children without auth wrapper
-  if (!settings) {
+  if (!userManager) {
     return <>{children}</>;
   }
 
@@ -103,12 +113,9 @@ export function AuthProvider({ children }: AuthProviderProps) {
     window.history.replaceState({}, document.title, window.location.pathname);
   };
 
-  // Wrap with OIDC provider
+  // Wrap with OIDC provider (shares the UserManager used by the tRPC token lookup)
   return (
-    <OIDCAuthProvider
-      {...settings}
-      onSigninCallback={onSigninCallback}
-    >
+    <OIDCAuthProvider userManager={userManager} onSigninCallback={onSigninCallback}>
       {children}
     </OIDCAuthProvider>
   );
diff --git a/frontend/src/lib/auth/config.ts b/frontend/src/lib/auth/config.ts
index 9f13b3d3..d39939de 100644
--- a/frontend/src/lib/auth/config.ts
+++ b/frontend/src/lib/auth/config.ts
@@ -11,7 +11,7 @@
  * Reference: decision-009 - OIDC Authentication Implementation
  */
 
-import type { UserManagerSettings } from 'oidc-client-ts';
+import { WebStorageStateStore, type UserManagerSettings } from 'oidc-client-ts';
 
 /**
  * Runtime configuration loaded from /config.json
@@ -74,71 +74,11 @@ export async function isOIDCEnabledAsync(): Promise<boolean> {
 }
 
 /**
- * Gets the storage key for manual token storage (sync, build-time only)
- * @deprecated Use getStorageKeyAsync for runtime config support
+ * OIDC login needs a secure context: oidc-client-ts generates the PKCE challenge with
+ * `crypto.subtle`, which browsers only expose on HTTPS or `http://localhost`.
  */
-export function getStorageKey(): string {
-  const authority = import.meta.env.VITE_OIDC_AUTHORITY;
-  const clientId = import.meta.env.VITE_OIDC_CLIENT_ID;
-  return `oidc.user:${authority}:${clientId}`;
-}
-
-/**
- * Gets the storage key for manual token storage (async, supports runtime config)
- */
-export async function getStorageKeyAsync(): Promise<string> {
-  const authority = await getAuthority();
-  const clientId = await getClientId();
-  return `oidc.user:${authority}:${clientId}`;
-}
-
-/**
- * Checks if we have valid manually stored tokens (sync, build-time only)
- * @deprecated Use hasValidManualTokensAsync for runtime config support
- */
-export function hasValidManualTokens(): boolean {
-  try {
-    const storageKey = getStorageKey();
-    const stored = localStorage.getItem(storageKey);
-    if (!stored) return false;
-
-    const data = JSON.parse(stored);
-    if (!data.access_token) return false;
-
-    // Check expiration (with 30 second buffer)
-    if (data.expires_at) {
-      const now = Math.floor(Date.now() / 1000);
-      if (data.expires_at < now + 30) return false;
-    }
-
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Checks if we have valid manually stored tokens (async, supports runtime config)
- */
-export async function hasValidManualTokensAsync(): Promise<boolean> {
-  try {
-    const storageKey = await getStorageKeyAsync();
-    const stored = localStorage.getItem(storageKey);
-    if (!stored) return false;
-
-    const data = JSON.parse(stored);
-    if (!data.access_token) return false;
-
-    // Check expiration (with 30 second buffer)
-    if (data.expires_at) {
-      const now = Math.floor(Date.now() / 1000);
-      if (data.expires_at < now + 30) return false;
-    }
-
-    return true;
-  } catch {
-    return false;
-  }
+export function isSecureContextForOIDC(): boolean {
+  return window.isSecureContext && !!globalThis.crypto?.subtle;
 }
 
 /**
@@ -192,9 +132,13 @@ export async function buildOIDCSettings(): Promise<UserManagerSettings> {
     authority,
     client_id: clientId,
     redirect_uri: `${origin}/callback`,
-    post_logout_redirect_uri: origin,
+    post_logout_redirect_uri: `${origin}/`,
     scope,
 
+    // Keep the session in localStorage (library default is sessionStorage) so it is shared
+    // across tabs and survives a browser restart, like the previous login flow.
+    userStore: new WebStorageStateStore({ store: window.localStorage }),
+
     // Use authorization code flow with PKCE (recommended for SPAs)
     response_type: 'code',
 
diff --git a/frontend/src/lib/auth/index.ts b/frontend/src/lib/auth/index.ts
index c6017470..377b0a43 100644
--- a/frontend/src/lib/auth/index.ts
+++ b/frontend/src/lib/auth/index.ts
@@ -14,10 +14,10 @@ export { AuthProvider } from './AuthProvider';
 export { AuthGuard } from './AuthGuard';
 
 // Re-export configuration utilities
-export { isOIDCEnabled, isOIDCEnabledAsync, getAuthority, getClientId, getScope, hasValidManualTokens, hasValidManualTokensAsync, getStorageKey, getStorageKeyAsync } from './config';
+export { isOIDCEnabled, isOIDCEnabledAsync, isSecureContextForOIDC, getAuthority, getClientId, getScope } from './config';
 
 // Re-export token utilities for tRPC client
-export { getAccessToken, getUser } from './token';
+export { getAccessToken, getUser, getUserManager } from './token';
 
 // Re-export useAuth hook from react-oidc-context
 export { useAuth } from 'react-oidc-context';
diff --git a/frontend/src/lib/auth/token.test.ts b/frontend/src/lib/auth/token.test.ts
index b31ea7cb..fb6ddef9 100644
--- a/frontend/src/lib/auth/token.test.ts
+++ b/frontend/src/lib/auth/token.test.ts
@@ -1,23 +1,25 @@
 /**
- * Tests for the manual OIDC access-token refresh path (TASK-193).
+ * Tests for getAccessToken() on-demand renewal (TASK-193, reworked for PR #7).
  *
- * The production login uses the hand-rolled manual token flow, whose tokens are
- * NOT managed by oidc-client-ts, so they must be refreshed on demand via the
- * stored refresh_token. These tests exercise that path (UserManager mocked to
- * hold no user, so getAccessToken() falls back to manual storage).
+ * Tokens are owned by the single oidc-client-ts UserManager. When the access token is
+ * expired or about to expire, getAccessToken() renews it through the library
+ * (`signinSilent`, single-flight) instead of a hand-rolled token-endpoint call.
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 const STORAGE_KEY = 'oidc.user:https://iam.example/realms/pki:pki-web';
-const AUTHORITY = 'https://iam.example/realms/pki';
-const NOW_SECONDS = 1_000_000;
 
-// NOTE: vi.mock is hoisted above the module's top-level consts, so the factory
-// must use literals (not STORAGE_KEY / AUTHORITY) — they match the consts below.
+// NOTE: vi.mock is hoisted above the module's top-level consts, so factories must use
+// literals or vi.hoisted values.
+const mgr = vi.hoisted(() => ({
+  getUser: vi.fn(),
+  signinSilent: vi.fn(),
+  constructed: 0,
+}));
+
 vi.mock('./config', () => ({
   isOIDCEnabledAsync: vi.fn().mockResolvedValue(true),
-  getStorageKeyAsync: vi.fn().mockResolvedValue('oidc.user:https://iam.example/realms/pki:pki-web'),
   getAuthority: vi.fn().mockResolvedValue('https://iam.example/realms/pki'),
   getClientId: vi.fn().mockResolvedValue('pki-web'),
   buildOIDCSettings: vi
@@ -25,121 +27,121 @@ vi.mock('./config', () => ({
     .mockResolvedValue({ authority: 'https://iam.example/realms/pki', client_id: 'pki-web' }),
 }));
 
-// No library-managed user -> getAccessToken() falls back to manual storage.
 vi.mock('oidc-client-ts', () => ({
   UserManager: class {
-    async getUser() {
-      return null;
+    constructor() {
+      mgr.constructed += 1;
+    }
+    getUser() {
+      return mgr.getUser();
+    }
+    signinSilent() {
+      return mgr.signinSilent();
     }
   },
 }));
 
-import { getAccessToken, resetUserManager, resetTokenRefreshState } from './token';
+import { getAccessToken, getUserManager, resetUserManager, resetTokenRefreshState } from './token';
 
-function setStored(tokens: Record<string, unknown>) {
-  localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
-}
-
-function tokenResponse(body: Record<string, unknown>, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { 'Content-Type': 'application/json' },
-  });
+function user(accessToken: string, expiresIn: number | undefined) {
+  return { access_token: accessToken, expires_in: expiresIn };
 }
 
-describe('getAccessToken — manual token on-demand refresh', () => {
+describe('getAccessToken — library-managed renewal', () => {
   beforeEach(() => {
     localStorage.clear();
     resetUserManager();
     resetTokenRefreshState();
-    vi.spyOn(Date, 'now').mockReturnValue(NOW_SECONDS * 1000);
+    mgr.getUser.mockReset();
+    mgr.signinSilent.mockReset();
+    mgr.constructed = 0;
   });
 
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  it('returns a still-valid token without hitting the token endpoint', async () => {
-    setStored({ access_token: 'valid-abc', refresh_token: 'r1', expires_at: NOW_SECONDS + 600 });
-    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+  it('returns a still-valid token without renewing', async () => {
+    mgr.getUser.mockResolvedValue(user('valid-abc', 600));
 
     await expect(getAccessToken()).resolves.toBe('valid-abc');
-    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(mgr.signinSilent).not.toHaveBeenCalled();
   });
 
-  it('refreshes an expired token via the refresh_token and persists the rotated tokens', async () => {
-    setStored({ access_token: 'old', refresh_token: 'r1', expires_at: NOW_SECONDS - 10 });
-    const fetchSpy = vi
-      .spyOn(globalThis, 'fetch')
-      .mockResolvedValue(
-        tokenResponse({ access_token: 'new-xyz', refresh_token: 'r2', token_type: 'Bearer', expires_in: 300 })
-      );
-
-    await expect(getAccessToken()).resolves.toBe('new-xyz');
-
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
-    const [url, init] = fetchSpy.mock.calls[0];
-    expect(String(url)).toBe(`${AUTHORITY}/protocol/openid-connect/token`);
-    const body = (init as RequestInit).body as URLSearchParams;
-    expect(body.get('grant_type')).toBe('refresh_token');
-    expect(body.get('refresh_token')).toBe('r1');
-    expect(body.get('client_id')).toBe('pki-web');
-
-    const saved = JSON.parse(localStorage.getItem(STORAGE_KEY)!);
-    expect(saved.access_token).toBe('new-xyz');
-    expect(saved.refresh_token).toBe('r2'); // rotated
-    expect(saved.expires_at).toBe(NOW_SECONDS + 300);
+  it('returns null when there is no signed-in user', async () => {
+    mgr.getUser.mockResolvedValue(null);
+
+    await expect(getAccessToken()).resolves.toBeNull();
+    expect(mgr.signinSilent).not.toHaveBeenCalled();
   });
 
-  it('refreshes a token that is within the 60s expiry buffer (not yet expired)', async () => {
-    setStored({ access_token: 'old', refresh_token: 'r1', expires_at: NOW_SECONDS + 30 });
-    const fetchSpy = vi
-      .spyOn(globalThis, 'fetch')
-      .mockResolvedValue(tokenResponse({ access_token: 'fresh', expires_in: 300 }));
+  it('renews a token within the 60s expiry buffer and returns the new one', async () => {
+    mgr.getUser.mockResolvedValue(user('old', 30));
+    mgr.signinSilent.mockResolvedValue(user('renewed', 300));
 
-    await expect(getAccessToken()).resolves.toBe('fresh');
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    await expect(getAccessToken()).resolves.toBe('renewed');
+    expect(mgr.signinSilent).toHaveBeenCalledTimes(1);
   });
 
-  it('deduplicates concurrent refreshes into a single token request (single-flight)', async () => {
-    setStored({ access_token: 'old', refresh_token: 'r1', expires_at: NOW_SECONDS - 10 });
+  it('renews an already-expired token', async () => {
+    mgr.getUser.mockResolvedValue(user('expired', -5));
+    mgr.signinSilent.mockResolvedValue(user('renewed', 300));
+
+    await expect(getAccessToken()).resolves.toBe('renewed');
+  });
 
-    let resolveFetch!: (r: Response) => void;
-    const fetchSpy = vi
-      .spyOn(globalThis, 'fetch')
-      .mockReturnValue(new Promise<Response>((resolve) => {
-        resolveFetch = resolve;
-      }));
+  it('deduplicates concurrent renewals into a single signinSilent call (single-flight)', async () => {
+    mgr.getUser.mockResolvedValue(user('old', 10));
+    let resolve!: (u: unknown) => void;
+    mgr.signinSilent.mockReturnValue(new Promise((r) => (resolve = r)));
 
-    const p1 = getAccessToken();
-    const p2 = getAccessToken();
-    // Let both callers reach the shared single-flight promise, then resolve.
-    await Promise.resolve();
-    resolveFetch(tokenResponse({ access_token: 'shared-new', refresh_token: 'r2', expires_in: 300 }));
+    const calls = Promise.all([getAccessToken(), getAccessToken(), getAccessToken()]);
+    await vi.waitFor(() => expect(mgr.signinSilent).toHaveBeenCalled());
+    resolve(user('renewed', 300));
 
-    await expect(Promise.all([p1, p2])).resolves.toEqual(['shared-new', 'shared-new']);
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    await expect(calls).resolves.toEqual(['renewed', 'renewed', 'renewed']);
+    expect(mgr.signinSilent).toHaveBeenCalledTimes(1);
   });
 
-  it('clears the stored token and returns null when the refresh_token is rejected', async () => {
-    setStored({ access_token: 'old', refresh_token: 'bad', expires_at: NOW_SECONDS - 10 });
-    vi.spyOn(globalThis, 'fetch').mockResolvedValue(tokenResponse({ error: 'invalid_grant' }, 400));
+  it('returns null when renewal fails (session ended at the provider)', async () => {
+    mgr.getUser.mockResolvedValue(user('old', 10));
+    mgr.signinSilent.mockRejectedValue(new Error('login_required'));
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     await expect(getAccessToken()).resolves.toBeNull();
-    expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
   });
 
-  it('returns null when the token is expired and there is no refresh_token', async () => {
-    setStored({ access_token: 'old', expires_at: NOW_SECONDS - 10 });
-    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+  it('shares one UserManager between all callers', async () => {
+    mgr.getUser.mockResolvedValue(user('valid', 600));
 
-    await expect(getAccessToken()).resolves.toBeNull();
-    expect(fetchSpy).not.toHaveBeenCalled();
+    const [a, b] = await Promise.all([getUserManager(), getUserManager()]);
+    await getAccessToken();
+
+    expect(a).toBe(b);
+    expect(mgr.constructed).toBe(1);
   });
+});
 
-  it('returns null when there is no stored token at all', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch');
-    await expect(getAccessToken()).resolves.toBeNull();
-    expect(fetchSpy).not.toHaveBeenCalled();
+describe('legacy manual-token cleanup', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    resetUserManager();
+  });
+
+  it('removes a pre-library token blob (no profile) under the library key', async () => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ access_token: 'legacy', expires_at: 1 }));
+
+    await getUserManager();
+
+    expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
+  });
+
+  it('keeps a library-managed user', async () => {
+    const libraryUser = JSON.stringify({ access_token: 'lib', profile: { sub: 'u1' } });
+    localStorage.setItem(STORAGE_KEY, libraryUser);
+
+    await getUserManager();
+
+    expect(localStorage.getItem(STORAGE_KEY)).toBe(libraryUser);
   });
 });
diff --git a/frontend/src/lib/auth/token.ts b/frontend/src/lib/auth/token.ts
index 9a03ffa3..2e87af96 100644
--- a/frontend/src/lib/auth/token.ts
+++ b/frontend/src/lib/auth/token.ts
@@ -1,64 +1,69 @@
 /**
  * Token Storage Module
  *
- * Provides access to the current access token for use outside React components.
- * Used by tRPC client to inject Authorization headers.
- *
- * The production login uses the hand-rolled manual token flow (see
- * `routes/callback.tsx`), which stores tokens in localStorage but is NOT managed
- * by oidc-client-ts's UserManager — so its `automaticSilentRenew` never fires for
- * these tokens. To avoid unauthenticated (401) requests after the short-lived
- * access token expires mid-session, `getManualAccessToken()` transparently
- * renews the token on demand using the stored `refresh_token` (single-flight).
+ * Owns the single oidc-client-ts `UserManager` shared by the React `AuthProvider` and by
+ * code outside React (the tRPC client, which needs the access token for its
+ * Authorization header). One instance means one token store and one renewal timer, so
+ * the provider's `automaticSilentRenew` and the on-demand renewal below never race each
+ * other with the same refresh token.
  *
  * Reference: decision-009 - OIDC Authentication Implementation
  */
 
 import { UserManager, type User } from 'oidc-client-ts';
-import {
-  buildOIDCSettings,
-  isOIDCEnabledAsync,
-  getStorageKeyAsync,
-  getAuthority,
-  getClientId,
-} from './config';
+import { buildOIDCSettings, isOIDCEnabledAsync, getAuthority, getClientId } from './config';
 
-// Cached UserManager instance
-let userManager: UserManager | null = null;
+// Cached UserManager instance (and the in-flight creation, so concurrent callers share it)
+let userManagerPromise: Promise<UserManager | null> | null = null;
 
 // Renew the token this many seconds before it actually expires, so a request is
 // never sent with a token that lapses in flight.
 const TOKEN_REFRESH_BUFFER_SECONDS = 60;
 
-// Shape of the manual token blob written by the callback / refresh flow.
-interface StoredTokens {
-  access_token?: string;
-  id_token?: string;
-  refresh_token?: string;
-  token_type?: string;
-  expires_at?: number;
-}
-
-// In-flight refresh, shared across concurrent callers (a batched tRPC request
-// calls getAccessToken() once, but window-focus refetches and multiple links can
-// race) so we hit the token endpoint at most once per expiry.
-let refreshPromise: Promise<string | null> | null = null;
+// In-flight renewal, shared across concurrent callers (window-focus refetches and
+// multiple links can race) so we hit the token endpoint at most once per expiry.
+let renewPromise: Promise<User | null> | null = null;
 
 /**
- * Gets or creates the UserManager instance
+ * Drops a token blob left by the pre-3.13 hand-rolled login flow. It used the same
+ * storage key the library uses (`oidc.user:<authority>:<clientId>`) but stored raw
+ * tokens without a `profile`, which the library would otherwise load as a user with
+ * no claims. The affected user simply logs in once more.
  */
-async function getUserManager(): Promise<UserManager | null> {
-  const oidcEnabled = await isOIDCEnabledAsync();
-  if (!oidcEnabled) {
-    return null;
+async function removeLegacyManualTokens(): Promise<void> {
+  const key = `oidc.user:${await getAuthority()}:${await getClientId()}`;
+  const stored = localStorage.getItem(key);
+  if (!stored) {
+    return;
   }
+  try {
+    if (!('profile' in JSON.parse(stored))) {
+      localStorage.removeItem(key);
+    }
+  } catch {
+    localStorage.removeItem(key);
+  }
+}
 
-  if (!userManager) {
-    const settings = await buildOIDCSettings();
-    userManager = new UserManager(settings);
+async function createUserManager(): Promise<UserManager | null> {
+  if (!(await isOIDCEnabledAsync())) {
+    return null;
   }
+  await removeLegacyManualTokens();
+  return new UserManager(await buildOIDCSettings());
+}
 
-  return userManager;
+/**
+ * Gets or creates the shared UserManager instance (null when OIDC is disabled).
+ */
+export function getUserManager(): Promise<UserManager | null> {
+  if (!userManagerPromise) {
+    userManagerPromise = createUserManager().catch((error) => {
+      userManagerPromise = null;
+      throw error;
+    });
+  }
+  return userManagerPromise;
 }
 
 /**
@@ -77,155 +82,64 @@ export async function getUser(): Promise<User | null> {
   }
 }
 
-function readStoredTokens(storageKey: string): StoredTokens | null {
-  const stored = localStorage.getItem(storageKey);
-  if (!stored) {
-    return null;
-  }
-  try {
-    return JSON.parse(stored) as StoredTokens;
-  } catch {
-    return null;
-  }
-}
-
 /**
- * Renews the manually-stored access token using its refresh_token via the
- * OIDC token endpoint (refresh_token grant, public client — no secret).
- *
- * On success the rotated tokens are persisted and the new access token is
- * returned. On failure the stored token is cleared so AuthGuard falls back to a
- * login redirect (the same recovery a full page reload triggers).
+ * Renews the session through the library (refresh_token grant when the provider issued
+ * one, otherwise a silent iframe request). Resolves to null when renewal is impossible
+ * (e.g. the SSO session ended); the library then reports the user as signed out and
+ * AuthGuard redirects to the provider.
  */
-async function refreshManualAccessToken(
-  storageKey: string,
-  refreshToken: string
-): Promise<string | null> {
-  const [authority, clientId] = await Promise.all([getAuthority(), getClientId()]);
+async function renewUser(manager: UserManager): Promise<User | null> {
   try {
-    const response = await fetch(`${authority}/protocol/openid-connect/token`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({
-        grant_type: 'refresh_token',
-        client_id: clientId,
-        refresh_token: refreshToken,
-      }),
-    });
-
-    if (!response.ok) {
-      // The refresh token is invalid/expired (e.g. the SSO session lapsed).
-      // Drop the stale token so the app stops retrying and re-authenticates.
-      console.warn('[Auth] Token refresh failed:', response.status);
-      localStorage.removeItem(storageKey);
-      return null;
-    }
-
-    const tokens = (await response.json()) as {
-      access_token: string;
-      id_token?: string;
-      refresh_token?: string;
-      token_type?: string;
-      expires_in: number;
-    };
-
-    localStorage.setItem(
-      storageKey,
-      JSON.stringify({
-        access_token: tokens.access_token,
-        id_token: tokens.id_token,
-        // Keycloak rotates the refresh token; keep the old one if none returned.
-        refresh_token: tokens.refresh_token ?? refreshToken,
-        token_type: tokens.token_type,
-        expires_at: Math.floor(Date.now() / 1000) + tokens.expires_in,
-      })
-    );
-
-    console.debug('[Auth] Access token refreshed');
-    return tokens.access_token;
+    return await manager.signinSilent();
   } catch (error) {
-    // Network error — leave the stored token in place so a later attempt can
-    // still refresh, and let this request go out unauthenticated (401) rather
-    // than logging the user out on a transient blip.
-    console.warn('[Auth] Token refresh error:', error);
+    console.warn('[Auth] Token renewal failed:', error);
     return null;
   }
 }
 
 /**
- * Gets access token from manual storage
- * Used when tokens were exchanged via manual token flow.
+ * Gets the current access token
+ * Returns null if not authenticated or OIDC is disabled.
  *
- * Transparently refreshes via the stored refresh_token when the token is
- * expired or about to expire, so callers never receive a stale/absent token
- * while the session is still renewable.
+ * Transparently renews the token when it is expired or about to expire, so callers
+ * never receive a stale token while the session is still renewable.
  */
-async function getManualAccessToken(): Promise<string | null> {
-  try {
-    const storageKey = await getStorageKeyAsync();
-    console.debug('[Auth] Looking for token with key:', storageKey);
-    const data = readStoredTokens(storageKey);
-    if (!data?.access_token) {
-      console.debug('[Auth] No token found in localStorage');
-      return null;
-    }
-
-    // Refresh when the token is expired or within the renewal buffer.
-    const now = Math.floor(Date.now() / 1000);
-    const expiringSoon =
-      data.expires_at != null && data.expires_at < now + TOKEN_REFRESH_BUFFER_SECONDS;
-
-    if (expiringSoon) {
-      if (!data.refresh_token) {
-        console.debug('[Auth] Token expired and no refresh_token available');
-        return null;
-      }
-      console.debug('[Auth] Token expiring — refreshing via refresh_token');
-      // Single-flight: share one refresh across concurrent callers.
-      if (!refreshPromise) {
-        refreshPromise = refreshManualAccessToken(storageKey, data.refresh_token).finally(
-          () => {
-            refreshPromise = null;
-          }
-        );
-      }
-      return await refreshPromise;
-    }
-
-    console.debug('[Auth] Valid token found in localStorage');
-    return data.access_token;
-  } catch (error) {
-    console.warn('[Auth] Error retrieving manual access token:', error);
+export async function getAccessToken(): Promise<string | null> {
+  const manager = await getUserManager();
+  if (!manager) {
     return null;
   }
-}
 
-/**
- * Gets the current access token
- * Returns null if not authenticated or OIDC is disabled
- * Checks both library storage and manual token storage
- */
-export async function getAccessToken(): Promise<string | null> {
-  // First try the library's UserManager
   const user = await getUser();
-  if (user?.access_token) {
+  if (!user?.access_token) {
+    return null;
+  }
+
+  const expiringSoon =
+    user.expires_in !== undefined && user.expires_in < TOKEN_REFRESH_BUFFER_SECONDS;
+  if (!expiringSoon) {
     return user.access_token;
   }
 
-  // Fall back to manually stored token (with on-demand refresh)
-  return getManualAccessToken();
+  // Single-flight: share one renewal across concurrent callers.
+  if (!renewPromise) {
+    renewPromise = renewUser(manager).finally(() => {
+      renewPromise = null;
+    });
+  }
+  return (await renewPromise)?.access_token ?? null;
 }
 
 /**
  * Clears the cached UserManager (useful for testing)
  */
 export function resetUserManager(): void {
-  userManager = null;
+  userManagerPromise = null;
 }
 
 /**
- * Clears the in-flight refresh promise (useful for testing).
+ * Clears the in-flight renewal promise (useful for testing).
  */
 export function resetTokenRefreshState(): void {
-  refreshPromise = null;
+  renewPromise = null;
 }
diff --git a/frontend/src/routes/callback.tsx b/frontend/src/routes/callback.tsx
index 73d1aa91..c3ae1071 100644
--- a/frontend/src/routes/callback.tsx
+++ b/frontend/src/routes/callback.tsx
@@ -1,12 +1,17 @@
 /**
  * OIDC Callback Route
  *
- * The actual authorization-code exchange, PKCE validation and token storage
- * are handled by react-oidc-context / oidc-client-ts.
+ * Landing page for the redirect back from the OIDC provider. The authorization-code
+ * exchange, PKCE verification, state/nonce validation and token storage are all done
+ * by react-oidc-context / oidc-client-ts (AuthProvider processes the `code`/`state`
+ * params); this route only shows progress or errors and then returns the user to the
+ * page they originally requested.
+ *
+ * Reference: decision-009 - OIDC Authentication Implementation
  */
 
 import { createFileRoute, useNavigate } from '@tanstack/react-router';
-import { useAuth } from 'react-oidc-context';
+import { useAuth } from '@/lib/auth';
 import { useEffect } from 'react';
 
 export const Route = createFileRoute('/callback')({
@@ -17,14 +22,13 @@ function CallbackRoute() {
   const auth = useAuth();
   const navigate = useNavigate();
 
+  // Once authenticated, redirect to the stored return URL or home
   useEffect(() => {
     if (!auth.isAuthenticated) {
       return;
     }
-
     const returnUrl = sessionStorage.getItem('returnUrl') || '/';
     sessionStorage.removeItem('returnUrl');
-
     navigate({ to: returnUrl });
   }, [auth.isAuthenticated, navigate]);
 
@@ -38,15 +42,8 @@ function CallbackRoute() {
       <div className="min-h-[60vh] flex items-center justify-center">
         <div className="text-center max-w-md p-6">
           <div className="text-destructive text-5xl mb-4">⚠</div>
-
-          <h1 className="text-xl font-semibold mb-2">
-            Authentication Failed
-          </h1>
-
-          <p className="text-muted-foreground mb-4">
-            {auth.error.message}
-          </p>
-
+          <h1 className="text-xl font-semibold mb-2">Authentication Failed</h1>
+          <p className="text-muted-foreground mb-4">{auth.error.message}</p>
           <button
             type="button"
             onClick={handleReturnHome}
@@ -64,14 +61,8 @@ function CallbackRoute() {
       <div className="min-h-[60vh] flex items-center justify-center">
         <div className="text-center">
           <div className="text-green-500 text-5xl mb-4">✓</div>
-
-          <h1 className="text-xl font-semibold mb-2">
-            Sign-in Successful
-          </h1>
-
-          <p className="text-muted-foreground">
-            Redirecting...
-          </p>
+          <h1 className="text-xl font-semibold mb-2">Sign-in Successful</h1>
+          <p className="text-muted-foreground">Redirecting...</p>
         </div>
       </div>
     );
@@ -81,14 +72,8 @@ function CallbackRoute() {
     <div className="min-h-[60vh] flex items-center justify-center">
       <div className="text-center">
         <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
-
-        <h1 className="text-xl font-semibold mb-2">
-          Completing sign-in...
-        </h1>
-
-        <p className="text-muted-foreground">
-          Please wait while we verify your credentials.
-        </p>
+        <h1 className="text-xl font-semibold mb-2">Completing sign-in...</h1>
+        <p className="text-muted-foreground">Please wait while we verify your credentials.</p>
       </div>
     </div>
   );
diff --git a/tests/auth.spec.ts b/tests/auth.spec.ts
index 253901b4..7fa7ddda 100644
--- a/tests/auth.spec.ts
+++ b/tests/auth.spec.ts
@@ -25,8 +25,8 @@ import { test, expect, type Page } from '@playwright/test';
  *   pnpm playwright test tests/auth.spec.ts
  *
  *   # With custom URLs:
- *   PLAYWRIGHT_BASE_URL=http://wsl.ymbihq.local:52080 \
- *   KEYCLOAK_URL=http://wsl.ymbihq.local:42997 \
+ *   PLAYWRIGHT_BASE_URL=http://localhost:52080 \
+ *   KEYCLOAK_URL=http://localhost:42997 \
  *   pnpm playwright test tests/auth.spec.ts
  */
 
@@ -218,15 +218,8 @@ test.describe('Authentication Flow - OIDC Enabled', () => {
     await page.getByRole('button', { name: /admin user/i }).click();
     await page.getByRole('button', { name: /logout/i }).click();
 
-    // Should redirect to Keycloak logout confirmation
-    await page.waitForURL(/.*protocol\/openid-connect\/logout/, {
-      timeout: 10000,
-    });
-
-    // Confirm logout
-    await page.getByRole('button', { name: /logout/i }).click();
-
-    // Should redirect back to login page
+    // signoutRedirect sends id_token_hint, so Keycloak ends the session without a
+    // confirmation page and returns to the app, which redirects to the login page
     await page.waitForURL(/.*realms.*protocol\/openid-connect\/auth/, {
       timeout: 10000,
     });
@@ -479,6 +472,45 @@ test.describe('Session Management', () => {
     expect(tokenData.expires_at).toBeDefined();
   });
 
+  test('an expiring access token is renewed without a new login', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForURL(/.*realms.*protocol\/openid-connect\/auth/, {
+      timeout: 10000,
+    });
+    await keycloakLogin(page, TEST_USER, TEST_PASSWORD);
+    await waitForAppLoaded(page);
+
+    // Make the stored token look like it expires in 10s (inside the 60s renewal buffer)
+    const oldToken = await page.evaluate(() => {
+      const key = Object.keys(localStorage).find((k) => k.startsWith('oidc.user:'))!;
+      const data = JSON.parse(localStorage.getItem(key)!);
+      data.expires_at = Math.floor(Date.now() / 1000) + 10;
+      localStorage.setItem(key, JSON.stringify(data));
+      return data.access_token as string;
+    });
+
+    // Reload: API calls must go out with a renewed token (refresh_token grant), no 401s
+    const unauthorized: string[] = [];
+    page.on('response', (r) => {
+      if (r.url().includes('/trpc') && r.status() === 401) unauthorized.push(r.url());
+    });
+    await page.reload();
+    await waitForAppLoaded(page);
+
+    await expect
+      .poll(
+        () =>
+          page.evaluate(() => {
+            const key = Object.keys(localStorage).find((k) => k.startsWith('oidc.user:'))!;
+            return JSON.parse(localStorage.getItem(key)!).access_token as string;
+          }),
+        { timeout: 15000 }
+      )
+      .not.toBe(oldToken);
+    expect(page.url()).not.toContain('realms');
+    expect(unauthorized).toEqual([]);
+  });
+
   test('logout clears tokens from localStorage', async ({ page }) => {
     // Login
     await page.goto('/');
@@ -498,12 +530,8 @@ test.describe('Session Management', () => {
     // Logout
     await page.getByRole('button', { name: /admin user/i }).click();
     await page.getByRole('button', { name: /logout/i }).click();
-    await page.waitForURL(/.*protocol\/openid-connect\/logout/, {
-      timeout: 10000,
-    });
-    await page.getByRole('button', { name: /logout/i }).click();
 
-    // Wait for redirect back to login
+    // Wait for redirect back to login (no Keycloak confirmation page: id_token_hint is sent)
     await page.waitForURL(/.*realms.*protocol\/openid-connect\/auth/, {
       timeout: 10000,
     });

From 6d8f91e640446f8400955072530e3f759eef283c Mon Sep 17 00:00:00 2001
From: Oriol Rius <oriol@joor.net>
Date: Wed, 21 Oct 2026 17:11:17 +0200
Subject: [PATCH 5/5] build(dev): run the dev stack on localhost only (drop
 wsl.ymbihq.local)

OIDC login now needs a secure context (HTTPS or localhost), so the dev stack
uses http://localhost everywhere:

- vite: drop the *.ymbihq.local allowedHosts (Vite's default allows
  localhost and IP addresses).
- dev realm pki-web client: only localhost:52080 / :8080 redirect URIs and
  web origins. PKCE S256 is required and post-logout redirects are allowed.
- .env.example files now match the real dev ports (52080/52081), so
  `cp .env.example .env && pnpm dev` works as-is.
- KMS_URL defaults: localhost:42998.
- Docs (DEVELOPMENT/CLAUDE/README/keycloak README) and test usage examples
  updated. Document how a Windows localhost reaches WSL (localhostForwarding
  or loopback-only netsh portproxy).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                          |  5 ++--
 DEVELOPMENT.md                     | 40 +++++++++++++++++++++---------
 README.md                          |  4 +--
 backend/.env.example               |  6 ++---
 backend/CLAUDE.md                  |  2 +-
 backend/src/kms/service.ts         |  2 +-
 backend/src/kms/spike-ssh-ecies.ts |  2 +-
 backend/src/kms/spike-ssh-sign.ts  |  2 +-
 frontend/.env.example              |  2 +-
 frontend/vite.config.ts            |  8 +++---
 keycloak/README.md                 |  2 +-
 keycloak/pki-dev-realm.json        | 18 ++++++++------
 tests/auth-m2m.spec.ts             |  4 +--
 13 files changed, 57 insertions(+), 40 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index fd8bf32d..4b4c6a1e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -117,8 +117,9 @@ you can run `pnpm dev` headlessly (no `Stdin is not a tty`) and then read the st
 `backlog browser` on 6430) needs a socat relay. That doc also has the real port table,
 verify commands, and the cleanup recipe.
 
-The committed dev config targets `*.ymbihq.local` on the `42xxx`/`52xxx` port range — see
-[frontend/CLAUDE.md](frontend/CLAUDE.md) and edit the `.env` files for local-only dev.
+The dev stack runs on **`http://localhost`** (`42xxx`/`52xxx` ports, IPv4 binds, so the same
+URLs work in Orca's and in the Windows browser). Use `localhost`, never a LAN/WSL hostname:
+OIDC login needs a secure context (HTTPS or localhost) — see [frontend/CLAUDE.md](frontend/CLAUDE.md).
 Details: [DEVELOPMENT.md](DEVELOPMENT.md) (dev), [DEPLOYMENT.md](DEPLOYMENT.md) (Docker),
 [KEYCLOAK.md](KEYCLOAK.md) / [OIDC.md](OIDC.md) (auth).
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 2535b9ae..83f5c6a9 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -31,14 +31,20 @@ pnpm dev
 
 ### Dev stack ports
 
-The committed dev config targets `*.ymbihq.local` on the `42xxx`/`52xxx` range
+The dev stack runs on **`localhost`** on the `42xxx`/`52xxx` range
 (`backend/.env`, `frontend/.env`, `frontend/vite.config.ts`) — **not** the 3000/5173
-defaults.
+defaults. Everything binds IPv4 `0.0.0.0`, so WSL2 forwards each port to Windows and the
+same `http://localhost:PORT` URLs work in Orca's browser **and** in any Windows browser.
+
+**Use `localhost`, not a LAN/WSL hostname.** OIDC login (PKCE) needs `crypto.subtle`, which
+browsers only expose in a secure context — HTTPS or `http://localhost`. Over plain HTTP on
+any other name (e.g. the old `wsl.ymbihq.local`) the app shows *"Login requires a secure
+context"*. Production must be served over HTTPS.
 
 | Service | URL | Bound by |
 |---|---|---|
-| Frontend (Vite) | http://wsl.ymbihq.local:52080 | `frontend/vite.config.ts` (`host: '0.0.0.0'`) |
-| Backend (Fastify) | http://wsl.ymbihq.local:52081 — Swagger at `/api/docs` | `backend/.env` `PORT`/`HOST` |
+| Frontend (Vite) | http://localhost:52080 | `frontend/vite.config.ts` (`host: '0.0.0.0'`) |
+| Backend (Fastify) | http://localhost:52081 — Swagger at `/api/docs` | `backend/.env` `PORT`/`HOST` |
 | Cosmian KMS | http://localhost:42998 | `kms/docker-compose.yml` |
 | Keycloak | http://localhost:42997 (admin/admin) | `keycloak/docker-compose.yml` |
 | Backlog.md web UI | http://localhost:6430 | `backlog/config.yml` `defaultPort` |
@@ -104,9 +110,19 @@ serving fine — probe the HTTP endpoints, don't trust the healthcheck label.
 
 ### WSL2 / Windows reachability gotcha
 
-The Orca browser and the user resolve `localhost` on **Windows**, and WSL2 only forwards
-**IPv4 (`0.0.0.0`)** binds. A server on the IPv6 wildcard (`*:PORT` in `ss`) works from
-inside WSL but gives `ERR_EMPTY_RESPONSE` / a `chrome-error://` page in the browser.
+The Orca browser and the user resolve `localhost` on **Windows**. How a Windows
+`localhost:PORT` reaches WSL depends on the machine:
+
+- **WSL default (`localhostForwarding=true`)**: WSL2 forwards **IPv4 (`0.0.0.0`)** binds
+  automatically. A server on the IPv6 wildcard (`*:PORT` in `ss`) works from inside WSL
+  but gives `ERR_EMPTY_RESPONSE` / a `chrome-error://` page in the browser.
+- **d0 (`localhostForwarding=false` in `%USERPROFILE%\.wslconfig`, on purpose)**: ports are
+  exposed with `netsh portproxy` rules instead. The dev stack's browser-facing ports are
+  forwarded loopback-only (`127.0.0.1:PORT → wsl.ymbihq.local:PORT`, not reachable from the
+  LAN) by `C:\tools\private\add-pki-manager-dev-ports.ps1` (elevated, additive):
+  **52080** frontend, **52081** API, **42997** Keycloak, **52091** backlog relay. A new
+  browser-facing port needs a rule there too. Check with
+  `netsh.exe interface portproxy show v4tov4`.
 
 - Backend and frontend already bind `0.0.0.0` — fine as-is.
 - **`backlog browser` binds the IPv6 wildcard on 6430** and has no `--host` flag, so it
@@ -180,7 +196,7 @@ HOST=0.0.0.0
 NODE_ENV=development
 
 # Frontend URL for CORS
-FRONTEND_URL=http://wsl.ymbihq.local:52080/
+FRONTEND_URL=http://localhost:52080
 
 # Database
 DATABASE_PATH=./data/pki.db
@@ -192,7 +208,7 @@ KMS_URL=http://localhost:42998
 ALLOW_UNAUTHENTICATED_SSH_CA=true
 
 # CRL Distribution Point
-CRL_DISTRIBUTION_URL=http://wsl.ymbihq.local:52081/crl
+CRL_DISTRIBUTION_URL=http://localhost:52081/crl
 ```
 
 With no `OIDC_ISSUER`/`OIDC_AUDIENCE` set the backend runs **fully unauthenticated** and
@@ -202,7 +218,7 @@ when the Keycloak container is up. See [OIDC.md](OIDC.md) to enable it.
 ### Frontend (`frontend/.env`)
 
 ```env
-VITE_API_URL=http://wsl.ymbihq.local:52081/trpc
+VITE_API_URL=http://localhost:52081/trpc
 ```
 
 ## Development Servers
@@ -223,8 +239,8 @@ Use this when you can't give mprocs a TTY (scripts, agents, CI-ish runs):
 |----------|-----------|---------|-----|
 | 1 | `kms/` | `docker compose up -d` | http://localhost:42998 |
 | 2 | `keycloak/` | `docker compose up -d` | http://localhost:42997 |
-| 3 | `backend/` | `pnpm dev` | http://wsl.ymbihq.local:52081 |
-| 4 | `frontend/` | `pnpm dev` | http://wsl.ymbihq.local:52080 |
+| 3 | `backend/` | `pnpm dev` | http://localhost:52081 |
+| 4 | `frontend/` | `pnpm dev` | http://localhost:52080 |
 | 5 | repo root | `backlog browser --no-open` | http://localhost:6430 |
 
 ## Available Scripts
diff --git a/README.md b/README.md
index 4d09bbb6..935e9473 100644
--- a/README.md
+++ b/README.md
@@ -347,8 +347,8 @@ cd backend && pnpm db:migrate
 pnpm dev  # from root
 ```
 
-- **Frontend**: http://localhost:5173
-- **Backend API**: http://localhost:3000
+- **Frontend**: http://localhost:52080
+- **Backend API**: http://localhost:52081
 - **Cosmian KMS**: http://localhost:42998
 - **Keycloak**: http://localhost:42997 (admin/admin)
 
diff --git a/backend/.env.example b/backend/.env.example
index eef189ea..fc5069c8 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -1,10 +1,10 @@
 # Server Configuration
-PORT=3000
+PORT=52081
 HOST=0.0.0.0
 NODE_ENV=development
 
 # Frontend URL for CORS
-FRONTEND_URL=http://localhost:5173
+FRONTEND_URL=http://localhost:52080
 
 # Database
 DATABASE_PATH=./data/pki.db
@@ -16,7 +16,7 @@ KMS_URL=http://localhost:42998
 # CRL Distribution Point URL (for X.509 certificates)
 # Format: http://your-domain.com/crl/{caId}.crl
 # Example: http://crl.example.com/crl/{caId}.crl
-CRL_DISTRIBUTION_URL=http://localhost:3000/crl
+CRL_DISTRIBUTION_URL=http://localhost:52081/crl
 
 # =============================================================================
 # OIDC Authentication Configuration
diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md
index e4334eae..5da0a2aa 100644
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@@ -68,7 +68,7 @@ trusts only its own zone's user CAs (`ssh-host-krl.service` narrows the composed
 ## Gotchas
 
 - **KMS is a hard dependency** for almost all CA/cert paths; unreachable → most ops fail
-  (`CAKmsInconsistencyError`). `getKMSService()` defaults `KMS_URL` to `http://wsl.ymbihq.local:42998`.
+  (`CAKmsInconsistencyError`). `getKMSService()` defaults `KMS_URL` to `http://localhost:42998`.
 - KMS `certify` modes: pass a `publicKeyId` to certify a KMS-held key (CA creation, manual
   issuance); pass a `csr` + `preserveCsrKey` to sign a CSR's **own** public key (the external
   `/sign` path — the CA key stays in the KMS). The CSR goes in the KMIP `CertificateRequestValue`
diff --git a/backend/src/kms/service.ts b/backend/src/kms/service.ts
index f6c547cd..8b4fcf22 100644
--- a/backend/src/kms/service.ts
+++ b/backend/src/kms/service.ts
@@ -561,7 +561,7 @@ let kmsServiceInstance: KMSService | null = null;
  */
 export function getKMSService(): KMSService {
   if (!kmsServiceInstance) {
-    const kmsUrl = process.env.KMS_URL || 'http://wsl.ymbihq.local:42998';
+    const kmsUrl = process.env.KMS_URL || 'http://localhost:42998';
 
     kmsServiceInstance = new KMSService({
       kmsUrl,
diff --git a/backend/src/kms/spike-ssh-ecies.ts b/backend/src/kms/spike-ssh-ecies.ts
index ef5dabf5..2314327d 100644
--- a/backend/src/kms/spike-ssh-ecies.ts
+++ b/backend/src/kms/spike-ssh-ecies.ts
@@ -13,7 +13,7 @@ import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-const KMS_URL = (process.env.KMS_URL || 'http://wsl.ymbihq.local:42998').replace(/\/$/, '');
+const KMS_URL = (process.env.KMS_URL || 'http://localhost:42998').replace(/\/$/, '');
 const COSMIAN = process.env.COSMIAN_BIN || 'cosmian';
 const cosmian = (args: string[]) => execFileSync(COSMIAN, ['--kms-url', KMS_URL, 'kms', ...args], { encoding: 'utf8' });
 
diff --git a/backend/src/kms/spike-ssh-sign.ts b/backend/src/kms/spike-ssh-sign.ts
index e8a5d7a1..e901486d 100644
--- a/backend/src/kms/spike-ssh-sign.ts
+++ b/backend/src/kms/spike-ssh-sign.ts
@@ -25,7 +25,7 @@ import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const KMS_URL = (process.env.KMS_URL || "http://wsl.ymbihq.local:42998").replace(/\/$/, "");
+const KMS_URL = (process.env.KMS_URL || "http://localhost:42998").replace(/\/$/, "");
 const COSMIAN_BIN = process.env.COSMIAN_BIN || "cosmian";
 
 type Probe = { path: string; ok: boolean; detail: string };
diff --git a/frontend/.env.example b/frontend/.env.example
index 57ab398d..21d40564 100644
--- a/frontend/.env.example
+++ b/frontend/.env.example
@@ -1,5 +1,5 @@
 # Backend API URL
-VITE_API_URL=http://localhost:3000/trpc
+VITE_API_URL=http://localhost:52081/trpc
 
 # =============================================================================
 # OIDC Authentication Configuration
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 8c4c0136..27e96038 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -20,10 +20,8 @@ export default defineConfig({
     // Fail loudly instead of silently hopping to 52082 when a stale dev server
     // still owns the port — a shifted port is how you end up with two stacks.
     strictPort: true,
-    allowedHosts: [
-      'wsl.ymbihq.local',
-      'localhost',
-      '.ymbihq.local', // Allow all subdomains
-    ],
+    // No allowedHosts: Vite's default (localhost + IP literals) is exactly what dev needs.
+    // Open the app as http://localhost:52080 — WSL2 forwards it to the Windows browser,
+    // and localhost is a secure context, which OIDC login (PKCE / crypto.subtle) requires.
   },
 })
diff --git a/keycloak/README.md b/keycloak/README.md
index 9ff4c46e..0d7f6ddc 100644
--- a/keycloak/README.md
+++ b/keycloak/README.md
@@ -135,7 +135,7 @@ curl -X POST http://localhost:42997/realms/pki-dev/protocol/openid-connect/token
 ### Authorization Code Flow (pki-web)
 
 For web application authentication, use the `pki-web` client with redirect URIs:
-- `http://localhost:5173/*` (Vite dev server)
+- `http://localhost:52080/*` (Vite dev server)
 - `http://localhost:8080/*` (Production frontend)
 
 ## Persistent Data
diff --git a/keycloak/pki-dev-realm.json b/keycloak/pki-dev-realm.json
index 143b46ff..c9314b53 100644
--- a/keycloak/pki-dev-realm.json
+++ b/keycloak/pki-dev-realm.json
@@ -52,17 +52,15 @@
       "standardFlowEnabled": true,
       "directAccessGrantsEnabled": true,
       "serviceAccountsEnabled": false,
-      "rootUrl": "http://localhost:5173",
+      "rootUrl": "http://localhost:52080",
       "baseUrl": "/",
       "redirectUris": [
-        "http://localhost:5173/*",
-        "http://localhost:8080/*",
-        "http://wsl.ymbihq.local:52080/*"
+        "http://localhost:52080/*",
+        "http://localhost:8080/*"
       ],
       "webOrigins": [
-        "http://localhost:5173",
-        "http://localhost:8080",
-        "http://wsl.ymbihq.local:52080"
+        "http://localhost:52080",
+        "http://localhost:8080"
       ],
       "defaultClientScopes": [
         "web-origins",
@@ -72,7 +70,11 @@
       ],
       "optionalClientScopes": [
         "offline_access"
-      ]
+      ],
+      "attributes": {
+        "pkce.code.challenge.method": "S256",
+        "post.logout.redirect.uris": "+"
+      }
     }
   ],
   "users": [
diff --git a/tests/auth-m2m.spec.ts b/tests/auth-m2m.spec.ts
index 8a590750..844f5cfe 100644
--- a/tests/auth-m2m.spec.ts
+++ b/tests/auth-m2m.spec.ts
@@ -16,8 +16,8 @@ import { test, expect } from '@playwright/test';
  *   KEYCLOAK_URL - Keycloak base URL (default: http://localhost:42997)
  *
  * Usage:
- *   BACKEND_URL=http://wsl.ymbihq.local:52081 \
- *   KEYCLOAK_URL=http://wsl.ymbihq.local:42997 \
+ *   BACKEND_URL=http://localhost:52081 \
+ *   KEYCLOAK_URL=http://localhost:42997 \
  *   pnpm playwright test tests/auth-m2m.spec.ts
  */