JWT Token Refresh: Configurable Lifetimes, Proactive Renewal

JWT tokens are currently issued with a hardcoded 8-hour lifetime in ores.iam/include/ores.iam/messaging/auth_handler.hpp. When a token expires, make_request_context() in ores.service silently falls back to a system-level database context rather than returning an error. The Qt client receives no notification and the user has no indication that their session has expired.

This plan introduces:

• Configurable token lifetimes stored in the system settings table (depends on the system settings unification PR)
• A iam.v1.auth.refresh NATS subject for token renewal
• A fix to the silent fallback bug in request_context.cpp
• Proactive refresh in the Qt nats_session (fires at ~80% of token lifetime)
• Reactive handling of token_expired errors returned to the client
• A session-expired UI flow: dialog → disconnect → login screen

Prerequisite: The system settings unification PR must be merged before Phase 1 of this plan. Phases 2–5 can proceed once the system settings registry exists.

PR: [iam] Register JWT token lifetime settings

Depends on: system settings unification PR merged.

The four settings keys and their defaults:

// In settings_registry definitions
{ "iam.token.access_lifetime_seconds",       data_type::integer, "1800"  },
{ "iam.token.party_selection_lifetime_seconds", data_type::integer, "300" },
{ "iam.token.max_session_seconds",            data_type::integer, "28800" },
{ "iam.token.refresh_threshold_pct",          data_type::integer, "80"    },

token_settings::load() fetches all four from the service and returns a typed struct. Called once at service startup and cached; the IAM service subscribes to ores.variability.v1.events.system_setting_changed to reload on change.

Working state: Four settings exist in the DB with defaults. IAM can read them at startup.

PR: [iam] Configurable token lifetimes and iam.v1.auth.refresh

handle_refresh logic:

message handle_refresh(const nats::message& msg, const request_context& ctx) {
    // ctx was built with validate_ignore_expiry = true
    // (token may be near/just-past expiry — still trusted for identity)

    const auto now = std::chrono::system_clock::now();
    const auto original_iat = ctx.claims().issued_at;
    const auto max_session = std::chrono::seconds(settings_.max_session_s);

    if (original_iat + max_session < now)
        return error_reply(msg, "max_session_exceeded");

    // Issue fresh token with same identity, new iat/exp
    const auto new_token = jwt_issuer_.issue(
        ctx.claims().account_id,
        ctx.claims().tenant_id,
        ctx.claims().roles,
        std::chrono::seconds(settings_.access_lifetime_s));

    refresh_response resp{ .token = new_token };
    return msgpack_reply(msg, resp);
}

The login/select-party handlers read lifetimes from token_settings instead of hardcoded constants.

The IAM registrar listens on ores.variability.v1.events.system_setting_changed and reloads token_settings when any iam.token.* key changes.

Working state: iam.v1.auth.refresh is live. Login issues 30-min tokens. Shell and Qt clients still use 8h tokens until rebuilt/reconnected.

PR: [service] Propagate token_expired error instead of silent fallback

make_request_context() change:

// BEFORE (silent fallback):
auto result = jwt_auth_.validate(token);
if (!result) {
    // fell through to system context — WRONG
    return make_system_context(db_);
}

// AFTER:
auto result = jwt_auth_.validate(token);
if (!result) {
    if (result.error() == jwt_error::expired_token)
        return std::unexpected(error_code::token_expired);
    return std::unexpected(error_code::unauthorized);
}

Each domain handler that calls make_request_context() gains an early-exit:

auto ctx = make_request_context(msg, db_pool_);
if (!ctx) {
    if (ctx.error() == error_code::token_expired)
        return nats_error_reply(msg, "token_expired");
    return nats_error_reply(msg, "unauthorized");
}

Working state: Expired tokens produce explicit token_expired replies instead of wrong data.

PR: [shell] Handle token_expired: attempt refresh, re-issue command

message nats_session::authenticated_request(std::string_view subject, ...) {
    auto reply = client_.request_sync(subject, data, auth_headers());
    if (reply.header("X-Error") == "token_expired") {
        refresh();  // calls iam.v1.auth.refresh; updates session_.jwt
        reply = client_.request_sync(subject, data, auth_headers());
    }
    if (reply.header("X-Error") == "max_session_exceeded") {
        throw session_expired_error("Session has expired. Please log in again.");
    }
    return reply;
}

Working state: Shell commands transparently refresh tokens. If max session is exceeded the error message tells the user to re-authenticate.

PR: [qt] Proactive JWT refresh timer and session-expired dialog