feat(auth): unify token lifecycle with coordinated silent refresh across REST, WebSocket, and offline queues

[oladev2026-tech]

Closes #1142

Summary

Introduces a single TokenManager that owns the authentication token lifecycle, so the REST client, WebSocket connections, the notification socket and the offline replay queue all obtain their token from one place, share one refresh path, and react to rotation/revocation consistently.

What changed

• TokenManager (src/lib/auth/tokenManager.ts, new) — the single source of truth:
  • Single-flight refresh: concurrent callers share one in-flight /auth/refresh request, so a burst of 401s collapses into a single network round-trip (no thundering herd).
  • Proactive silent refresh: a background timer refreshes a configurable skew before exp, so long-lived sockets and queued offline operations never carry an about-to-lapse token.
  • Lifecycle events: token:rotated / token:revoked / auth:logout let consumers re-authenticate or tear down instead of each discovering the change on its own failed request.
  • Metrics: auth.refresh_success, auth.refresh_failure, auth.token_rotated, auth.forced_logout.
• REST (api.ts, apiInterceptors.ts) — the client sources its token from the manager, proactively refreshes before sending, and performs one coordinated refresh + replay on a 401 (guarded against loops). The request interceptor attaches a freshly-refreshed token; the error interceptor hard-logs-out only when the refresh itself fails.
• Sockets (websocketManager.ts, notifications/socket.ts) — re-authenticate live connections in place on token:rotated and disconnect on token:revoked, so a revoked session cannot keep receiving realtime data.
• Offline (offlineApi.ts, offlineSync.ts) — replay is gated on a valid token: it refreshes silently, and refuses (dead-letters via OfflineAuthRequiredError / skips the drain) when logged out, rather than burning retries against a dead credential.
• Supporting — jwt.ts gains a client-safe decodeTokenPayload and a verifyTokenDetailed that surfaces the specific exp/nbf/signature failure reason; environment.ts/app.constants.ts add the refresh endpoint and skew; monitoring/metrics.ts adds a typed recordAuthMetric.

Acceptance criteria

• A single access-token refresh occurs under concurrent 401s (single-flight) — verified by test
• Access tokens refresh silently before expiry using the configured skew; in-flight REST, socket and offline operations resume without a user-visible failure
• Token rotation triggers a socket re-auth; revocation disconnects sockets and halts offline replay with dead-lettering
• Auth lifecycle metrics are emitted with the documented tags; forced logout clears tokens from every consumer
• Unit tests cover dedupe, skew scheduling, rotation/revocation, persistence and forced logout

Verification

All repo CI checks pass locally: pnpm run type-check, pnpm run lint (--max-warnings=0), pnpm run validate:ui, pnpm run validate:web3, pnpm run build, and the new Vitest suite (13/13 passing) for the token manager.

[RUKAYAT-CODER]

Thank you for contributing to the project.