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