Files
HermenixandClaude Opus 5 10176356b6 docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

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

89 lines
5.2 KiB
Markdown

# The HTTP transport's bearer token is not MCP authorization
## The issue
`hhstream-mcp serve --http` requires `Authorization: Bearer <token>` on every
request, where the token is a static secret an operator minted with
`hhstream-mcp token mint` and pasted into a client's configuration. That is not
what the Model Context Protocol says authorization is.
The specification's authorization profile is **OAuth 2.1 plus RFC 9728
protected-resource metadata**. A compliant server answers an unauthenticated
request with a `401` whose `WWW-Authenticate` carries a `resource_metadata`
parameter pointing at `/.well-known/oauth-protected-resource`; the client
fetches that, learns which authorization server to talk to, discovers *its*
metadata, and runs a real flow with scopes, refresh and revocation. The MCP
Python SDK ships the machinery for this — `mcp.server.auth`, its
`TokenVerifier` protocol, `AuthSettings` with an `issuer_url` and a
`resource_server_url`, and `RequireAuthMiddleware`.
What ships here is `hhstream_mcp.http.BearerAuth`, forty lines of ASGI
middleware that looks the token up in a file. The `401` carries
`WWW-Authenticate: Bearer realm="hhstream"` and nothing else, because there is
no authorization server to point at and advertising a metadata endpoint that
does not exist would be worse than advertising nothing.
The measured consequences, in order of how soon they are met:
1. **A client that only knows how to discover an authorization server cannot
connect.** It will read the `401`, find no `resource_metadata`, and have
nowhere to go. A client that lets a human set a header connects
immediately — which is most of them today, and is why this is usable at all.
2. **There is no rotation and no expiry negotiation.** `token mint
--expires-in` sets a fixed lifetime at mint time and nothing can extend it;
a client that wants to keep working past it needs a human to mint another
one. There is no refresh token because there is no token endpoint.
3. **There are no scopes in the protocol's sense.** A token carries
`toolsets`, which is this project's own notion and invisible to a client:
nothing in the handshake tells a caller what its token may do, so an agent
discovers its own limits by being refused. (`AccessToken.scopes` is where
these would go if the SDK's path were taken, and the SDK's middleware is
what would then enforce them.)
4. **Audience is unchecked.** RFC 8707 resource indicators exist so a token
minted for one server cannot be replayed at another. These tokens name no
audience, so a token is as good as the operator's care in handing it out.
## Ideas
1. **Keep it, and say so.** *(what ships, and the recommended route for now)*
The threat this transport actually faces is "someone on the LAN finds the
port", and a 256-bit token in a header answers it. OAuth would add an
authorization server to deploy, a metadata document to serve and a flow to
get right, in exchange for no additional protection against that threat on
a single-operator machine. The honest version of this option is the one
taken: a limit written down, not a capability implied.
2. **Implement the SDK's `TokenVerifier` over the same table.** The protocol is
one method (`async verify_token(token) -> AccessToken | None`) and the store
already satisfies it in all but name — `Store.verify` returns a `Grant` and
an `AccessToken` is a `Grant` with `client_id` and `scopes` spelled
differently. That alone buys spec-shaped *verification* and lets
`toolsets` become real `scopes`, enforced by the SDK's middleware rather
than by `offered_for`. It does **not** buy discovery: without an issuer
there is still no metadata to advertise. *(recommended as the next step, if
one is wanted — it is small, and it is the half that pays.)*
3. **Serve the metadata documents and be a resource server for real.** Mint
tokens as signed JWTs with an audience and an expiry, serve
`/.well-known/oauth-protected-resource`, and accept an external
authorization server's tokens as well as locally minted ones. This is the
complete answer and is a feature in its own right, worth doing when a client
that needs it actually appears.
4. **Drop the HTTP transport and tunnel stdio over SSH instead.** Rejected, but
worth recording as the thing this competes with: `ssh host hhstream-mcp` is
genuinely more secure — real keys, real TLS-grade transport, and no new
listener — and for one operator with one machine it is the better answer. The
HTTP transport exists for the client that cannot spawn a process over SSH,
which is most hosted ones.
## Why it matters
Medium, and the severity is about *interoperability* rather than about safety.
Nothing here is weaker than it claims to be: the token is 256 bits, the refusal
leaks nothing, revocation is immediate, and loopback is the default. What is
missing is the part that lets an arbitrary MCP client connect without a human
pasting a header — so the cost is paid in which clients work, not in how
exposed the desktop is.
It would move to high the moment this server is meant to be reached by a client
somebody else configured, because at that point "set this header" stops being
an instruction anyone can follow.