Skip to content

The agent that grows with you

3.3 KB
Raw Blame
"""The browser credential, and how every grant made under it ends when it is replaced.

The browser credential is the dashboard session token (``hermes_cli.web_server._SESSION_TOKEN``). A
loopback Webapp tab holds it; behind the sign-in gate each Webapp login is bound to it
(``hermes_cli.webapp_sign_in``). The gateway keeps the Webapp's credential in its home
(``gateway.webapp_listener.browser_session_token``) and sets it when its listener starts.

Every grant a browser gets under the credential records the credential's generation, a SHA-256 digest
of it, when the grant is made, and is honoured only while :func:`is_current` says that generation is
still the one in use: window and launch tickets (``web_routers.webapp``), socket tickets
(``web_session_sockets.ticket_refusal``), Bot Desktop viewer tickets (``web_routers.display``), file
tickets (``web_server_file_tickets``), open sockets (``web_session_sockets.track``) and a cookie
login's binding (``webapp_sign_in.check``). Stores keep the generation, never the credential.

:func:`rotate` (``hermes webapp --sign-out``) replaces the credential, then runs every revoker
registered with :func:`on_rotate`: grants that stay in use without being presented again (open
sockets) end at once, and stores drop what can no longer be redeemed.
"""
from __future__ import annotations

import hashlib
import hmac
import threading
from typing import Callable, Optional

_lock = threading.Lock()
#: Revoker name -> callable that ends the grants made under a replaced credential and returns how
#: many it ended.
_revokers: dict[str, Callable[[], int]] = {}


def current() -> str:
    """The browser credential in use now."""
    from hermes_cli import web_server
    return web_server._SESSION_TOKEN


def generation_of(credential: str) -> str:
    """The generation a grant made under *credential* records."""
    return hashlib.sha256(credential.encode()).hexdigest()


def generation() -> str:
    """The generation of the credential in use now."""
    return generation_of(current())


def is_current(recorded: Optional[str]) -> bool:
    """Whether a grant that recorded generation *recorded* was made under the credential in use now."""
    return current_if(recorded) is not None


def current_if(recorded: Optional[str]) -> Optional[str]:
    """The credential in use now when *recorded* is its generation, else None. For a grant that
    hands the credential over or binds a login to it: one read, so a rotation between the check
    and the use cannot pass on the credential that replaced the one the grant was made under."""
    credential = current()
    if recorded is None or not hmac.compare_digest(recorded, generation_of(credential)):
        return None
    return credential


def on_rotate(name: str, revoker: Callable[[], int]) -> None:
    """Run *revoker* each time the credential is replaced; registering a name again replaces it."""
    with _lock:
        _revokers[name] = revoker


def rotate(credential: str) -> dict[str, int]:
    """Make *credential* the browser credential and end every grant made under the one it replaces.
    Returns how many grants each registered revoker ended, by name. Safe from any thread."""
    from hermes_cli import web_server

    web_server._SESSION_TOKEN = credential
    with _lock:
        revokers = dict(_revokers)
    return {name: revoker() for name, revoker in revokers.items()}