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:
1 parent
7eb9afdfa3
commit
10176356b6
8 files changed
+504
-31
No files matched your search
+28
-3
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
@@ -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` |
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user