Skip to content

The agent that grows with you

7.1 KB
Raw Blame
"""SessionTokenProvider — the deployment session token as a first-class credential.

Gated mode (non-loopback bind) demands a registered ``DashboardAuthProvider`` and verifies
every bearer / WS ``?token=`` through ``verify_session``. The nix/agenix deployment story
(``backend.sessionTokenFile`` → ``HERMES_DASHBOARD_SESSION_TOKEN=file:<path>``) provisions
exactly one shared secret — the same token the Desktop's "Session token" connection field
presents — but until now nothing vouched for it in gated mode, so a token-only deployment
was forced through the interactive provider prompt into basic-auth credentials it never
asked for. This provider closes that gap: it registers whenever the session token is
provisioned (and not explicitly disabled), and ``verify_session`` constant-time-compares
the presented credential against it. Both auth legs the Desktop uses — the REST
``Authorization: Bearer`` path and the ``/api/ws`` ``?token=`` upgrade credential — run
through that seam, so one provisioned token authorizes both.

It is deliberately NOT an interactive login: no login-page button, no cookies, no refresh.
A browser visiting a token-gated dashboard sees a note pointing at the deployment's
credential channel instead of a dead sign-in link. Disable with
``dashboard.session_token_auth.enabled: false`` in config.yaml (the env var itself is the
opt-in; it is a credential, so there is deliberately no new env var for the toggle).
"""
from __future__ import annotations

import hmac
import logging
import os
import time
from typing import Optional

from hermes_cli.dashboard_auth import (
    DashboardAuthProvider, RefreshExpiredError, Session)
from plugins.dashboard_auth._shared import (
    NonInteractiveMixin, SkipRegistration, load_config_section, register_provider)

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

# The verifier re-derives an expiry on every verify (the credential itself never
# expires — rotation is replacing the env var / secret file), so this only bounds
# how long anything that ever minted a cookie from a verified session would keep it.
_SESSION_HORIZON_SECONDS = 24 * 60 * 60

LAST_SKIP_REASON: str = ""


def _resolve_provisioned_token() -> str:
    """The exact token ``web_server`` serves under: env value, or the contents of a
    ``file:``-prefixed path (BOM-tolerant, same reader). Raises ``SystemExit`` for an
    unreadable/empty token file — ``register`` maps that to a skip so plugin discovery
    never dies for a sibling provider's misconfiguration."""
    from hermes_cli.web_server_session_token import resolve_session_token

    return resolve_session_token()


def _load_session_token_auth_section() -> dict:
    return load_config_section(logger, _TAG, "dashboard", "session_token_auth")


def _opt_out() -> bool:
    """``dashboard.session_token_auth.enabled: false`` disables the provider. There is no
    env toggle: the enabling side of this switch IS ``HERMES_DASHBOARD_SESSION_TOKEN``, a
    credential; behaviour belongs in config.yaml."""
    section = _load_session_token_auth_section()
    return str(section.get("enabled", True)).strip().lower() in ("0", "false", "no", "off")


def _settings() -> dict:
    """Resolve SessionTokenProvider kwargs; raises ``SkipRegistration`` when the token is
    not provisioned, the provider is disabled, or the token file is unreadable (the file
    resolver's ``SystemExit`` — a deployment misconfiguration must not crash plugin
    discovery for every sibling plugin)."""
    if not os.environ.get("HERMES_DASHBOARD_SESSION_TOKEN", "").strip():
        raise SkipRegistration(
            "HERMES_DASHBOARD_SESSION_TOKEN is not set. Provision it (a literal token, or "
            "'file:<path>' pointing at a secret-manager-decrypted token file) to let the "
            "deployment session token authorize the gated dashboard.")
    if _opt_out():
        raise SkipRegistration(
            "dashboard.session_token_auth.enabled is false; the deployment session token "
            "does not authenticate the gated dashboard.")
    try:
        token = _resolve_provisioned_token()
    except SystemExit as exc:
        raise SkipRegistration(str(exc), level="error") from exc
    if len(token) < 32:
        logger.warning(
            "%s: the provisioned session token is short (%d chars); use a "
            "`secrets.token_urlsafe(32)`-shaped value for a deployment credential.",
            _TAG, len(token))
    return {"token": token}


class SessionTokenProvider(NonInteractiveMixin, DashboardAuthProvider):
    """Vouches for the deployment session token (``HERMES_DASHBOARD_SESSION_TOKEN``).

    ``supports_session`` is True — the presented bearer/``?token=`` IS the session
    credential the middleware seam verifies — while ``interactive_login`` is False: there
    is no browser sign-in flow, so login surfaces must not offer it.
    """

    name = "session-token"
    display_name = "Deployment Session Token"
    supports_password = False
    supports_session = True
    interactive_login = False
    _NOT_INTERACTIVE = (
        "SessionTokenProvider has no login flow: clients present the provisioned session "
        "token directly (Authorization: Bearer, or ?token= on the /api/ws upgrade).")
    _NO_START_LOGIN = _NOT_INTERACTIVE

    def __init__(self, *, token: str) -> None:
        if not token:
            raise ValueError("token must be non-empty")
        self._token = token

    # ---- session verification (the one capability) --------------------------

    def verify_session(self, *, access_token: str) -> Optional[Session]:
        if not access_token or not hmac.compare_digest(
                access_token.encode("utf-8"), self._token.encode("utf-8")):
            return None
        return Session(
            user_id="deployment-token", email="", display_name="Deployment session token",
            org_id="", provider=self.name,
            expires_at=int(time.time()) + _SESSION_HORIZON_SECONDS,
            access_token=access_token, refresh_token="")

    def refresh_session(self, *, refresh_token: str) -> Session:
        # The credential never rotates server-side mid-process; there is nothing to
        # refresh into. Any refresh attempt is a foreign cookie's — rejected.
        raise RefreshExpiredError("the deployment session token has no refresh token")

    def revoke_session(self, *, refresh_token: str) -> None:
        # Stateless shared credential — revocation is rotation (redeploy the secret).
        # Must not raise.
        return None


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

def register(ctx) -> None:
    """Register ``SessionTokenProvider`` when the deployment session token is provisioned
    and not disabled; a no-op otherwise (so the gate's fail-closed message keeps steering
    interactive deployments toward basic-auth / OAuth)."""
    global LAST_SKIP_REASON
    LAST_SKIP_REASON = ""
    kwargs, LAST_SKIP_REASON = register_provider(ctx, logger, _TAG, SessionTokenProvider, _settings)
    if kwargs is not None:
        logger.info(
            "%s: registered deployment session-token provider — the provisioned "
            "HERMES_DASHBOARD_SESSION_TOKEN authorizes the gated dashboard "
            "(bearer REST + /api/ws ?token=).", _TAG)