fix(auth/ux): cause-aware OIDC + session error surfacing (HIGH-7 + HIGH-8 closure)

Server (HIGH-7): the OIDC callback failure path now 302-redirects to
/login?error=oidc_failed&reason=<category> instead of emitting a blank
400. `category` is the existing audit `failure_category` value;
classifyOIDCFailure was extended with three new sentinel paths
(email_domain_not_allowed, email_missing_but_required, pkce_invalid)
so CRIT-5 + PKCE failures get distinguishable GUI rendering.
Audit-log observability is unchanged — the same failure_category is
written to the auth.oidc_login_failed audit row; the 302 is purely a
UX leg layered on top.

Server (HIGH-8): SessionMiddleware now stashes a cause classification
on the request context when Validate returns an error, mapping the
sentinels via classifySessionError (errors.Is-based, so wrapped
sentinels still classify) to the stable wire-strings idle_timeout /
absolute_timeout / back_channel_revoked / invalid_token. The 401
emit point in bearerSkipIfAuthenticated reads the stashed cause and
emits WWW-Authenticate: Bearer realm="certctl", error="invalid_token",
error_description=<cause> per RFC 6750 §3.

GUI (HIGH-7): LoginPage reads ?error= + ?reason= from the URL via
react-router useSearchParams and renders an operator-friendly
amber-bordered banner above the form; OIDC_FAILURE_REASON_TEXT maps
all 16 known categories with a defensive 'unspecified' fallback for
forward-compat with future server-side categories.

GUI (HIGH-8): api/client fetchJSON parses the WWW-Authenticate cause
via parseWWWAuthenticateCause and attaches it to the
'certctl:auth-required' CustomEvent detail; AuthProvider redirects
to /login?session_expired=<cause> on cause-aware 401s; LoginPage
renders a blue-bordered session-cause banner. invalid_token stays
on the current page (no hard redirect for opaque failures).

Misc cleanup: ErrorState now accepts the title/message/data-testid
form added by CRIT-4 BreakglassPage (was erroring tsc on master).

Regression matrix:
- internal/api/handler/oidc_redirect_categories_test.go pins all 16
  failure categories to the 302 + reason= location + audit-row leg
- internal/auth/session/www_authenticate_test.go pins the 4 stable
  cause categories on classifySessionError (incl. errors.Is wrapped
  sentinels) + the WWW-Authenticate emission across all 4 categories
  + the no-session-context fallback case
- internal/api/handler/auth_session_oidc_test.go: 4 pre-existing
  TestLoginCallback_*Returns400 tests updated to assert 302 + reason=
  location (the wire shape changed from 400 to 302, but the audit
  observability and behaviour-equivalent failure-classification are
  preserved)
- web/src/pages/LoginPage.test.tsx: 6 new cases pinning the failure
  banner, session-cause banner, unknown-reason fallback, and
  forward-compat 'unspecified' category

Spec: cowork/auth-bundles-fixes-2026-05-10/08-high-7-8-error-surfacing.md
Closes: HIGH-7, HIGH-8 of cowork/auth-bundles-audit-2026-05-10.md

web/src/api/client.ts

@@ -72,6 +72,31 @@ function readCSRFCookie(): string {
   return '';
 }
 
+// Audit 2026-05-10 HIGH-8 — extract the session-failure cause from the
+// WWW-Authenticate header the server emits on 401. The server format
+// (RFC 6750 §3) is: `Bearer realm="certctl", error="invalid_token",
+// error_description="<cause>"` where <cause> is one of the stable
+// categories `idle_timeout` / `absolute_timeout` /
+// `back_channel_revoked` / `invalid_token`. Returns "" when the
+// header is missing, malformed, or carries an unrecognised cause —
+// the AuthProvider falls back to the generic "Session expired" UX
+// in that case (forward-compat with future categories).
+function parseWWWAuthenticateCause(header: string | null): string {
+  if (!header) return '';
+  const m = header.match(/error_description="([^"]+)"/i);
+  if (!m) return '';
+  const cause = m[1];
+  switch (cause) {
+    case 'idle_timeout':
+    case 'absolute_timeout':
+    case 'back_channel_revoked':
+    case 'invalid_token':
+      return cause;
+    default:
+      return '';
+  }
+}
+
 // isStateChangingMethod mirrors the server-side
 // internal/auth/session/middleware.go::isStateChangingMethod predicate.
 // State-changing requests get the X-CSRF-Token header auto-attached
