Files
hyprland-headless-stream-pl…/src/hhstream_mcp/authorizations.py
T
HermenixandClaude Opus 5 f4485f7a63 feat(mcp)!: a second transport, and the token it exists for
`hhstream-mcp serve --http` serves the surface over Streamable HTTP behind
a bearer token, and `hhstream-mcp token mint|list|revoke|prune` issues
those tokens.  stdio stays the default and stays unauthenticated.

The two are one feature, because neither works alone.  A token checked by
a process the caller spawned is a lock whose key is in the same pocket:
over stdio the client starts the server and already holds the broker's
0660 control socket, which is why `mcp.enable`'s own option text says it
"grants no access the `hhstream` CLI does not already grant".  A port is
the first time the caller is someone who passed no filesystem check on
the way in, and that is the moment a credential starts meaning something.
So the transport arrives with the credential, and the contract's "stdio,
and only stdio" is rewritten rather than quietly broken.

The store (`authorizations.py`) keeps SHA-256 digests, not tokens:
nothing ever needs the secret back, so `authorizations.json` is not
itself a credential.  No salt and no KDF -- a token is 256 bits of
`secrets`, so there is no dictionary to attack and a work factor would
only slow the request path.  Expiry is wall clock, the one place in this
project where that is right: every broker deadline is CLOCK_BOOTTIME so
an idle window survives an NTP step, but "valid for thirty days" is a
calendar statement that has to outlive a reboot.  Every read-modify-write
takes a flock, because two processes write this file -- the server
stamping `last_used` and an operator running `token mint` -- and the
atomic replace alone prevents a torn read, not a lost update.

`--toolsets` on a token, not just at launch, because the flag is
per-process and one HTTP server has many callers: a per-process tool
budget stops being a per-caller one the moment the transport is shared.
The intersection applies, so a token cannot widen what the unit was
started with.  `server.build` takes a chooser instead of a fixed list to
make that possible; the stdio path passes none and closes over its
selection exactly as before.

Three things in the request path are deliberate.  `default_allowed_hosts`
exists because the SDK's DNS-rebinding check is allowlist-only with no
implicit localhost -- protection on with an empty list 421s *every*
request -- so the allowlist is derived from the bind address rather than
the protection being switched off to get a working default; a wildcard
bind derives nothing and is refused, which makes binding every interface
the case where the hostnames must be said out loud.  The grant travels in
the ASGI scope and not a contextvar, because in stateful mode the session
manager runs the handler in a task owned by its own lifespan and a
contextvar set in middleware would not be visible there.  And a refusal
is a 401 with an empty body that never echoes the token and never says
which of unknown, revoked or expired it was -- the discipline
`hhstream_live.server` already applies to a wrong phrase, with that app's
own RateLimiter reused rather than a second one grown.

This is NOT MCP's authorization specification, which is OAuth 2.1 plus
RFC 9728 metadata discovery.  A client that can only discover an
authorization server will not connect; one that lets you set a header
will.  Documented as a limit rather than hidden, beside the two the SDK
already imposes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 17:53:31 +00:00

458 lines
17 KiB
Python

