`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
458 lines
17 KiB
Python
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",
|
|
]
|