hermes-agent/plugins/dashboard_auth/nous/__init__.py

"""NousDashboardAuthProvider — Nous Portal OAuth (authorization-code + PKCE).

Implements ``nous-account-service/docs/agent-dashboard-oauth-contract.md``; registers only
when a client_id (``dashboard.oauth.client_id`` / ``HERMES_DASHBOARD_OAUTH_CLIENT_ID``, shape
``agent:{instance_id}``) is configured. Access tokens are RS256 JWTs verified against the
Portal JWKS with ``aud`` = bare client_id. Portal issues a 24h *rotating* refresh token with
reuse detection: the middleware MUST persist ``Session.refresh_token`` back to the cookie on
every refresh or the next refresh replays a rotated token and revokes the whole session.
"""

from __future__ import annotations

import logging
from typing import Any, Dict, Optional

from hermes_cli.dashboard_auth import LoginStart, ProviderError, Session
from plugins.dashboard_auth._shared import (
    JwtOAuthProvider,
    SkipRegistration,
    exchange_token,
    load_config_section,
    pkce_login_start,
    refresh_token_from,
    register_provider,
    resolve_env_or_cfg,
    session_from_claims,
    validate_redirect_uri,
    verify_jwt)

logger = logging.getLogger(__name__)
_TAG = "dashboard-auth-nous"

_DEFAULT_PORTAL_URL = "https://portal.nousresearch.com"
_SCOPE = "agent_dashboard:access"  # contract C3
_EXPECTED_CONTRACT_VERSION = 1  # contract C11

LAST_SKIP_REASON: str = ""  # cleared on every register() so restarts don't leak stale reasons


class NousDashboardAuthProvider(JwtOAuthProvider):
    """Nous Portal OAuth via authorization-code + PKCE (S256)."""

    name = "nous"
    display_name = "Nous Research"

    def __init__(self, *, client_id: str, portal_url: str) -> None:
        # Defense-in-depth: register() filters too, but a malformed id must never construct a provider.
        if not client_id.startswith("agent:"):
            raise ValueError(f"client_id must match contract shape 'agent:{{instance_id}}', got {client_id!r}")
        self._client_id = client_id
        self._agent_instance_id = client_id[len("agent:") :]
        self._portal_url = portal_url.rstrip("/")
        self._jwks_url = f"{self._portal_url}/.well-known/jwks.json"
        self._authorize_url = f"{self._portal_url}/oauth/authorize"
        self._token_url = f"{self._portal_url}/api/oauth/token"
        self._jwks_client: Any = None  # lazily built (crypto import cost)

    def start_login(self, *, redirect_uri: str) -> LoginStart:
        validate_redirect_uri(redirect_uri)
        return pkce_login_start(self._authorize_url, client_id=self._client_id, scope=_SCOPE, redirect_uri=redirect_uri)

    def revoke_session(self, *, refresh_token: str) -> None:
        # Portal exposes no token-endpoint revocation grant; logout is client-side cookie
        # clearing and the RT expires within its 24h TTL.
        return None

    # ---- JwtOAuthProvider hooks -------------------------------------------

    def _jwks_uri(self) -> str:
        return self._jwks_url

    def _refresh_request(self, refresh_token: str) -> tuple[Dict[str, str], Optional[Dict[str, str]]]:
        # The RT goes in BOTH the body (Portal's request schema requires it) and the
        # ``x-nous-refresh-token`` header (Portal reconciles the two and keeps the value
        # out of body access logs). Header-only → 400.
        return (
            {"grant_type": "refresh_token", "client_id": self._client_id, "refresh_token": refresh_token},
            {"x-nous-refresh-token": refresh_token})

    def _grant(
        self, data: Dict[str, str], *, bad_request_exc: type[Exception], headers: Optional[Dict[str, str]] = None,
        previous_refresh_token: str = "",
    ) -> Session:
        access_token, payload = exchange_token(
            self._token_url, data, headers=headers, bad_request_exc=bad_request_exc,
            idp="Portal", endpoint="Portal token endpoint", token_key="access_token",
            missing_msg="Portal token response missing access_token")
        # Rotating RT the caller MUST persist back to the cookie.
        return self._session(access_token, refresh_token_from(payload), self._claims_for(access_token))


    def _claims_for(self, access_token: str) -> Dict[str, Any]:
        claims = verify_jwt(
            access_token, self._get_jwks_client(), algorithms=["RS256"],
            audience=self._client_id,  # contract C2: bare client_id
            issuer=self._portal_url, label="access token")
        # Contract C9: agent_instance_id is "should" not "must" — tolerated when absent
        # (the aud check already binds the token to this instance).
        token_instance_id = claims.get("agent_instance_id")
        if token_instance_id is not None and token_instance_id != self._agent_instance_id:
            raise ProviderError(
                f"agent_instance_id mismatch: token={token_instance_id!r} vs configured={self._agent_instance_id!r}")
        contract_version = claims.get("oauth_contract_version")
        if contract_version is None:
            logger.warning(
                "Nous Portal token missing oauth_contract_version claim (contract says it should be %d); proceeding anyway.",
                _EXPECTED_CONTRACT_VERSION)
        elif contract_version != _EXPECTED_CONTRACT_VERSION:
            raise ProviderError(
                f"unsupported oauth_contract_version={contract_version!r}, expected {_EXPECTED_CONTRACT_VERSION}")
        return claims


    def _session(self, access_token: str, refresh_token: str, claims: Dict[str, Any]) -> Session:
        # Contract C4: no email / display_name in tokens.
        return session_from_claims(
            self.name, claims, access_token=access_token, refresh_token=refresh_token, org_id=str(claims.get("org_id") or ""))