"""The token store: who may reach this server over HTTP.
Standard library only, and no MCP import, so the whole of it is testable
without the SDK -- the same split :mod:`hhstream_mcp.tools` keeps.
**This exists because of the HTTP transport and nothing else.** Over stdio the
client spawns the server, and whoever can spawn it already holds the broker's
control socket (``0660``, ``sessions.group``): a token checked by a process the
caller started is a lock whose key is in the same pocket. Bind a port and the
caller is no longer someone who passed a filesystem permission check on the way
in, and that is the moment a credential starts meaning something.
What is on disk
---------------
One JSON object in ``<state>/authorizations.json``::
{"version": 1, "grants": [{"id": …, "label": …, "hash": …, …}]}
**The file holds SHA-256 hashes, not tokens.** Nothing here ever needs the
secret back -- ``mint`` prints it once and forgets it -- so storing the digest
costs nothing and means a readable ``authorizations.json`` is not itself a
credential. No salt and no KDF, deliberately: a token is
:func:`secrets.token_urlsafe` over 32 bytes, so there is no dictionary to
attack and a work factor would only slow the legitimate request path. This
diverges from the live stream, which keeps a phrase in cleartext in the session
record (`docs/plans/2026-10-03-network-stream.md`) -- it has to, because
``serve --stream`` needs it back.
Expiry is **wall clock**, which is the one place in this project that is the
right choice. Every deadline in the broker is ``CLOCK_BOOTTIME`` (see
:mod:`hhstreamd.clock`) because an idle window must survive an NTP step and
count time spent suspended. A token minted for thirty days is a calendar
statement that has to outlive a reboot, and BOOTTIME resets to zero there.
Concurrency
-----------
Two processes write this file: the HTTP server, stamping ``last_used``, and an
operator running ``hhstream-mcp token mint`` in a shell. The atomic replace
borrowed from :func:`hhstreamd.registry.atomic_write_json` keeps a reader from
ever seeing half a file, but it does not stop a lost update -- the server could
rewrite the table it read a moment before the mint landed, and the new token
would vanish. So every read-modify-write takes an exclusive ``flock`` on a
sidecar lock file first. ``verify`` on the hot path takes no lock at all: it
only reads, and a stale read costs one request.
"""
from __future__ import annotations
import base64
import contextlib
import fcntl
import hashlib
import hmac
import json
import logging
import os
import secrets
from collections.abc import Iterator, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from hhstreamd.clock import Clock, iso
from hhstreamd.registry import atomic_write_json
log = logging.getLogger("hhstream.mcp.auth")
#: Where the tokens live when nothing says otherwise. **Not** the broker's
#: ``sessions.stateDir``: that directory is ``0700`` owned by the broker's user
#: and holds ``events.jsonl``, the audit trail, and the MCP server runs as
#: whichever user's client spawned it. Handing this shim write access to the
#: audit trail's directory to park a token file in it would be a wider grant
#: than the feature needs.
DEFAULT_STATE_DIR = "/var/lib/hhstream-mcp"
ENV_STATE_DIR = "HHSTREAM_MCP_STATE_DIR"
#: The file, and the lock beside it.
STORE_NAME = "authorizations.json"
LOCK_NAME = ".authorizations.lock"
#: Prefix on every minted token. Not a namespace and not parsed on the way in
#: -- it is there so a leaked token is identifiable on sight, in a log, a shell
#: history or a committed config, which is the convention secret scanners are
#: built around.
TOKEN_PREFIX = "hhsmcp_"
#: 32 bytes of ``secrets`` is 256 bits. Nothing about the length is a
#: trade-off: the token is pasted into a client configuration, never typed and
#: never read aloud, which is exactly why this is not
#: :mod:`hhstream_live.phrase` -- a phrase buys sayability with 77 bits, and
#: there is nobody here to say it to.
TOKEN_BYTES = 32
#: The on-disk format. Written on every save and refused on load if unknown,
#: so a file from a future version is a named error rather than a table that
#: silently loses the fields this code does not know about.
FORMAT_VERSION = 1
#: How often ``last_used`` is allowed to reach the disk. A write per request
#: would turn a read-only tool call into a file replace and a lock round-trip;
#: the stamp is for an operator asking "is this token still in use", and an
#: hour is well inside that question's resolution. Same reasoning, and the
#: same shape, as ``registry.ACTIVITY_FLUSH_INTERVAL_S``.
LAST_USED_FLUSH_S = 3600.0
#: Bound on the operator's label, so one pathological ``--label`` cannot make
#: the table unreadable.
MAX_LABEL_CHARS = 128
class StoreError(Exception):
"""The store could not be used. Carries a message fit for a CLI error."""
class NoSuchGrant(StoreError):
"""A token id that is not in the table."""
def hash_token(token: str) -> str:
"""The digest stored for ``token``. Hex, lowercase, 64 characters."""
return hashlib.sha256(token.encode("utf-8")).hexdigest()
def mint_token() -> str:
"""A fresh bearer token. Returned once and never stored."""
return TOKEN_PREFIX + secrets.token_urlsafe(TOKEN_BYTES)
def mint_id(taken: set[str]) -> str:
"""``<6 base32 chars>`` -- the handle revocation uses.
An id and not the token: ``token revoke`` takes this, so ending a grant
never means pasting a live secret onto a command line that lands in a shell
history. Shaped like :func:`hhstreamd.registry.mint_id`'s suffix for the
same reason -- base32 lowercase has no character a reader confuses.
"""
for _ in range(1000):
raw = secrets.token_bytes(5)
candidate = base64.b32encode(raw).decode("ascii").rstrip("=").lower()[:6]
if candidate not in taken:
return candidate
raise StoreError("could not mint an unused token id") # pragma: no cover
@dataclass
class Grant:
"""One authorization: what the table knows about a token it cannot show."""
id: str
hash: str
label: str = ""
created: str = ""
expires_at: float | None = None
last_used: str | None = None
#: The toolsets this token may call, or ``None`` for every tool. Stored
#: from the first version even though the HTTP server is what enforces it,
#: because ``--toolsets`` is a *launch-time* flag and the moment one
#: process serves several callers a per-process tool budget has stopped
#: being a per-caller one. The token is the only place that distinction
#: can live, and adding the field later would be a file-format migration
#: for no reason.
toolsets: tuple[str, ...] | None = None
def to_dict(self) -> dict[str, Any]:
return {
"id": self.id,
"hash": self.hash,
"label": self.label,
"created": self.created,
"expires_at": self.expires_at,
"last_used": self.last_used,
"toolsets": list(self.toolsets) if self.toolsets is not None else None,
}
@classmethod
def from_dict(cls, raw: dict[str, Any]) -> Grant:
toolsets = raw.get("toolsets")
return cls(
id=str(raw["id"]),
hash=str(raw["hash"]),
label=str(raw.get("label") or ""),
created=str(raw.get("created") or ""),
expires_at=(
float(raw["expires_at"]) if raw.get("expires_at") is not None else None
),
last_used=raw.get("last_used") or None,
toolsets=tuple(str(name) for name in toolsets) if toolsets else None,
)
def expired(self, now: float) -> bool:
return self.expires_at is not None and now >= self.expires_at
def expires_iso(self) -> str | None:
return iso(self.expires_at) if self.expires_at is not None else None
@dataclass
class Store:
"""The table on disk, read and written under a lock."""
path: Path
clock: Clock = field(default_factory=Clock)
@classmethod
def at(cls, state_dir: Path | str | None = None, clock: Clock | None = None) -> Store:
"""The store under ``state_dir``, ``$HHSTREAM_MCP_STATE_DIR``, or the default."""
root = Path(
state_dir
if state_dir is not None
else os.environ.get(ENV_STATE_DIR, DEFAULT_STATE_DIR)
)
return cls(path=root / STORE_NAME, clock=clock or Clock())
@property
def state_dir(self) -> Path:
return self.path.parent
# ---- the lock ----------------------------------------------------
@contextlib.contextmanager
def _locked(self) -> Iterator[None]:
"""Exclusive access for one read-modify-write.
The lock is a sidecar rather than the store itself, because the store
is *replaced* on every write -- a descriptor held on it would be a
descriptor on an unlinked inode, and the next writer would lock a
different file and think itself alone.
"""
self.ensure_dir()
lock_path = self.state_dir / LOCK_NAME
fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
yield
finally:
os.close(fd)
def ensure_dir(self) -> None:
"""Create the state directory if the supervisor has not.
In the deployed shape ``StateDirectory=`` in the unit makes this (and
its mode and owner) declarative; the same reasoning, and the same
fallback, as :meth:`hhstreamd.registry.Registry.ensure_dirs`.
"""
try:
self.state_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
except OSError as exc:
raise StoreError(f"cannot create {self.state_dir}: {exc}") from exc
# ---- reading -----------------------------------------------------
def load(self) -> list[Grant]:
"""Every grant, newest last. A missing file is an empty table."""
try:
raw = self.path.read_text(encoding="utf-8")
except FileNotFoundError:
return []
except OSError as exc:
raise StoreError(f"cannot read {self.path}: {exc}") from exc
try:
data = json.loads(raw)
except json.JSONDecodeError as exc:
raise StoreError(f"{self.path} is not valid JSON: {exc}") from exc
if not isinstance(data, dict):
raise StoreError(f"{self.path} is not an authorization table")
version = data.get("version")
if version != FORMAT_VERSION:
raise StoreError(
f"{self.path} is format version {version!r}, and this build "
f"understands {FORMAT_VERSION}. A newer hhstream-mcp wrote it."
)
try:
return [Grant.from_dict(entry) for entry in data.get("grants", [])]
except (KeyError, TypeError, ValueError) as exc:
raise StoreError(f"{self.path} has an unreadable grant: {exc}") from exc
def _write(self, grants: Sequence[Grant]) -> None:
"""Replace the table. Call under :meth:`_locked`."""
self.ensure_dir()
atomic_write_json(
self.path,
{"version": FORMAT_VERSION, "grants": [g.to_dict() for g in grants]},
)
# `atomic_write_json` creates the temp file with the default mode, so
# the mode is set on the thing that survives the replace. The file is
# not a credential (it holds digests), but it is the list of who may
# drive this desktop, and that is nobody else's business either.
try:
os.chmod(self.path, 0o600)
except OSError as exc: # pragma: no cover -- the write just succeeded
log.warning("cannot chmod %s: %s", self.path, exc)
# ---- writing -----------------------------------------------------
def mint(
self,
*,
label: str = "",
ttl: float | None = None,
toolsets: Sequence[str] | None = None,
) -> tuple[Grant, str]:
"""Add a grant and return it with its token. The token is not stored."""
token = mint_token()
with self._locked():
grants = self.load()
now = self.clock.wall()
grant = Grant(
id=mint_id({g.id for g in grants}),
hash=hash_token(token),
label=label[:MAX_LABEL_CHARS],
created=iso(now),
expires_at=(now + ttl) if ttl is not None else None,
toolsets=tuple(toolsets) if toolsets else None,
)
self._write([*grants, grant])
return grant, token
def revoke(self, grant_id: str) -> Grant:
"""Remove one grant by id. Raises :class:`NoSuchGrant` if it is not there."""
with self._locked():
grants = self.load()
kept = [g for g in grants if g.id != grant_id]
if len(kept) == len(grants):
raise NoSuchGrant(
f"no token with id {grant_id!r}. `hhstream-mcp token list` "
"shows the ids."
)
gone = next(g for g in grants if g.id == grant_id)
self._write(kept)
return gone
def revoke_all(self) -> list[Grant]:
"""Empty the table. Returns what was in it."""
with self._locked():
grants = self.load()
self._write([])
return grants
def prune(self) -> list[Grant]:
"""Drop expired grants. Returns what was dropped.
Not required for correctness -- :meth:`verify` refuses an expired grant
whether or not it is still on disk -- so this is housekeeping, and it
is a separate call rather than a side effect of a read for that reason.
"""
now = self.clock.wall()
with self._locked():
grants = self.load()
dead = [g for g in grants if g.expired(now)]
if dead:
self._write([g for g in grants if not g.expired(now)])
return dead
# ---- the hot path ------------------------------------------------
def verify(self, token: str, *, stamp: bool = True) -> Grant | None:
"""The grant this token belongs to, or ``None``.
``None`` covers every way a token can fail -- unknown, revoked, expired
-- on purpose. The caller's answer is one 401 either way, and a richer
return would only tempt it into saying which, to someone who should not
be told they guessed a real id.
The digest comparison is :func:`hmac.compare_digest` even though both
sides are already hashes: the cost is nothing and it keeps the function
free of a timing signal that a later refactor might otherwise make
meaningful.
"""
if not token:
return None
digest = hash_token(token)
now = self.clock.wall()
try:
grants = self.load()
except StoreError as exc:
# A broken table denies everything rather than allowing anything.
log.error("authorization table unusable, refusing: %s", exc)
return None
for grant in grants:
if not hmac.compare_digest(grant.hash, digest):
continue
if grant.expired(now):
return None
if stamp:
self._stamp(grant, now)
return grant
return None
def _stamp(self, grant: Grant, now: float) -> None:
"""Record that ``grant`` was used, at most once per flush interval.
Never raises: a stamp that could not be written is not a reason to
refuse a request that was authorized. Same trade as the audit log's
(:mod:`hhstreamd.audit`).
"""
if grant.last_used:
try:
age = now - _epoch(grant.last_used)
except ValueError:
age = LAST_USED_FLUSH_S + 1.0
if age < LAST_USED_FLUSH_S:
return
stamped = iso(now)
try:
with self._locked():
grants = self.load()
for entry in grants:
if entry.id == grant.id:
entry.last_used = stamped
break
else:
# Revoked between the verify and the stamp. Nothing to
# record, and re-adding it would resurrect a dead grant.
return
self._write(grants)
except (StoreError, OSError) as exc:
log.warning("cannot stamp last_used for %s: %s", grant.id, exc)
return
grant.last_used = stamped
def _epoch(stamp: str) -> float:
"""An ISO stamp this module wrote, back as an epoch."""
import datetime as _dt
return _dt.datetime.fromisoformat(stamp.replace("Z", "+00:00")).timestamp()
__all__ = [
"DEFAULT_STATE_DIR",
"ENV_STATE_DIR",
"FORMAT_VERSION",
"Grant",
"NoSuchGrant",
"STORE_NAME",
"Store",
"StoreError",
"TOKEN_PREFIX",
"hash_token",
"mint_token",
]