feat(dashboard-auth): rotate dashboard sessions via refresh token

hermes_cli/dashboard_auth/middleware.py

@@ -24,7 +24,7 @@
 
 from hermes_cli.dashboard_auth import list_providers
 from hermes_cli.dashboard_auth.audit import AuditEvent, audit_log
-from hermes_cli.dashboard_auth.base import ProviderError
+from hermes_cli.dashboard_auth.base import ProviderError, RefreshExpiredError
 from hermes_cli.dashboard_auth.cookies import read_session_cookies
 from hermes_cli.dashboard_auth.public_paths import PUBLIC_API_PATHS
 
@@ -185,44 +185,94 @@ async def gated_auth_middleware(
         return await call_next(request)
 
     at, _rt = read_session_cookies(request)
-    if not at:
+    if not at and not _rt:
+        # Neither token present — no session at all. Nothing to verify or
+        # refresh; force login.
         return _unauth_response(request, reason="no_cookie")
 
     # Try every registered provider's verify_session in turn. Providers
     # MUST return None for tokens they don't recognise (not raise). This
     # lets multiple providers stack — the first one that recognises a
     # token wins.
+    #
+    # When the access-token cookie is absent but a refresh-token cookie is
+    # present, skip verification and go straight to the refresh path below.
+    # This is the COMMON expiry case, not an edge case: the access-token
+    # cookie is set with ``Max-Age = access_token_expires_in`` (~15 min), so
+    # the browser EVICTS it the moment the token lapses, while the
+    # refresh-token cookie lives for 30 days. From that point the browser
+    # sends only ``hermes_session_rt``. If we bailed on ``not at`` here we'd
+    # bounce the user to /login on every expiry despite holding a perfectly
+    # good refresh token — defeating the whole transparent-refresh feature.
     session = None
-    for provider in list_providers():
-        try:
-            session = provider.verify_session(access_token=at)
-        except ProviderError as e:
-            _log.warning(
-                "dashboard-auth: provider %r unreachable during verify: %s",
-                provider.name, e,
+    if at:
+        for provider in list_providers():
+            try:
+                session = provider.verify_session(access_token=at)
+            except ProviderError as e:
+                _log.warning(
+                    "dashboard-auth: provider %r unreachable during verify: %s",
+                    provider.name, e,
+                )
+                audit_log(
+                    AuditEvent.SESSION_VERIFY_FAILURE,
+                    provider=provider.name,
+                    reason="provider_unreachable",
+                    ip=_client_ip(request),
+                )
+                return JSONResponse(
+                    {"detail": f"Auth provider {provider.name!r} unreachable"},
+                    status_code=503,
+                )
+            if session is not None:
+                break
+
+    if session is None:
+        # Access token is expired/invalid. Before forcing re-login, try to
+        # rotate it using the refresh token (if the session cookie carries
+        # one). On success we re-set the rotated cookies on the response and
+        # serve the request transparently; on RefreshExpiredError (RT dead /
+        # revoked / reuse-detected) we fall through to clear-and-relogin.
+        refreshed = _attempt_refresh(request, refresh_token=_rt)
+        if refreshed is not None:
+            new_session, refreshing_provider = refreshed
+            request.state.session = new_session
+            response = await call_next(request)
+            # Persist the ROTATED tokens. Portal rotates the refresh token on
+            # every refresh and runs reuse-detection, so writing the new RT
+            # back is mandatory: a stale RT cookie would replay a rotated
+            # token on the next refresh and (outside Portal's grace) revoke
+            # the whole session. Bind cookie Secure/Path to the request shape.
+            from hermes_cli.dashboard_auth.cookies import (
+                detect_https,
+                set_session_cookies,
+            )
+            from hermes_cli.dashboard_auth.prefix import prefix_from_request
+
+            set_session_cookies(
+                response,
+                access_token=new_session.access_token,
+                refresh_token=new_session.refresh_token,
+                access_token_expires_in=_expires_in_seconds(new_session),
+                use_https=detect_https(request),
+                prefix=prefix_from_request(request),
             )
             audit_log(
-                AuditEvent.SESSION_VERIFY_FAILURE,
-                provider=provider.name,
-                reason="provider_unreachable",
+                AuditEvent.REFRESH_SUCCESS,
+                provider=refreshing_provider,
+                user_id=new_session.user_id,
                 ip=_client_ip(request),
             )
-            return JSONResponse(
-                {"detail": f"Auth provider {provider.name!r} unreachable"},
-                status_code=503,
-            )
-        if session is not None:
-            break
+            return response
 
-    if session is None:
         audit_log(
             AuditEvent.SESSION_VERIFY_FAILURE,
             reason="no_provider_recognises",
             ip=_client_ip(request),
         )
         response = _unauth_response(request, reason="invalid_or_expired_session")
-        # Clear the dead cookie so the browser doesn't keep sending it.
-        # Contract v1: no refresh token to retry with, so the only correct
+        # Clear the dead cookies so the browser doesn't keep sending them.
+        # Refresh already failed (or there was no RT), so the only correct
         # next step is full re-auth via /login. Importing locally avoids a
         # cycle with cookies → middleware at module load. Pass the active
         # prefix so the deletion's Path matches the set-Path (otherwise
@@ -234,3 +284,61 @@ async def gated_auth_middleware(
 
     request.state.session = session
     return await call_next(request)
+
+
+def _expires_in_seconds(session) -> int:
+    """Seconds until the access token's ``exp``, floored at 60.
+
+    Mirrors the auth-route's ``max(60, exp - now)`` so the access-token
+    cookie's Max-Age tracks the token lifetime even on a slightly skewed
+    clock. ``time`` imported locally to keep the module's import surface
+    minimal.
+    """
+    import time
+
+    return max(60, int(session.expires_at) - int(time.time()))
+
+
+def _attempt_refresh(request: Request, *, refresh_token):
+    """Try to rotate an expired session via the refresh token.
+
+    Returns ``(new_session, provider_name)`` on success, or ``None`` if
+    there's no RT or every provider's ``refresh_session`` failed with
+    ``RefreshExpiredError`` (dead/revoked/reuse-detected RT → force re-login).
+
+    A ``ProviderError`` (Portal unreachable) is NOT swallowed into a re-login
+    here — re-raising would 500 the request; instead we log and return None so
+    the caller forces a clean re-login, which is the safer UX than a hard
+    error on a transient network blip during the narrow refresh window.
+    """
+    if not refresh_token:
+        return None
+    for provider in list_providers():
+        try:
+            new_session = provider.refresh_session(refresh_token=refresh_token)
+        except RefreshExpiredError:
+            # This provider owns the RT but it's dead — stop trying others
+            # (an RT belongs to exactly one provider) and force re-login.
+            audit_log(
+                AuditEvent.REFRESH_FAILURE,
+                provider=provider.name,
+                reason="refresh_expired",
+                ip=_client_ip(request),
+            )
+            return None
+        except ProviderError as e:
+            _log.warning(
+                "dashboard-auth: provider %r unreachable during refresh: %s",
+                provider.name, e,
+            )
+            audit_log(
+                AuditEvent.REFRESH_FAILURE,
+                provider=provider.name,
+                reason="provider_unreachable",
+                ip=_client_ip(request),
+            )
+            return None
+        if new_session is not None:
+            return new_session, provider.name
+    return None
+

plugins/dashboard_auth/nous/__init__.py

@@ -36,8 +36,13 @@
   - scope is ``agent_dashboard:access`` only (no OIDC scopes).
   - tokens are RS256 JWTs verified against ``/.well-known/jwks.json``;
     JWKS is cached for 5 minutes.
-  - V1 has NO refresh tokens — ``refresh_session`` always raises
-    ``RefreshExpiredError`` so the middleware redirects to ``/auth/login``.
+  - the dashboard auth-code grant issues a 24h rotating refresh token
+    (Portal NAS PR #293). ``refresh_session`` posts ``grant_type=refresh_token``
+    to rotate the access token; ``complete_login`` and ``refresh_session``
+    both populate ``Session.refresh_token`` with the (rotating) value the
+    middleware persists back to the HttpOnly cookie. On a dead/expired/
+    reuse-detected refresh token Portal returns 400 → ``RefreshExpiredError``
+    → middleware redirects to ``/auth/login``.
   - audience claim is the bare ``client_id`` (no ``hermes-cli:`` prefix).
   - tolerant ``oauth_contract_version`` check: missing → warn + proceed;
     present and ``!= 1`` → refuse.
@@ -49,11 +54,11 @@
 "state": …}`` and the route serializes those into the ``hermes_session_pkce``
 cookie.
 
-Forward compatibility: if a future Portal contract starts issuing refresh
-tokens, ``complete_login`` already captures the value forward-compatibly
-(populates ``Session.refresh_token``). Wiring the RT cookie back into the
-middleware's near-expiry refresh path lives in the host application, not
-here.
+Refresh-token rotation: Portal rotates the refresh token on every
+successful refresh and runs reuse-detection (replaying a rotated token
+outside Portal's 60s grace revokes the whole session). The host
+middleware therefore MUST persist the rotated ``Session.refresh_token``
+back to the cookie on every refresh.
 
 Skip reasons:
   The plugin exposes a module-level ``LAST_SKIP_REASON`` that the gate's
@@ -229,12 +234,94 @@ def complete_login(
         except httpx.RequestError as exc:
             raise ProviderError(f"Portal token endpoint unreachable: {exc}") from exc
 
+        # The dashboard auth-code grant now issues a rotating refresh token
+        # (24h session, reuse-detected) — Portal NAS PR #293. A 400 here means
+        # the code/PKCE/redirect_uri failed, surfaced as InvalidCodeError.
+        return self._token_response_to_session(
+            response, bad_request_exc=InvalidCodeError
+        )
+
+    def refresh_session(self, *, refresh_token: str) -> Session:
+        """Rotate the access token using the refresh token.
+
+        Posts ``grant_type=refresh_token`` to Portal's token endpoint. The
+        refresh token is sent in the ``X-Refresh-Token`` header (not the body)
+        so it never lands in Portal's request-body access logs — mirroring the
+        device-flow CLI convention; Portal reconciles header vs. body and
+        rejects conflicts.
+
+        Portal rotates the refresh token on every successful refresh, so the
+        returned ``Session.refresh_token`` is a NEW value the caller MUST
+        persist (replacing the old cookie). Failing to persist it means the
+        next refresh replays a rotated token and — outside Portal's 60s grace
+        — trips reuse-detection and revokes the whole session.
+
+        Raises ``RefreshExpiredError`` on a 400 (expired / revoked / reuse-
+        detected), so the middleware clears cookies and forces re-login.
+        Raises ``ProviderError`` if Portal is unreachable.
+        """
+        if not refresh_token:
+            # No RT to present — treat as a dead session so middleware
+            # forces a clean re-login rather than emitting a malformed POST.
+            raise RefreshExpiredError("no refresh token present in session")
+
+        try:
+            response = httpx.post(
+                self._token_url,
+                # The refresh token goes in BOTH the body and the
+                # ``x-nous-refresh-token`` header. Portal's token endpoint
+                # requires ``refresh_token`` in the body (its request schema
+                # rejects a header-only request as ``invalid_request``), and
+                # additionally reconciles the header against the body — sending
+                # both lets Portal keep the value out of body-access-logs while
+                # still satisfying the schema. The header name must match
+                # Portal's ``REFRESH_TOKEN_HEADER`` exactly (``x-nous-refresh-
+                # token``); any other name is silently ignored. (Verified
+                # against the NAS #293 preview deploy: header-only → 400
+                # invalid_request; body → accepted.)
+                data={
+                    "grant_type": "refresh_token",
+                    "client_id": self._client_id,
+                    "refresh_token": refresh_token,
+                },
+                headers={
+                    "Accept": "application/json",
+                    "x-nous-refresh-token": refresh_token,
+                },
+                timeout=_TOKEN_ENDPOINT_TIMEOUT_SEC,
+            )
+        except httpx.RequestError as exc:
+            raise ProviderError(
+                f"Portal token endpoint unreachable: {exc}"
+            ) from exc
+
+        # A 400 on refresh means the RT is expired / revoked / reuse-detected;
+        # surface as RefreshExpiredError so middleware forces re-login.
+        return self._token_response_to_session(
+            response, bad_request_exc=RefreshExpiredError
+        )
+
+    def _token_response_to_session(
+        self,
+        response: httpx.Response,
+        *,
+        bad_request_exc: type[Exception],
+    ) -> Session:
+        """Translate a Portal ``/api/oauth/token`` response into a Session.
+
+        Shared by ``complete_login`` (auth-code grant) and ``refresh_session``
+        (refresh grant). ``bad_request_exc`` is the exception type raised on a
+        400 — ``InvalidCodeError`` for the auth-code path, ``RefreshExpiredError``
+        for the refresh path — so the middleware's distinct handling
+        (400-on-callback vs. force-relogin) is preserved.
+        """
         if response.status_code == 400:
-            # Contract: invalid_code, invalid_grant, redirect_uri_mismatch all
+            # Contract: invalid_code / invalid_grant / redirect_uri_mismatch
+            # (auth-code) and expired / revoked / reuse-detected (refresh) all
             # surface as 400 with an OAuth-shaped JSON error envelope.
             body = self._parse_json_body(response)
             error_code = body.get("error", "invalid_request")
-            raise InvalidCodeError(f"Portal rejected code: {error_code}")
+            raise bad_request_exc(f"Portal rejected token request: {error_code}")
         if response.status_code != 200:
             raise ProviderError(
                 f"Portal token endpoint returned {response.status_code}: "
@@ -251,21 +338,14 @@ def complete_login(
             raise ProviderError(f"unexpected token_type={token_type!r}")
 
         claims = self._verify_jwt(access_token)
-        # Contract V1: no refresh token expected. If a future Portal ever
-        # adds one, capture it forward-compatibly.
+        # The dashboard grant issues a rotating refresh token; capture it so
+        # the caller can persist it. Empty string if Portal omitted it (the
+        # session then behaves as access-token-only until expiry).
         refresh_token = payload.get("refresh_token") or ""
         if not isinstance(refresh_token, str):
             refresh_token = ""
         return self._session_from_claims(access_token, refresh_token, claims)
 
-    def refresh_session(self, *, refresh_token: str) -> Session:
-        # Contract V1 has no refresh tokens — always force re-auth. If a
-        # future Portal contract starts issuing them, this method needs to
-        # be re-implemented; until then it's an unconditional refusal.
-        raise RefreshExpiredError(
-            "Nous Portal does not issue refresh tokens in OAuth contract v1; "
-            "user must re-authenticate via /auth/login."
-        )
 
     def verify_session(self, *, access_token: str) -> Optional[Session]:
         # Contract: returns None on expiry/invalidity (middleware then
@@ -284,9 +364,16 @@ def verify_session(self, *, access_token: str) -> Optional[Session]:
         return self._session_from_claims(access_token, "", claims)
 
     def revoke_session(self, *, refresh_token: str) -> None:
-        # Contract V1: no refresh tokens to revoke, and no Portal revocation
-        # endpoint documented for dashboard tokens. Logout is purely
-        # client-side cookie clearing; this is a best-effort no-op.
+        # Portal exposes no public refresh-token revocation grant on its token
+        # endpoint (revocation is driven from the authenticated /sessions UI,
+        # keyed by sessionId + userId, not by the RT value). So logout is
+        # client-side cookie clearing; the server-side refresh session simply
+        # expires within its 24h TTL. Best-effort no-op, must not raise.
+        #
+        # If Portal later adds a token-endpoint revoke grant (e.g.
+        # grant_type=... + X-Refresh-Token), implement it here so logout
+        # invalidates the RT server-side immediately rather than waiting out
+        # the TTL.
         _ = refresh_token
         return None