Story: JWT refresh
Table of Contents
This page documents a story in Sprint 15. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Close the loop on JWT auth with token refresh, configurable lifetimes, and a TimescaleDB auth-events hypertable for telemetry.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 15 |
| Now | Completed 2026-03-21. |
| Waiting on | None. |
| Next | None. |
| Last touched | 2026-03-21 |
Continued from: JWT RS256 in ores.security (sprint 14). The RS256 signing landed last sprint; this story closes the loop with token refresh (no more silent token-expired failures during long-running sessions).
Acceptance
- Configurable lifetimes via iam.token.* system settings.
- iam.v1.auth.refresh NATS endpoint + validate_allow_expired().
- ores_iam_auth_events_tbl hypertable with hourly + daily aggregates.
- make_request_context returns explicit token_expired / unauthorized via X-Error.
- 48 handlers updated to handle std::expected return.
- Hot-reload of token settings on system_setting_changed.
- Shell reactive retry on token_expired; Qt proactive QTimer at 80% of lifetime.
- sessionExpired signal + warning dialog flow.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Implement JWT refresh | DONE | 2026-05-20 | 2026-03-21 | Configurable token lifetimes via iam.token.* system settings (access_lifetime, party_selection_lifetime, max_session_seconds, refresh_threshold_pct); iam.v1.auth.refresh NATS endpoint + validate_allow_expired() method; ores_iam_auth_events_tbl TimescaleDB hypertable with hourly + daily continuous aggregate views (90d raw, 3y daily); make_request_context returns std::expected with token_expired / unauthorized; error_reply via X-Error NATS headers; 48 domain handlers updated; hot-reload of token settings on system_setting_changed; shell reactive retry; Qt proactive QTimer at 80% of token lifetime; sessionExpired signal + warning dialog. |
Decisions
- Configurable lifetimes via system settings
- instead of compile-time constants; tunable per environment.
- Hot-reload via event
- avoids service restarts when changing token settings.
- Reactive + proactive client refresh
- shell retries on failure; Qt refreshes ahead of expiry.
Out of scope
- Refresh token rotation (future).
- Per-tenant token policies (future).
See also
- JWT RS256 in ores.security (sprint 14) — predecessor.
- Unified system_settings — supplies the iam.token.* configuration.