Files
hyprland-headless-stream-pl…/src
HermenixandClaude Opus 5 242a2b9413 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-11 20:40:22 +00:00
..