@@ -106,8 +131,14 @@ async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
     headers, // intentional: spread init first, then override headers with the merged map (init.headers already merged into `headers` above)
   });
   if (res.status === 401) {
-    // Trigger re-auth
-    const event = new CustomEvent('certctl:auth-required');
+    // Audit 2026-05-10 HIGH-8 — propagate the WWW-Authenticate
+    // error_description so the AuthProvider can route the user into
+    // OIDC-aware re-login UX instead of generic "session expired."
+    // Stable cause categories: idle_timeout, absolute_timeout,
+    // back_channel_revoked, invalid_token. Anything else is treated
+    // as invalid_token by the server-side classifier.
+    const cause = parseWWWAuthenticateCause(res.headers.get('WWW-Authenticate'));
+    const event = new CustomEvent('certctl:auth-required', { detail: { cause } });
     window.dispatchEvent(event);
     throw new Error('Authentication required');
   }
@@ -827,7 +858,9 @@ export const retireAgent = async (
   });
 
   if (res.status === 401) {
-    window.dispatchEvent(new CustomEvent('certctl:auth-required'));
+    // Audit 2026-05-10 HIGH-8 — see fetchAPI() for the cause-extraction rationale.
+    const cause = parseWWWAuthenticateCause(res.headers.get('WWW-Authenticate'));
+    window.dispatchEvent(new CustomEvent('certctl:auth-required', { detail: { cause } }));
     throw new Error('Authentication required');
   }
 

web/src/components/AuthProvider.tsx

@@ -66,14 +66,35 @@ export default function AuthProvider({ children }: { children: ReactNode }) {
       .finally(() => setLoading(false));
   }, []);
 