# ---- Plugin entry point ----

def _load_config_oauth_section() -> dict:
    return load_config_section(logger, _TAG, "dashboard", "oauth")


def _settings() -> dict:
    """Resolve NousDashboardAuthProvider kwargs; the skip reason names BOTH configuration surfaces."""
    section = _load_config_oauth_section()
    client_id = resolve_env_or_cfg("HERMES_DASHBOARD_OAUTH_CLIENT_ID", section.get("client_id", ""))
    portal_url = resolve_env_or_cfg("HERMES_DASHBOARD_PORTAL_URL", section.get("portal_url", "")) or _DEFAULT_PORTAL_URL
    if not client_id:
        raise SkipRegistration(
            "HERMES_DASHBOARD_OAUTH_CLIENT_ID is not set (and dashboard.oauth.client_id "
            "in config.yaml is empty). The Nous Portal provisions this env var (shape "
            "'agent:{instance_id}') when it deploys a Hermes Agent instance — set it to "
            "your provisioned client id (either as an env var or under "
            "dashboard.oauth.client_id in config.yaml), or pass --insecure to skip the "
            "OAuth gate entirely.")
    if not client_id.startswith("agent:"):
        raise SkipRegistration(
            f"HERMES_DASHBOARD_OAUTH_CLIENT_ID={client_id!r} doesn't match the contract "
            f"shape 'agent:{{instance_id}}'. The Nous Portal provisions this value at deploy "
            f"time; check your Fly app's secrets or override with the value from the Portal admin UI.",
            level="warning")
    return {"client_id": client_id, "portal_url": portal_url}


def register(ctx) -> None:
    """Register ``NousDashboardAuthProvider`` when a client_id is configured."""
    global LAST_SKIP_REASON
    LAST_SKIP_REASON = ""
    kwargs, LAST_SKIP_REASON = register_provider(ctx, logger, _TAG, NousDashboardAuthProvider, _settings)
    if kwargs is not None:
        logger.info(
            "dashboard-auth-nous: registered provider (client_id=%s, portal=%s)", kwargs["client_id"], kwargs["portal_url"])