fix: auth refactor — eliminate refresh race, increase buffer, add error semantics

[exactlyallan]

Summary

This PR addresses three of the five root causes of persistent auth failures documented in the auth flow analysis. It is the first PR of a multi-phase auth refactor.

Commit 1: Eliminate dual refresh race + increase buffer (Phases 1 & 2)

• Eliminate dual refresh race condition: Removed the duplicate setInterval in useAuth that fired concurrently with SessionProvider.refetchInterval. With rotating refresh tokens (e.g., NVIDIA Starfleet SSO), concurrent refreshes consumed an already-invalidated token → invalid_grant → random logouts.
• Config-driven refresh interval: SessionProvider.refetchInterval now uses config.sessionRefreshIntervalSeconds instead of hardcoded 4 * 60.
• Increase default refresh buffer: TOKEN_REFRESH_BUFFER_MINUTES default changed from 5 → 15 minutes (covering most deep research operations).

Commit 2: Machine-readable auth error codes + RUM observability (Phase 3)

• validate_with_error() on TokenValidator: New method returns (user, error_code) instead of just user | None. Default wraps validate() for backward compatibility.
• JWTValidator override: ExpiredSignatureError → "token_expired", InvalidTokenError → "token_invalid".
• Middleware 401 responses now include "error" field: "token_missing", "token_expired", "token_invalid" — frontends can distinguish "refresh" from "reauthenticate".
• TokenExpiredError / TokenInvalidError subclasses of AuthError with error_code attribute.
• WebSocket error propagation: AuthError caught in workflow handler → sends typed "auth_error" message over WS.
• Datadog RUM integration: authenticatedFetch and WebSocket client emit DD_RUM.addError() on auth failures (no-op without Datadog SDK).

Files changed

Frontend (frontends/ui/src/)

File	Change
adapters/auth/session.ts	Remove duplicate setInterval, add explanatory comment
adapters/auth/config.ts	Increase default buffer from 5 → 15 minutes
app/providers.tsx	Use config-driven refetchInterval
adapters/api/authenticated-fetch.ts	Add RUM error tracking on 401 responses
adapters/api/websocket-client.ts	Add RUM tracking for WS auth errors
.env.example, README.md	Update defaults
adapters/auth/config.spec.ts	Update default expectations
adapters/auth/session.spec.tsx	Add regression test (no setInterval)

Backend (frontends/aiq_api/src/aiq_api/)

File	Change
auth/base.py	Add validate_with_error() default method
auth/jwt_validator.py	Override with expired/invalid distinction
auth/middleware.py	Return error code in 401 JSON body
auth/errors.py	Add TokenExpiredError, TokenInvalidError
auth/__init__.py	Export new error types
websocket_reconnect.py	Auth error messages over WebSocket
tests/test_auth.py	10 new tests + fix flaky kid cache test

Test plan

• npm run test:ci — 1183 frontend tests pass
• pytest test_auth.py — 39 backend tests pass (10 new)
• Pre-commit hooks pass (ruff, formatting, secrets detection)
• Manual: verify 401 response includes "error": "token_expired" for expired JWT
• Manual: verify 401 response includes "error": "token_invalid" for bad JWT
• Manual: with REQUIRE_AUTH=true, verify single refresh path in Network tab
• Manual: with REQUIRE_AUTH=false, verify app loads with no auth UI

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR is the first phase of an auth refactor addressing three root causes of auth failures: it removes the duplicate setInterval in useAuth that raced with SessionProvider.refetchInterval on rotating-token providers, increases the default token refresh buffer from 5 → 15 minutes, and adds machine-readable error codes ("token_missing", "token_expired", "token_invalid") to 401 responses, WebSocket error messages, and Datadog RUM events. The validate() abstract method now returns (user_dict, error_code) tuples with full backward-compatibility handling in the middleware.

Confidence Score: 5/5

