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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-12 18:00:05 +00:00
1 parent 7eb9afdfa3
commit 10176356b6
8 files changed
+504 -31

No files matched your search

+28 -3
View File
@@ -51,10 +51,21 @@ import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the 21 acting verbs
hhstream-mcp --list-tools # the 23 acting verbs
hhstream-mcp --list-resources # the 10 read-only URIs
# the HTTP transport, which is the only part that needs a credential
export HHSTREAM_MCP_STATE_DIR=$PWD/.mcp-state
hhstream-mcp token mint --label dev # the token, once, on stdout
hhstream-mcp serve --http # 127.0.0.1:9989/mcp
```
stdio is unauthenticated on purpose and the HTTP transport is not: a stdio
client spawns the server and so already holds the broker's socket, while a port
is reachable by someone who passed no permission check. `docs/CONTRACT-mcp.md`
§1 has the argument; `token mint` prints the secret once and the table on disk
keeps only its digest.
## The checks
| Check | What it proves | Needs a VM |
@@ -72,6 +83,8 @@ hhstream-mcp --list-resources # the 10 read-only URIs
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
| `vm-mcp-http` | the **HTTP transport, its token and its unit**: the unit refusing to start while the authorization table is empty *and* saying so in the journal, then coming up by itself within one retry interval of the first `token mint` with no `systemctl start` — the half that nothing in Python can test; the state directory `0700` and owned by the account that mints tokens, the table `0600` and holding no token; the port on loopback only and **not** in the firewall; an unauthenticated and a wrong-token request both `401` with an empty body and no echo; a good token completing the handshake, reading a resource and calling a tool against the live broker; two tokens served by **one process** with different tool budgets; and a revocation taking effect on the next request with no restart | yes |
All of them at once:
```bash
@@ -96,6 +109,7 @@ nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
nix build -L .#checks.x86_64-linux.vm-mcp-http
nix build -L .#checks.x86_64-linux.vm-stream
```
@@ -125,11 +139,15 @@ output is on that path beside it, and `mcp` is in the test environment, because
— not optionally: a file that skipped when the SDK was absent would be green in
exactly the build where a malformed tool schema mattered.
The MCP suite is four files, split along what each can be tested without:
The MCP suite is six files, split along what each can be tested without:
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
writes), `test_mcp_authorizations.py` (the token store and the `token` verbs --
standard library, no SDK), `test_mcp_server.py` (the SDK wiring, over its
memory transport, plus the command line now that it has subcommands) and
`test_mcp_http.py` (the bearer check and the per-token toolsets, over a real
ASGI stack).
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
@@ -264,11 +282,18 @@ checks/
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
JSON-RPC client against the live broker
vm-mcp-http.nix nixosTest, the HTTP transport: the unit's refusal while
no token exists and its self-heal after the first mint,
the 0700 state dir, the refusals, and two tokens with
different tool budgets served by one process
vm-stream.nix nixosTest, `session stream enable` and a real HTTP
viewer reading MJPEG from inside the guest
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
NOT the MCP SDK's -- the SDK on both ends would agree
with itself about a framing neither side had to get right
lib/mcp_http_client.py the same choice over HTTP: hhs-mcp-http, urllib only,
with a distinct exit status for an HTTP refusal so a
401 cannot be mistaken for a server that died
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share
+58 -5
View File
@@ -122,8 +122,8 @@ services.hyprland-headless-stream = {
};
```
Then register it with a client. The transport is **stdio** — one process per
client, spawned by the client, no port and no daemon — so the whole
Then register it with a client. The default transport is **stdio** — one
process per client, spawned by the client, no port and no daemon — so the whole
configuration is a command and an environment:
```json
@@ -161,9 +161,62 @@ what is offered to whichever families are wanted — `frames`, `sessions`,
```
Resources are deliberately *not* narrowed by it: they are the host's context,
not the model's tool budget. Nothing else about the server is configurable — it
holds no state and caches no lease, and the pointer lease is an explicit
argument on every gesture tool for exactly that reason.
not the model's tool budget. The server holds no state and caches no lease, and
the pointer lease is an explicit argument on every gesture tool for exactly that
reason.
### Over a port instead, for a client that cannot spawn a process
`mcp.http.enable` serves the same surface over Streamable HTTP, as a unit,
behind a bearer token:
```nix
services.hyprland-headless-stream.mcp.http.enable = true; # 127.0.0.1:9989/mcp
```
```console
$ sudo -u hermes hhstream-mcp token mint --label laptop --expires-in 90d
hhsmcp_…
minted a7k2qp (laptop), expires 2026-01-09T12:00:00Z, toolsets all.
This is the only time the token is shown.
```
```json
{
"mcpServers": {
"hhstream": {
"url": "http://127.0.0.1:9989/mcp",
"headers": { "Authorization": "Bearer hhsmcp_…" }
}
}
}
```
**stdio stays unauthenticated and that is not an oversight.** A stdio client
spawns the server, so it has already passed a filesystem permission check and
holds the broker's socket either way — a token there would be a lock whose key
is in the same pocket. A port is the first time the caller is someone who did
neither, which is the entire reason the token exists. The two options are
independent; neither implies the other.
Three things worth knowing before enabling it:
- **The unit refuses to start until a token exists**, and retries every five
seconds, so it comes up on its own moments after the first `token mint`. A
listener that `401`s every request is almost always a forgotten mint, and
`systemctl status hhstream-mcp` says so in as many words.
- **There is no TLS.** The token crosses the wire in clear text. Loopback is the
default and an SSH tunnel is the simplest way to reach it from elsewhere; a
LAN bind wants a reverse proxy, and the module warns about it.
- **It is not MCP's OAuth profile.** A client that can only discover an
authorization server will not connect; one that lets you set a header will.
See `docs/TODO/mcp-http-auth-is-not-oauth.md`.
`token list` shows the ids, labels and last use; `token revoke <id>` takes
effect on the next request with no restart. A token can carry its own
`--toolsets`, which is the only way to give two clients different tool budgets
from one process — though it narrows tools and *not* resources, which is
`docs/TODO/mcp-tokens-do-not-scope-resources.md`.
| Document | What it is |
|---|---|
+16 -3
View File
@@ -44,10 +44,10 @@
│ in-process: argv in, exit code out
│
┌────────────┴──────────────┐
│ hhstream-mcp │ spawned per client, stdio only
│ hhstream-mcp │ stdio: spawned per client
│ 23 tools (the acts) │◀─── an MCP client's JSON-RPC
│ 10 resources (the state)│
└───────────────────────────┘
│ 10 resources (the state)│ http: one unit, one port,
└───────────────────────────┘ a bearer token per request
```
Six pieces, deliberately separate, and a seventh that is deliberately not a
@@ -104,6 +104,19 @@ And the seventh, which is a *shim* and not a layer:
which is why it is a separate derivation (`nix/mcp.nix`) and why
`packages.hhstream` — the compositor's own units — keeps the closure it had.
It is the only component with **two transports**, and the only one that
authenticates anything. Over stdio it does not, because there is nothing
there to authenticate: the client spawns the process, so it has already
passed a filesystem permission check and holds the `0660` control socket
either way — unix permissions are the gate, and a token checked by a process
the caller started guards a lock whose key is in the same pocket. Over HTTP
(`mcp.http.enable`) it is a unit on a port, the caller passed no such check,
and a bearer token is then the only gate there is. That asymmetry is the
whole of why the credential exists, and it is also why this shim has a state
directory of its own (`mcp.stateDir`) while owning no state about the
desktop: the authorization table is about *callers*, not about sessions, and
it has no business in the broker's `0700` directory beside the audit trail.
## Why containers are outputs
A session's container is a headless **output**, not just a workspace, and the
+227 -20
View File
@@ -1,4 +1,4 @@
# CONTRACT — the MCP server (mcp-v3)
# CONTRACT — the MCP server (mcp-v4)
This file is the interface of `hhstream-mcp`: the resource URIs, the tool names,
the arguments each takes, what comes back, and which of the CLI's exit codes
@@ -10,9 +10,19 @@ containers and the input lease).
these argument shapes is a consumer like any other, and renaming a tool breaks
it exactly as renaming a wire verb would.
Version: mcp-v3 (2026-10-11). v1 was the first freeze and lasted one day; v2
split state out into resources; v3 adds the live stream. v3 is **additive** —
every v2 name still means what it meant.
Version: mcp-v4 (2026-10-12). v1 was the first freeze and lasted one day; v2
split state out into resources and removed five tools; v3 adds the live stream;
v4 adds a second transport. v3 and v4 are **additive** — every v2 name still
means what it meant.
v4 changes: a second transport, and the credential it exists for
| § | Change | Why |
| --- | --- | --- |
| §1 | A **second transport**: Streamable HTTP, opt-in, behind a bearer token. stdio stays the default and stays unauthenticated. | A token means nothing on stdio — the client spawns the server, so it has already passed a filesystem permission check and holds the broker's `0660` socket either way. A port is the first time the caller is someone who did neither, and the transport and the credential are therefore one feature. |
| §2 | `serve --http` and its flags; `token mint\|list\|revoke\|prune` beside it. The bare `hhstream-mcp` and `hhstream-mcp --toolsets=…` forms are unchanged. | A client's `command` entry is a configuration someone else wrote — an HTTP endpoint is a configuration someone else *hosts*. |
| §3 | A token may carry its own `toolsets`, and the **intersection** with the server's `--toolsets` applies. | `--toolsets` is a launch-time flag, and one HTTP process serves many callers: a per-process tool budget stops being a per-caller one the moment the transport is shared. |
| §10 | What the HTTP transport's token **is not**: not OAuth 2.1, not RFC 9728, no metadata discovery. | A limit worth stating in the same register as the two the SDK imposes. |
v3 changes, all of them the per-session live stream
(`docs/CONTRACT-sessions.md` §4, v4):
@@ -75,16 +85,73 @@ documented in `hhstream_mcp.invoke`: `cli.main`'s `sg` re-exec, and `cmd_run`'s
## 1. Transport
**stdio, and only stdio.** One process per client, spawned by the client; no
port, no daemon, no socket of its own. There is already a daemon in this system
and it owns all the state.
**Two, and stdio is the default.**
The protocol is **not on file descriptor 1** once the server is running: the
tools run the CLI in process, the CLI prints, and `record` spawns an `ffmpeg`
whose output the CLI does not capture. The server takes a private duplicate of
stdin and stdout at start-up, then points fd 1 at its log and fd 0 at
`/dev/null`. A stray write is therefore a log line and never a corrupted
stream.
| transport | how | authentication |
| --- | --- | --- |
| **stdio** | `hhstream-mcp`, or `hhstream-mcp serve`. One process per client, spawned by the client; no port and no daemon. | **None, deliberately.** See below. |
| **Streamable HTTP** | `hhstream-mcp serve --http`, or the `mcp.http.enable` unit. One process, many clients, one port. | A bearer token on every request, or `401`. |
### Why stdio is unauthenticated, and why that is not an oversight
The stdio server is spawned *by* its client. To do that the client already had
to pass a filesystem permission check, and whoever can run `hhstream-mcp` can
run `hhstream` — which talks to the same `0660` control socket owned by
`sessions.user`, in the same group. **Unix permissions are the gate**, and
`mcp.enable`'s own option text has always said so: it "grants no access the
`hhstream` CLI does not already grant to whoever runs it". A token checked by a
process the caller started is a lock whose key is in the same pocket.
Which is also the whole argument for the HTTP transport existing. A port is
reachable by a caller who passed no filesystem check, and at that moment a
credential is the only gate there is. So the two arrived together: v1 and v2
said "stdio, and only stdio" because, for what the server then was, that was
the honest answer.
### stdio: the protocol is not on file descriptor 1
Once the server is running: the tools run the CLI in process, the CLI prints,
and `record` spawns an `ffmpeg` whose output the CLI does not capture. The
server takes a private duplicate of stdin and stdout at start-up, then points
fd 1 at its log and fd 0 at `/dev/null`. A stray write is therefore a log line
and never a corrupted stream.
This is also why `token mint` prints a secret on stdout and is safe: the token
verbs return *before* anything claims the transport, which
`tests/unit/test_mcp_authorizations.py` asserts with a `claim_transport` that
fails the test if it is reached.
### HTTP: what is on the wire
* **`Authorization: Bearer <token>` on every request.** The scheme is compared
case-insensitively (RFC 9110). Anything else — absent, malformed, wrong
scheme, unknown token, revoked token, expired token — is one answer: `401`,
an **empty body**, `WWW-Authenticate: Bearer realm="hhstream"`,
`Cache-Control: no-store`. The token is never echoed, in the body or in a
header, and the response does not distinguish *which* of those it was —
telling them apart would tell someone who guessed a real id that they had.
* **Failed attempts are rate-limited per client**, reusing
`hhstream_live.server`'s `RateLimiter`; past the limit the refusal is `429`.
* **The token is checked before the `Host`.** An unauthenticated caller learns
nothing about the rebinding allowlist, which is itself a hint about how the
server is deployed.
* **Any path but the mounted one is a `401` without a token** and a `404` with
one. An unauthenticated caller does not learn what is mounted, or that
anything is.
* **DNS-rebinding protection is on.** The `Host` allowlist is derived from the
bind address when none is given, because the SDK's check is allowlist-only
with no implicit localhost — protection on with an empty list `421`s *every*
request. A wildcard bind derives nothing and is refused at launch, which
makes binding every interface the one case where the hostnames must be named.
* **No TLS.** The token crosses the wire in clear text. Loopback is the
default; anything else wants a reverse proxy and says so in a module warning.
* **Tool calls are serialised across every caller**, not per session. The
`Runner` holds a process-wide lock because the CLI it calls prints to a
stdout this process shares — invisible while each client had a process of its
own, visible now that one process serves many. Two agents on two tokens queue
behind each other, and a slow call delays everyone's next one rather than
only its own caller's. Latency, never a hang: the event loop answers a `ping`
throughout. See `docs/TODO/mcp-in-process-has-no-call-deadline.md`.
## 2. Configuration
@@ -99,17 +166,87 @@ the CLI:
Set them in the MCP client's `env` block. One place to configure them is one
place for them to be wrong.
The server's own command line:
The HTTP transport reads one more, and `hhstream-mcp token` reads the same:
| flag | what it does |
| Variable | What it names | Default |
| --- | --- | --- |
| `HHSTREAM_MCP_STATE_DIR` | where the authorization table lives | `/var/lib/hhstream-mcp` |
**Not `sessions.stateDir`.** That directory is `0700` owned by the broker's
user and holds `events.jsonl`, the audit trail; the MCP server runs as whichever
user's client spawned it, and parking a token file there would mean granting
this shim write access to the audit trail's directory for no reason. The two
also have different lifetimes: revoking every token must not be able to touch a
session record.
The server's own command line. `hhstream-mcp` with no subcommand, and
`hhstream-mcp serve`, are the same thing — the bare form is not deprecated and
will not be, because an MCP client's `command` entry is a configuration
somebody else wrote:
| flag | where | what it does |
| --- | --- | --- |
| `--toolsets NAMES` | either | comma-separated families to offer as **tools**: `frames`, `sessions`, `pointer`, `keyboard`. Omitted, every tool is offered. An unknown name is argparse's exit 2, never a silently empty server. **Resources are not filtered by it** — they are the host's context, not the model's tool budget, and making `hhstream://sessions` conditional on the session *tools* would couple two decisions that are not the same decision. |
| `--list-tools` | either | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
| `--list-resources` | either | print the resource URIs and templates and exit. |
| `--http` | `serve` | Streamable HTTP instead of stdio. |
| `--address HOST` | `serve` | default `127.0.0.1`. Loopback, because reaching the LAN is a second decision. |
| `--port N` | `serve` | default `9989`, one past the live stream's `9988`. |
| `--path P` | `serve` | default `/mcp`. |
| `--state-dir DIR` | `serve`, `token` | overrides `$HHSTREAM_MCP_STATE_DIR`. |
| `--allowed-host HOST` | `serve` | repeatable. Omitted, derived from `--address`; a trailing `:*` is a wildcard port. |
| `--allowed-origin ORIGIN` | `serve` | repeatable. Nothing needs this unless a browser is the client. |
| `--allow-no-tokens` | `serve` | start although the table is empty. Without it that is a usage error, because a listener that `401`s every request is almost always a forgotten `token mint`. |
| `--stateless` | `serve` | no session to pin, for a deployment behind a load balancer. |
| `--json-response` | `serve` | one JSON body instead of an SSE stream. |
### `hhstream-mcp token`
| verb | what it does |
| --- | --- |
| `--toolsets NAMES` | comma-separated families to offer as **tools**: `frames`, `sessions`, `pointer`, `keyboard`. Omitted, every tool is offered. An unknown name is argparse's exit 2, never a silently empty server. **Resources are not filtered by it** — they are the host's context, not the model's tool budget, and making `hhstream://sessions` conditional on the session *tools* would couple two decisions that are not the same decision. |
| `--list-tools` | print the table and exit. Honours `--toolsets`, so it is also how to see what a selection would offer. |
| `--list-resources` | print the resource URIs and templates and exit. |
| `token mint [--label L] [--expires-in D] [--toolsets NAMES]` | print a new token **once**, on stdout, with the prose for a human on stderr beside it. `D` is `30s`/`5m`/`3h`/`90d` or bare seconds. |
| `token list [--json]` | the table. The tokens are not in it and cannot be. |
| `token revoke <id> \| --all` | by **id**, so ending a grant never means pasting a live secret onto a command line that lands in a shell history. |
| `token prune` | drop expired grants. Housekeeping only — an expired token is refused whether or not it is still on disk. |
The table holds **SHA-256 digests, not tokens**, so `authorizations.json` is not
itself a credential; a token that was not written down can only be revoked and
replaced. No salt and no KDF: a token is `secrets.token_urlsafe(32)` behind an
`hhsmcp_` prefix — 256 bits, so there is no dictionary to attack and a work
factor would only slow the request path. The prefix is there so a leaked token
is identifiable on sight, which is the convention secret scanners are built
around.
Expiry is **wall clock**, and it is the one place in this project where that is
right. Every deadline in the broker is `CLOCK_BOOTTIME` (`hhstreamd.clock`)
because an idle window has to survive an NTP step and count time spent
suspended. "Valid for thirty days" is a calendar statement that has to outlive
a reboot, and BOOTTIME resets to zero there.
Every read-modify-write takes an exclusive `flock` on a sidecar lock file. Two
processes write this table — the server stamping `last_used`, and an operator
running `token mint` — and the atomic replace alone prevents a torn *read*, not
a lost *update*.
These verbs sit **outside** the frozen exit-code table in
`hhstreamd.protocol`, because nothing they do reaches the broker and no agent
calls them. Two of the codes are chosen by analogy with it anyway: `0` done,
`2` usage, `3` no token with that id (the analogue of `NO_SUCH_SESSION`), `4`
the store itself is unusable (the analogue of `BAD_STATE`).
`$HHSTREAM_MCP_LOG` sets the log level on stderr. Nothing else affects
behaviour; in particular the server holds no state and caches no lease.
On the HTTP transport a **token** may carry its own `toolsets`, and the
**intersection** with the server's own applies — a token cannot widen what the
unit was started with. That exists because `--toolsets` is a launch-time flag
and one HTTP process serves many callers: a per-process tool budget stops being
a per-caller one the moment the transport is shared, and the token is then the
only place the distinction can live. A tool the caller's token excludes is not
listed and cannot be reached by name; the refusal names both possible
narrowings, because the agent cannot tell them apart from where it stands and
neither is its to change.
**There is no grouping primitive in MCP**, and `--toolsets` is not pretending to
be one. The `Tool` object carries `name`, `title`, `description`,
`inputSchema`, `outputSchema`, `icons`, `annotations`, `_meta` and `execution` —
@@ -429,5 +566,75 @@ unaffected, which is what that code means.
`services.hyprland-headless-stream.mcp.enable` (default `false`) puts the
binary on the system PATH. That is the whole of the option: there is no unit, no
socket and no state directory, because the server is spawned per client over
stdio.
socket and no state directory, because the stdio server is spawned per client.
`services.hyprland-headless-stream.mcp.http.enable` (default `false`) is the
other half, and it **is** a unit — `hhstream-mcp.service`, running as
`sessions.user` with `sessions.group`, because the tools it serves are the
CLI's own handlers called in process and that CLI opens a `0660` control socket
owned by that user and a compositor runtime directory owned by that group. It
is `Wants`/`After` the broker and not `BindsTo`: the frame verbs answer with
the broker down and the rest answer exit 5, which is a true answer, whereas a
listener that vanished with the broker would turn that into a connection
refused and tell a client nothing.
The two options are independent and neither implies the other. `http.enable`
also puts the binary on PATH, because `token mint` is how the credential that
unit demands gets issued.
| option | default |
| --- | --- |
| `mcp.stateDir` | `/var/lib/hhstream-mcp`, created `0700` by a tmpfiles entry |
| `mcp.http.address` | `127.0.0.1` |
| `mcp.http.port` | `9989` |
| `mcp.http.path` | `/mcp` |
| `mcp.http.allowedHosts` / `allowedOrigins` | `[]` — hosts are derived from the address |
| `mcp.http.toolsets` | `null`, every tool |
| `mcp.http.openFirewall` | `false`, and not implied by `http.enable` |
| `mcp.http.extraArgs` | `[]` |
**The unit refuses to start while the authorization table is empty**, and
retries every five seconds rather than giving up
(`StartLimitIntervalSec = 0`). Both halves are deliberate and neither works
without the other: the refusal is there because a listener that `401`s every
request is almost always a forgotten mint, and "connection works, auth fails"
is far worse to debug than a `systemctl status` that names the remedy — but a
refusal that gave up would leave every freshly provisioned machine dead, and
minting the first token would then also need a `systemctl start` nothing told
anyone about. With the retry, the unit comes up on its own within one interval
of the first mint. `checks/vm-mcp-http.nix` asserts exactly that, because
nothing in the Python can.
Revoking *every* token does not stop the running process — it keeps its port
and refuses everyone. The startup refusal exists to catch a forgotten mint, not
to police a deliberate one.
## 10. What the HTTP transport's token is not
**Not MCP's authorization specification.** That is OAuth 2.1 plus RFC 9728
protected-resource metadata: a `401` is meant to carry a `WWW-Authenticate`
pointing at a metadata document, the client discovers an authorization server,
and a real flow happens. What this serves is a static token an operator minted
and pasted into a client's configuration.
Stated rather than discovered, because the consequences are not subtle:
* a client that can only *discover* an authorization server will not connect to
this at all;
* a client that lets you set a header works immediately;
* there is no refresh, no rotation and no revocation list beyond
`token revoke`, which is immediate because the table is read per request —
no restart, and an operator who had to restart a service to lock someone out
would not have revocation.
The gap is `docs/TODO/mcp-http-auth-is-not-oauth.md`, beside the two limits the
SDK imposes.
**A token does not scope resources.** §2 keeps resources out of `--toolsets` on
the grounds that they are the host's context rather than the model's budget, and
that argument carries over to the server's own flag. It does not carry over
cleanly to a *token*, which is an authorization and not a budget — so a token
scoped to `frames` can still read `hhstream://sessions`. That is a real gap, not
an oversight: `docs/TODO/mcp-tokens-do-not-scope-resources.md`, and
`tests/unit/test_mcp_http.py` asserts the current behaviour so that fixing it is
a visible change rather than a silent one.
+2
View File
@@ -17,6 +17,8 @@ Each file answers three questions and stops:
| [capture-binary-and-the-unit-path](capture-binary-and-the-unit-path.md) | medium | partly fixed: the module passes grim's store path and a check reads real frames; the app still never checks its capture binary |
| [mcp-in-process-has-no-call-deadline](mcp-in-process-has-no-call-deadline.md) | medium | two costs of running the CLI in process: no killable deadline, and no `sg` recovery |
| [mcp-resources-cannot-be-subscribed-to](mcp-resources-cannot-be-subscribed-to.md) | medium | the SDK hardcodes `subscribe=False`, so a log resource can only be re-read |
| [mcp-http-auth-is-not-oauth](mcp-http-auth-is-not-oauth.md) | medium | a static bearer token, not OAuth 2.1 + RFC 9728: the cost is which clients can connect, not how exposed the desktop is |
| [mcp-tokens-do-not-scope-resources](mcp-tokens-do-not-scope-resources.md) | medium | `token mint --toolsets frames` narrows the tools and not the ten resources; nothing until a second token is minted for someone else |
| [stream-does-not-reattach-after-a-broker-restart](stream-does-not-reattach-after-a-broker-restart.md) | low | the phrase survives and the sweep works; `attached` reports false until re-enabled |
| [a-stream-that-gave-up-still-reports-attached](a-stream-that-gave-up-still-reports-attached.md) | low | the other direction: a capture that permanently gave up still reads `LIVE: YES` |
+88
View File
@@ -0,0 +1,88 @@
# 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.
@@ -65,3 +65,13 @@ and not high.
(1) is latent. It becomes real the first time a compositor stops answering while
an agent is driving it: the agent's next tool call waits behind the stuck one
with no way to give up, where a CLI user would have pressed ctrl-C.
**The HTTP transport widens (1) without changing it.** The serialisation was
always there — `Runner` holds a process-wide lock because the CLI prints to a
shared stdout — but over stdio each client had a process of its own, so a call
only ever queued behind that same client's previous call. `mcp.http.enable`
puts every caller in one process, so a stuck call now delays *other people's*
agents too, and the one of them who can see something is wrong is not
necessarily the one who caused it. That makes idea 1 (a reachable
frame-socket timeout) worth more than it was, and idea 2 (a forked child per
call) less unreasonable than it was.
@@ -0,0 +1,75 @@
# 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.