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');
   }