-  // Listen for 401 events from the API client
+  // Listen for 401 events from the API client.
+  //
+  // Audit 2026-05-10 HIGH-8 — the API client now attaches a cause
+  // category to the event detail (parsed from the WWW-Authenticate
+  // header). When a cause is recognised, redirect to
+  // /login?session_expired=<cause> so the LoginPage renders OIDC-aware
+  // re-login wording instead of the generic "session expired" + API-key
+  // copy. Cookie-mode (OIDC) and Bearer-mode (API-key) callers share
+  // the same wire shape; the LoginPage banner is purely UX.
   useEffect(() => {
-    const handler = () => {
+    const handler = (e: Event) => {
+      const detail = (e as CustomEvent<{ cause?: string }>).detail;
+      const cause = detail?.cause || '';
       setAuthenticated(false);
       setApiKey(null);
       setUser('');
       setAdmin(false);
+      // Generic copy; the LoginPage will overlay a cause-specific
+      // banner when ?session_expired=<cause> is present.
       setError('Session expired. Please re-enter your API key.');
+      // Forward the cause to the LoginPage. window.location is used
+      // (not React Router's navigate) because this listener fires
+      // outside any route component's render and we want a hard
+      // navigation that clears any stale state.
+      if (cause && cause !== 'invalid_token' &&
+          window.location.pathname !== '/login') {
+        const params = new URLSearchParams({ session_expired: cause });
+        window.location.href = '/login?' + params.toString();
+      }
     };
     window.addEventListener('certctl:auth-required', handler);
     return () => window.removeEventListener('certctl:auth-required', handler);

web/src/components/ErrorState.tsx

@@ -1,16 +1,39 @@
+// ErrorState supports two call shapes:
+//   1. error-object form: <ErrorState error={err} onRetry={fn} />
+//   2. title+message form: <ErrorState title="…" message="…" data-testid="…" />
+//
+// The title/message form was added by Audit 2026-05-10 CRIT-4
+// (BreakglassPage admin GUI) so pages can render a denied/disabled
+// banner without manufacturing a synthetic Error. When `title` is
+// supplied, it takes precedence over the default headline; when
+// `message` is supplied, it takes precedence over `error.message`.
 interface ErrorStateProps {
-  error: Error;
+  error?: Error;
   onRetry?: () => void;
+  title?: string;
+  message?: string;
+  'data-testid'?: string;
 }
 
-export default function ErrorState({ error, onRetry }: ErrorStateProps) {
+export default function ErrorState({
+  error,
+  onRetry,
+  title,
+  message,
+  'data-testid': dataTestid,
+}: ErrorStateProps) {
+  const headline = title ?? 'Failed to load data';
+  const detail = message ?? error?.message ?? '';
   return (
-    <div className="flex flex-col items-center justify-center py-16 text-ink-muted">
+    <div
+      className="flex flex-col items-center justify-center py-16 text-ink-muted"
+      data-testid={dataTestid}
+    >
       <svg className="w-12 h-12 text-red-700 mb-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
         <path strokeLinecap="round" strokeLinejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z" />
       </svg>
-      <p className="text-sm mb-2 text-ink">Failed to load data</p>
-      <p className="text-xs text-ink-faint mb-4">{error.message}</p>
+      <p className="text-sm mb-2 text-ink">{headline}</p>
+      {detail && <p className="text-xs text-ink-faint mb-4">{detail}</p>}
       {onRetry && (
         <button onClick={onRetry} className="btn btn-primary text-xs">
           Retry

web/src/pages/LoginPage.test.tsx

@@ -141,4 +141,83 @@ describe('LoginPage — render + XSS hardening (M-026 / M-029 Pass 3)', () => {
     });
     expect(screen.queryByTestId('login-oidc-providers')).toBeNull();
   });
+
+  // Audit 2026-05-10 HIGH-7 — when the OIDC callback path redirects
+  // here with ?error=oidc_failed&reason=<category>, the page renders
+  // an operator-friendly cause banner instead of leaving the user
+  // staring at a blank form.
+  it('renders OIDC failure banner when ?error=oidc_failed&reason=email_domain_not_allowed (HIGH-7)', async () => {
+    render(
+      <MemoryRouter initialEntries={['/login?error=oidc_failed&reason=email_domain_not_allowed']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId('login-oidc-failure-banner')).toBeTruthy();
+    });
+    const banner = screen.getByTestId('login-oidc-failure-banner');
+    expect(banner.getAttribute('data-reason')).toBe('email_domain_not_allowed');
+    expect(banner.textContent).toContain('email domain is not in the configured allowlist');
+  });
+
+  it('falls back to unspecified text when ?reason= is unknown (HIGH-7 forward-compat)', async () => {
+    render(
+      <MemoryRouter initialEntries={['/login?error=oidc_failed&reason=newcat_from_future_release']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId('login-oidc-failure-banner')).toBeTruthy();
+    });
+    const banner = screen.getByTestId('login-oidc-failure-banner');
+    expect(banner.textContent).toContain('OIDC sign-in failed');
+  });
+
+  it('does NOT render the OIDC failure banner without the error query param', () => {
+    render(
+      <MemoryRouter initialEntries={['/login']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    expect(screen.queryByTestId('login-oidc-failure-banner')).toBeNull();
+  });
+
+  // Audit 2026-05-10 HIGH-8 — session-expired causes routed via
+  // ?session_expired=<cause> render an OIDC-aware re-login banner.
+  it('renders session-cause banner when ?session_expired=back_channel_revoked (HIGH-8)', async () => {
+    render(
+      <MemoryRouter initialEntries={['/login?session_expired=back_channel_revoked']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId('login-session-cause-banner')).toBeTruthy();
+    });
+    const banner = screen.getByTestId('login-session-cause-banner');
+    expect(banner.getAttribute('data-cause')).toBe('back_channel_revoked');
+    expect(banner.textContent).toContain('back-channel logout');
+  });
+
+  it('renders idle-timeout cause banner when ?session_expired=idle_timeout (HIGH-8)', async () => {
+    render(
+      <MemoryRouter initialEntries={['/login?session_expired=idle_timeout']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId('login-session-cause-banner')).toBeTruthy();
+    });
+    expect(screen.getByTestId('login-session-cause-banner').textContent).toContain(
+      'timed out from inactivity',
+    );
+  });
+
+  it('does NOT render the session-cause banner for an unknown cause', () => {
+    render(
+      <MemoryRouter initialEntries={['/login?session_expired=zzz_unknown_cause']}>
+        <LoginPage />
+      </MemoryRouter>,
+    );
+    expect(screen.queryByTestId('login-session-cause-banner')).toBeNull();
+  });
 });

web/src/pages/LoginPage.tsx

@@ -1,8 +1,49 @@
 import { useState, useEffect } from 'react';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate, useSearchParams } from 'react-router-dom';
 import { useAuth } from '../components/AuthProvider';
 import { getAuthInfo, breakglassLogin, type AuthInfoOIDCProvider } from '../api/client';
 
+// Audit 2026-05-10 HIGH-7 closure — operator-friendly cause text for
+// each value the OIDC callback handler emits in the redirect's
+// `?reason=<category>` query param. Keys MUST match the categories
+// produced by `internal/api/handler/auth_session_oidc.go::classifyOIDCFailure`
+// — see TestLoginCallback_RedirectsWithReason_AllCategories for the
+// authoritative list.
+const OIDC_FAILURE_REASON_TEXT: Record<string, string> = {
+  pre_login_consume_failed:
+    'The login attempt was already used or expired. Try signing in again.',
+  state_mismatch:
+    'The OIDC callback was rejected (state mismatch). Try again from a single browser tab.',
+  nonce_mismatch:
+    'The OIDC callback was rejected (nonce mismatch). Try again from a single browser tab.',
+  audience_mismatch:
+    'The IdP returned a token addressed to a different audience. Check the client_id on the OIDC provider.',
+  token_expired:
+    'The IdP-issued token expired before the callback completed. Check server clock skew and try again.',
+  azp_mismatch:
+    'The IdP returned a token with an unexpected authorized party. Check the client_id binding.',
+  at_hash_mismatch:
+    'The access-token hash did not match. Check the IdP signing-algorithm settings.',
+  iat_window:
+    'The IdP-issued token claims a future or stale issued-at time. Check server clock skew.',
+  alg_rejected:
+    'The IdP signed the token with an algorithm that is not in the certctl allowlist. Check the OIDC provider configuration.',
+  unmapped_groups:
+    'You signed in successfully, but none of your groups map to a certctl role. Ask your administrator to add a group mapping.',
+  groups_missing:
+    'The IdP did not return a groups claim. Ask your administrator to enable the groups scope on the OIDC client.',
+  jwks_unreachable:
+    'certctl could not fetch the IdP signing keys (JWKS). Check network connectivity from the server to the IdP.',
+  email_domain_not_allowed:
+    'Your email domain is not in the configured allowlist for this OIDC provider. Ask your administrator to add it.',
+  email_missing_but_required:
+    'The IdP did not return an email claim. Ask your administrator to enable the email scope on the OIDC client.',
+  pkce_invalid:
+    'The PKCE verifier did not match the challenge. Try signing in again from a single browser tab.',
+  unspecified:
+    'OIDC sign-in failed. Try again, or check the server audit log for the failure category.',
+};
+
 // =============================================================================
 // LoginPage — Bundle 2 Phase 8 / multi-mode entry surface.
 //
@@ -23,11 +64,42 @@ import { getAuthInfo, breakglassLogin, type AuthInfoOIDCProvider } from '../api/
 export default function LoginPage() {
   const { login, error: authError } = useAuth();
   const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
   const [key, setKey] = useState('');
   const [submitting, setSubmitting] = useState(false);
   const [localError, setLocalError] = useState<string | null>(null);
   const [providers, setProviders] = useState<AuthInfoOIDCProvider[]>([]);
 
+  // Audit 2026-05-10 HIGH-7 closure — when the OIDC callback path
+  // redirects here with `?error=oidc_failed&reason=<category>`, render
+  // an operator-friendly cause banner. The reason maps via
+  // OIDC_FAILURE_REASON_TEXT; unknown reasons fall back to the
+  // `unspecified` text (defensive against new server categories).
+  const oidcError = searchParams.get('error');
+  const oidcReason = searchParams.get('reason') || '';
+  const oidcReasonText =
+    oidcError === 'oidc_failed'
+      ? OIDC_FAILURE_REASON_TEXT[oidcReason] ||
+        OIDC_FAILURE_REASON_TEXT.unspecified
+      : null;
+
+  // Audit 2026-05-10 HIGH-8 closure — when the AuthProvider redirects
+  // to /login because a session 401'd with a recognised cause, it
+  // attaches `?session_expired=<idle_timeout|absolute_timeout|back_channel_revoked>`
+  // so we can render OIDC-aware re-login wording instead of the
+  // generic API-key UX. See AuthProvider.tsx for the WWW-Authenticate
+  // parser.
+  const sessionCause = searchParams.get('session_expired') || '';
+  const sessionCauseText =
+    {
+      idle_timeout:
+        'Your session timed out from inactivity. Sign in again to continue.',
+      absolute_timeout:
+        'Your session reached its maximum lifetime. Sign in again to continue.',
+      back_channel_revoked:
+        'Your identity provider signed you out (back-channel logout). Sign in again to continue.',
+    }[sessionCause] || null;
+
   // Break-glass inline form state.
   const [showBreakglass, setShowBreakglass] = useState(false);
   const [bgActorID, setBgActorID] = useState('');
@@ -92,6 +164,30 @@ export default function LoginPage() {
           <p className="text-sm text-ink-muted uppercase tracking-wider">Certificate Control Plane</p>
         </div>
 
+        {oidcReasonText && (
+          <div
+            className="bg-amber-50 border border-amber-200 rounded p-4 mb-4 text-sm text-amber-900"
+            data-testid="login-oidc-failure-banner"
+            data-reason={oidcReason}
+            role="alert"
+          >
+            <div className="font-medium mb-1">Sign-in with your identity provider failed</div>
+            <div className="text-xs">{oidcReasonText}</div>
+          </div>
+        )}
+
+        {sessionCauseText && (
+          <div
+            className="bg-blue-50 border border-blue-200 rounded p-4 mb-4 text-sm text-blue-900"
+            data-testid="login-session-cause-banner"
+            data-cause={sessionCause}
+            role="status"
+          >
+            <div className="font-medium mb-1">You've been signed out</div>
+            <div className="text-xs">{sessionCauseText}</div>
+          </div>
+        )}
+
         {providers.length > 0 && (
           <div
             className="bg-surface border border-surface-border rounded p-6 space-y-3 shadow-sm mb-4"