Files
hyprland-headless-stream-pl…/docs/TODO/mcp-tokens-do-not-scope-resources.md
T
HermenixandClaude Opus 5 1fab00f2bf docs(mcp)!: mcp-v2.1, 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 -- but **v2.1 and not v3, because
nothing breaks**.  No tool renamed, no argument reshaped, no resource
moved; a client written against v2 over stdio still works unchanged.  v2
was a major bump because it *removed* five tools.  A point release is
what an additive change is.

§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-11 22:41:20 +00:00

76 lines
4.3 KiB
Markdown

# A token narrows the tools it may call, and none of the state it may read
## The issue
`hhstream-mcp token mint --toolsets frames` makes a token that is offered three
tools — `shot`, `record`, `run` — and is refused `session_start`,
`session_kill`, every pointer verb and every keyboard verb. It is also offered
**all five resources and all three templates**, unchanged. So a token scoped to
"look at the screen" can read `hhstream://sessions` and learn every running
session's id, application, pid, log path and home directory; it can read
`hhstream://sessions/<id>/logs` and get an application's own output; and it can
read `hhstream://pointer` and see who holds the lease.
`tests/unit/test_mcp_http.py::test_resources_are_not_narrowed_by_a_token`
asserts this, deliberately, so the behaviour is pinned rather than incidental.
The reasoning that produced it is sound for the server's own flag and does not
survive being reused for a token. `docs/CONTRACT-mcp.md` §2 keeps resources out
of `--toolsets` because **a tool listing is a budget and a resource is not**:
tools compete for a model's attention, resources are the host's to put in
context, and making `hhstream://sessions` conditional on the session *tools*
being enabled would couple two decisions that are not the same decision. All
true.
But `--toolsets` is set by whoever starts the process, and a token is handed to
somebody else. A budget and an authorization are different things, and
`hhstream_mcp.http.offered_for` applies the budget's rule to the
authorization — which is the bug in one sentence.
How much this matters depends entirely on a fact the code cannot see: whether
the operator hands out more than one token. With one token it is nothing. With
two of different trust, it is a confused deputy — the narrow token's holder was
told it could only look at the screen, and it can enumerate the desktop.
## Ideas
1. **A separate `--resources` list on the token.** *(recommended)* Mint takes
`--resources` naming families (`status`, `sessions`, `pointer`,
`containers`, `screen`), defaulting to all of them, and
`hhstream_mcp.resources.read` refuses a URI outside the grant with the same
`ReadRefused` a bad URI already raises. Two fields because they are two
decisions — a token that may drive the pointer does not automatically need
to read session logs — and keeping them separate means the *server's*
`--toolsets` can go on meaning only what it means now.
2. **Derive the resource grant from the toolsets.** `frames` implies
`hhstream://status`, `screen` and `outputs/{name}`; `sessions` implies the
session resources; `pointer` implies `hhstream://pointer`. One field, no new
vocabulary, and it maps the way a reader would guess. Rejected as the
recommendation because the mapping is a guess: `hhstream://containers` is a
session resource that a pointer-only token genuinely needs, since the
pointer aims at a session's output, and a derived rule would have to special
case it.
3. **A single `--read-only-everything` / `--no-read` switch.** The cheap version:
a token either reads all state or none. Honest and tiny, and strictly better
than today. But "none" breaks the pointer tools for the reason above, so it
would be a switch nobody could use with a narrow token.
4. **Leave it and document it.** What ships. Defensible while this machine has
one operator and the tokens all belong to them, which is why this is medium
rather than high — but it is the option that gets less defensible the moment
a second token is minted for someone else.
## Why it matters
Medium. The surface it exposes is read-only and this is a single-operator
machine today, so nothing is currently reachable through it that the token
holder could not also learn by taking a screenshot and reading the window
titles — which `frames` lets it do.
It becomes real with the second token. `--toolsets` on a token is advertised
as the way to hand out a *restricted* credential, and the restriction is
narrower than it reads: an operator who mints a `frames` token for a
screen-watching agent has not stopped that agent from enumerating sessions, and
nothing in the surface or the mint output says so. Until this is fixed, that
sentence belongs in the answer to "can I give out a limited token" — which is
what this file is for.