Safe to merge; only P2 findings, all on non-critical observability paths

The core auth fixes (race condition elimination, buffer increase, error code propagation) are well-implemented and thoroughly tested. Both findings are P2: one is a narrow RUM tracking guard that misses specific subclass codes (no functional regression), the other is dead code complexity. No P0/P1 issues found.

No files require special attention. middleware.py has the dead validate_with_error branch worth cleaning up, but it has no runtime impact.

Important Files Changed

Filename	Overview
frontends/aiq_api/src/aiq_api/auth/middleware.py	Refactored to propagate machine-readable error codes in 401 responses; backward-compat validator detection includes a dead validate_with_error branch that is never reached with current validators
frontends/ui/src/adapters/api/websocket-client.ts	Adds RUM tracking for WS auth errors, but the guard only matches the base 'auth_error' code, silently missing 'token_expired' and 'token_invalid' subclass codes
frontends/aiq_api/src/aiq_api/auth/jwt_validator.py	All return paths updated to tuples; ExpiredSignatureError → "token_expired", InvalidTokenError → "token_invalid", consistent with the new contract
frontends/aiq_api/src/aiq_api/auth/errors.py	Adds TokenExpiredError and TokenInvalidError subclasses with error_code class attribute; clean hierarchy
frontends/aiq_api/src/aiq_api/websocket_reconnect.py	Auth errors during workflow are now caught and surfaced as typed WS error messages; non-auth exceptions still log and return as before
frontends/ui/src/adapters/auth/session.ts	Duplicate setInterval removed; explanatory comment added; RUM error emitted before signOut() redirect
frontends/ui/src/app/providers.tsx	refetchInterval now uses config-driven sessionRefreshIntervalSeconds instead of hardcoded 4 * 60
frontends/ui/src/shared/utils/rum.ts	New RUM helper; correctly guards for window existence (SSR safe) and optional DD_RUM global; no-op without Datadog SDK
frontends/ui/src/adapters/api/authenticated-fetch.ts	Uses response.clone().json() correctly to read body without consuming the original response; RUM tracking on 401 is well-guarded
frontends/aiq_api/tests/test_auth.py	10 new tests covering error subclasses, error code propagation through middleware, and missing/expired/invalid token scenarios; flaky kid-cache test fixed
frontends/ui/src/adapters/auth/config.ts	Default TOKEN_REFRESH_BUFFER_MINUTES increased from 5 → 15; change is reflected consistently in spec, .env.example, and README

Sequence Diagram

sequenceDiagram
    participant FE as Frontend
    participant SP as SessionProvider
    participant MW as AuthMiddleware
    participant JV as JWTValidator
    participant RUM as Datadog RUM

    Note over SP: refetchInterval = config.sessionRefreshIntervalSeconds<br/>(no duplicate setInterval in useAuth)
    SP->>MW: GET /session (Bearer token)
    MW->>JV: validate_token_with_error(token)
    alt Token valid
        JV-->>MW: (user_dict, None)
        MW-->>SP: 200 OK
    else Token expired
        JV-->>MW: (None, "token_expired")
        MW-->>FE: 401 {error: "token_expired"}
        FE->>RUM: trackRumError("Auth failure: token_expired")
    else Token invalid
        JV-->>MW: (None, "token_invalid")
        MW-->>FE: 401 {error: "token_invalid"}
        FE->>RUM: trackRumError("Auth failure: token_invalid")
    else No token
        MW-->>FE: 401 {error: "token_missing"}
    end

    Note over FE: WebSocket path
    FE->>MW: WS connect (AuthError raised in workflow)
    MW-->>FE: ERROR msg {message: exc.error_code}
    FE->>RUM: trackRumError("WebSocket auth failure")

Loading

_{Reviews (6): Last reviewed commit: "Merge upstream develop into auth refacto..." | Re-trigger Greptile}

[AjayThorve]

LGTM, tested locally, no regressions to the middleware