diff --git a/README.dev.md b/README.dev.md index 7b3170f..7390a73 100644 --- a/README.dev.md +++ b/README.dev.md @@ -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 diff --git a/README.md b/README.md index f0b4442..8b511e9 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 | |---|---| diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0c05cb1..7de4ff7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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 diff --git a/docs/CONTRACT-mcp.md b/docs/CONTRACT-mcp.md index f647164..c04ff84 100644 --- a/docs/CONTRACT-mcp.md +++ b/docs/CONTRACT-mcp.md @@ -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 ` 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 \| --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. diff --git a/docs/TODO/README.md b/docs/TODO/README.md index 099bc10..f7bd589 100644 --- a/docs/TODO/README.md +++ b/docs/TODO/README.md @@ -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` | diff --git a/docs/TODO/mcp-http-auth-is-not-oauth.md b/docs/TODO/mcp-http-auth-is-not-oauth.md new file mode 100644 index 0000000..110947c --- /dev/null +++ b/docs/TODO/mcp-http-auth-is-not-oauth.md @@ -0,0 +1,88 @@ +# The HTTP transport's bearer token is not MCP authorization + +## The issue + +`hhstream-mcp serve --http` requires `Authorization: Bearer ` 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. diff --git a/docs/TODO/mcp-in-process-has-no-call-deadline.md b/docs/TODO/mcp-in-process-has-no-call-deadline.md index 244ab1a..7f17e12 100644 --- a/docs/TODO/mcp-in-process-has-no-call-deadline.md +++ b/docs/TODO/mcp-in-process-has-no-call-deadline.md @@ -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. diff --git a/docs/TODO/mcp-tokens-do-not-scope-resources.md b/docs/TODO/mcp-tokens-do-not-scope-resources.md new file mode 100644 index 0000000..7437161 --- /dev/null +++ b/docs/TODO/mcp-tokens-do-not-scope-resources.md @@ -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//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.