Repository navigation
Commit 543ee4b
feat(server): owner-approved external MCP clients over DPoP device grants (#1636)
## Problem
An external agent (another machine, another harness) had no safe way to coordinate T3 threads.
The only options were the provider-session `/mcp` token or a broad admin credential.
## Change
The owner approves a DPoP device grant with an MCP policy instead of scopes.
The client then uses `/api/mcp/external`, a second MCP server with its own `t3_external_*` tools.
| Aspect | Rule |
| --- | --- |
| Credential | DPoP device session, scopes `[]` |
| Policy | `auth_external_mcp_grants`, keyed by session |
| Reads | projects, threads, timelines, waits |
| Mutations | create, send/steer, interrupt with `--mcp-coordinate` |
| Boundary | granted projects only |
| Ceilings | default `approval-required` and `plan` |
| Retries | `auth_external_mcp_requests` binds key to request and result |
| Lost result | retry recovers the committed message and its run |
| Interrupt retry | pins its run, or no run, before dispatch |
| Steering | a capped grant joins only the provider attempt it vetted |
| Dispatch | refuses a capped send or create prompt once its attempt or the thread modes changed |
| Later owner changes | apply to turns that start afterwards, as for any queued message |
| Reused key, new payload | `invalid_request` |
| Failures | MCP `isError: true`, text led by the code |
| Provenance | `createdBy: agent`, `creationSource: mcp` |
| Revocation | `t3 auth session revoke` ends it at once |
| Isolation | own `Layer.fresh`; `/mcp` is unchanged |
```bash
t3 auth device approve <code> --mcp-project <id> --mcp-coordinate
```
The token endpoint also omits `scope` for a scopeless grant.
It used to fail with `500` after it had issued the session.
## Head
| Commit | Content |
| --- | --- |
| `77023d822ba173f4be58619469f2ae16179f0750` | head; one docs-only commit |
| `657bd5cf7f29aa63a04b13c6421baeac2618afba` | last code commit; the recordings and VM transcript ran here |
`git diff 657bd5c 77023d8`: `docs/fork/internals/fork-delta.md` only, +2 −1.
The recordings stand for the head; a reviewer confirms that equivalence.
```diff
-| Credential | DPoP device session only; scopes `[]`, so no RPC or route accepts it |
+| Credential | DPoP device session only; scopes `[]`, so scope-checked routes and RPCs refuse it |
+| WebSocket | `/api/auth/websocket-ticket` needs only authentication; each socket RPC refuses it |
```
## Recordings
Recorded on an isolated QA VM against `657bd5c`.
Left: the guest's standalone client.
Right: the host owner terminal and a separate observer browser.
**1. Pair and connect.** Provenance, device start, owner approve, poll, tool list, whoami.
https://github.com/user-attachments/assets/e875e8fd-9854-4ad1-b339-6ea7e5744f13
**2. Create a thread.** `t3_external_thread_create` with a prompt; the observer shows the thread, "Sent by another agent", and the reply.
https://github.com/user-attachments/assets/c10b2b05-a493-4ada-b7b2-c52420ed8611
**3. Send a message.** `t3_external_thread_send`; the observer shows the second reply; wait completes.
https://github.com/user-attachments/assets/fefce4d0-e894-4fb9-a6d8-35dd0cb5c7e3
**4. Refusals.** Ceiling escalation, a foreign project, then a read-only grant: read `200`, create `capability_denied`.
https://github.com/user-attachments/assets/c4759ebf-b594-4564-99ee-7770ea14d98a
**5. Credential probes.** Another key's proof, replayed proof, no credential, Bearer, no proof, forged: `401`; browser origin: `403`.
https://github.com/user-attachments/assets/01bd3ace-de56-4b68-b546-27d6b69a05d5
**6. Revoke.** A new grant creates a thread; the owner revokes it; send and whoami `401`; the reader grant still `200`.
https://github.com/user-attachments/assets/969f08c2-d9df-4dc3-8676-55cc9a3cb713
| Provenance | Value |
| --- | --- |
| Commit | `657bd5cf7f29aa63a04b13c6421baeac2618afba`, tree clean |
| Server | `node apps/server/src/bin.ts serve --host 192.168.122.1 --port 38917 --base-dir <worktree>/.t3` |
| Web | `vp build` of the same tree |
| State | the worktree's own `.t3`; libvirt bridge only |
| Guest | `qa-desktop`, 1360x768; Python client, own P-256 key |
| Guest credentials | none from T3, the host, or a provider |
| Observer | host Chrome, paired by a one-time token |
| Harness `extmcp.py` sha256 | `bf43970fc04cebd0b70e665898a606ff74fb4c180cb7640740e917df2d06eef5` |
| Recorder | `donjor hypr record`, takes `rec-e058` (clips 1-5), `rec-27c5` (clip 6) |
| Harness | Claude Code 2.1.289, Claude Opus 5.5 |
Clip 1 shows the commit, the dirty count, and the harness hash on screen.
<details>
<summary>Clip hashes and cuts</summary>
Each upload was downloaded again; every sha256 matched.
| Clip | Length | sha256 |
| --- | --- | --- |
| 1 pair | 46.0s | `806a7b69d060f522ed5c02fa6d44c6377f2c2b01769589d78ca4f88224046078` |
| 2 create | 16.0s | `bf4b2f50a179297b376b55994c431bf73df65065e1cd8dcde3cf820e8b777bf0` |
| 3 send | 13.0s | `fb277d317e6a2b0947e6788ba18cdab73e4a362900ab1d285c6389ba4545c53b` |
| 4 refusals | 31.0s | `5f81329a7e822985712a1b3771d0cc29b7a8b8af8a23d916c9a90d920839f768` |
| 5 probes | 10.0s | `87c32f67053e439052b65bbbc7dc6714c4eb3c509488c2bb54581b823e52f52e` |
| 6 revoke | 40.0s | `6a0459303d15ea8715dd1f32b3d33213aa192f5ba54ab13aa4d8e0008ba5fc9d` |
| Clip | Span | Real | Clip |
| --- | --- | --- | --- |
| 1 | provenance hold | 13s | cut |
| 1 | idle after approve | 9s | cut |
| 1 | tools hold, overflowing whoami | 18s | cut |
| 2 | observer navigation | 9s | 3x |
| 2 | idle, reply already shown | 15s | cut |
| 3 | idle until wait | 13s | cut |
| 4 | first refusal attempt, truncated output | 28s | outside the trim |
| 4 | four idle gaps | 3s, 9s, 8s, 9s | cut |
| 6 | three idle gaps | 5s, 6s, 13s | cut |
| 6 | observer route detour | 24s | cut |
| 6 | tail after reader `200` | 8s | cut |
No secret is on screen.
The client never prints its access token or device code.
The pairing token never left the host files.
User codes appear by design: single use, consumed, now expired.
</details>
## Blast radius
| Surface | Change | Existing behavior |
| --- | --- | --- |
| Device grant | `--mcp-*` approve stores a policy, scopes `[]` | scope approvals unchanged; tests |
| Token endpoint | omits `scope` when empty | scoped grants still carry it |
| Routes | adds `/api/mcp/external` | other routes untouched |
| Provider `/mcp` | none | own bearer registry; probe below |
| Orchestrator | `message.dispatch` checks two optional fields | absent fields: no-op |
| `sendToThread` | optional `steerTarget`, `expectedModes` | absent: same dispatch mode |
| Contracts | two optional command fields | existing commands decode unchanged |
| Schema | two fork tables, two columns | idempotent; upgrade test |
| Clients | none | desktop, web, mobile unchanged |
Upstream code files take 42 added lines and lose none; every hook carries a `fork-hook` tag.
One upstream doc, `orchestrator-mcp-server.md`, is corrected to the shipped provider credential lifetime.
Probe from the guest with the read-only external credential:
```diff
+ /api/mcp/external → 200
- provider /mcp, DPoP or Bearer → 401 invalid_mcp_credential
- /api/auth/clients, pairing-links → 403 insufficient_scope
- /api/auth/pairing-token → 403 insufficient_scope
! /api/auth/websocket-ticket → 200
```
The ticket route only requires authentication upstream; this PR leaves it unchanged.
Every RPC on that socket requires a scope ([`RpcAuthorization.ts`](https://github.com/RSI-Software/t3code-hyprws/blob/77023d822ba173f4be58619469f2ae16179f0750/apps/server/src/auth/RpcAuthorization.ts)).
Live probe through that ticket, same branch server, a fresh read-only external grant:
```diff
+ POST /api/auth/websocket-ticket → 200, ticket issued
+ GET /ws?wsTicket=…&orchestrationProtocol=2 → socket open
- server.getConfig → EnvironmentAuthorizationError orchestration:read
- orchestration.subscribeShell → EnvironmentAuthorizationError orchestration:read
- subscribeAuthAccess → EnvironmentAuthorizationError access:read
- orchestration.dispatchCommand → EnvironmentAuthorizationError orchestration:operate
- terminal.open → EnvironmentAuthorizationError terminal:operate
- after revoke: websocket-ticket → 401
```
No call returned a value or a stream chunk.
Payloads were valid but aimed at ids that do not exist, so even an accepted call could touch nothing.
Opening the socket records only the session's own connection, as for any client.
<details>
<summary>Probe method</summary>
| Item | Value |
| --- | --- |
| Server | `657bd5c` source, own `.t3`, `192.168.122.1:38917` |
| Client | host Node script, own P-256 key; DPoP with `ath` |
| Grant | `--mcp-project` one project, no `--mcp-coordinate` |
| Output | reply tag, exit tag, scope, error tag; never the token or ticket |
Effect RPC decodes a payload before the scope check, so an invalid payload fails decoding first.
The probe sends valid payloads so the scope check is what answers.
</details>
## Verification
```text
npx tsc --noEmit -p apps/server → exit 0
vp test run <ForkSchema, mcp/external, ThreadManagementService, SelectionRestart> → exit 0 (43 tests)
vp lint <changed .ts> → exit 0
vp run fork:ci → exit 0
vp run build (apps/server) → exit 0
```
Transcript proof, round 4, on an isolated VM.
The branch server ran with its own `.t3` and listened on the libvirt bridge only.
The guest client was standalone Python with its own P-256 key, and had no T3, host, or provider credentials.
```diff
+ A, B, C: three grants, three keys, one guest
+ whoami: each client's own session and policy
+ one mcp-session-id, two credentials: each call answers as its sender
+ create K, retry K as sent → same thread
+ create with prompt → real Codex turn; retry → same run
+ steer → joins the vetted provider attempt
+ interrupt → interrupted
+ steer retry after the run ended → recorded result
+ owner clears every recorded result while run 3 is live:
+ interrupt retry → run 2, interrupted; run 3 untouched
+ steer and send retries → run 2, original delivery
+ create retry → run 1
- create K or send s1 retried with a changed payload → invalid_request
- full-access create → runtime_mode_escalation_denied
- reader create → capability_denied
- no proof, Bearer, forged, another key's proof → 401 DPoP
- replayed proof → 401 DPoP; browser origin → 403
- C after its 1m lifetime → 401
- A revoked → 401; B unaffected
```
Real-orchestrator regression: `ExternalMcpService.orchestrator.fork.test.ts` (owner elevates a thread under a used key; lost result for create, send, interrupt, idle interrupt; owner mode change during a running or starting turn; a send joins only its vetted attempt, also across an owner restart; dispatch refuses a send vetted under older modes; an owner raise that wins the lock mid-create keeps the prompt from starting).
Auth: `ExternalMcpServer.auth.fork.test.ts` (real session store and DPoP verifier).
Schema: `ForkSchema.fork.test.ts` adds the interrupt pin to an existing request table.
The VM run caught that upgrade gap on a round-1 database.
| Evidence | Value |
| --- | --- |
| Head | `77023d822ba173f4be58619469f2ae16179f0750` |
| VM run | `657bd5cf7f2`, the last code commit, from source |
| Not on the VM | an owner mode change racing a capped send or create; regressions own it |
| Harness `extmcp.py` sha256 | `bf43970f…6eef5` |
| Transcript sha256 | `4af1dec3…7ccf03` |
Transcript: [external-mcp-vm-proof-r4.txt](https://github.com/user-attachments/files/33043476/external-mcp-vm-proof-r4.txt), harness: [extmcp.py](https://github.com/user-attachments/files/33041290/extmcp.py)
### Internal compatibility
The external rejection above is a negative test; this section is the positive one.
| Check | Result |
| --- | --- |
| Native Electron | `vp run dev:desktop:agent --home-dir <worktree>/.t3`, head `77023d8`, virtual monitor; backend ready, window connected, threads listed |
| Provider MCP call | Codex thread asked to call `t3_project_list`: item `dynamic_tool` `t3-code.t3_project_list` completed, reply `6` = 6 projects |
| Provider `/mcp` traffic | initialize `200`, tools/list `200`, tool call `200` |
| Existing tests, CI on head | `McpHttpServer`, `McpProviderSession`, `McpSessionRegistry`, `OrchestratorMcpToolkit.integration` in Test Server 1-3 |

Screenshot sha256 `e0c474c6625dc16855e3174840f85d210d032d90bcc08b23479ad8f317ca0712`.
Not checked: mobile UI (no client change), relay and tunnel modes.
### Checks
Artifact Kit is not configured here: no `./ak`, no `.agents/skills/ak`; none was added.
The repository has no aftercare review workflow; its fork checks are below.
```text
vp run fork:ci → exit 0 (head 77023d8)
ghb pr checks 1636 → exit 0 (head 77023d8, 9/9: Check, Test, Test Web, Test Scripts, Test Server 1-3, Body, merge-tree)
```
## Upstream baseline
Fork-only. Nothing is posted upstream; this is a rebase and retirement baseline.
| Item | State, 2026-10-05 |
| --- | --- |
| Fork base | `v0.0.46-nightly.20261004.2652` |
| Latest stable | `v0.0.45` |
| `pingdotgg#15219` explicit MCP targets | merged 2026-10-05, untagged |
| `pingdotgg#15220` MCP OAuth for outside agents | open, not draft |
| Concern | Baseline |
| --- | --- |
| Scope | external MCP only; no client change |
| Reuse | device grant, `SessionStore`, DPoP verifier, five `OrchestratorMcpService` helpers |
| Fork-owned | 17 `.fork` files; schema in `ForkSchema.ts` |
| Rebase | the five helpers survive `pingdotgg#15219`; this PR's files auto-merge onto `upstream/main` `cf3e714b0f5` |
| Retire | when a tag ships `pingdotgg#15220`, feed its authenticator from device grants; keep only project and mode policy |
The auto-merge is textual; no typecheck ran on that tree.
<details>
<summary>Follow-ups, out of scope</summary>
| Follow-up | Note |
| --- | --- |
| Stale grant and request rows | remain after the session ends |
</details>
Claude Opus 5.5 in Claude Code, inside T3 Code.
## Fork trailers
Squashes:
- 3f58ba7 feat(server): owner-approved external MCP clients over DPoP device grants (#1636) (#1636)
- 2844353 fixup! feat(server): owner-approved external MCP clients over DPoP device grants (#1636) (#1636)
Fork-Domain: device-auth
Fork-Tier: core
Co-authored-by: donjor <[email protected]>1 parent 0c1d1aa commit 543ee4b
25 files changed
Lines changed: 3675 additions & 26 deletions
File tree
- apps/server/src
- auth
- cli
- mcp
- external
- toolkits/external
- orchestration-v2
- persistence
- docs
- fork/internals
- orchestration-v2
- packages/contracts/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
417 | 417 | | |
418 | 418 | | |
419 | 419 | | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
| 454 | + | |
| 455 | + | |
| 456 | + | |
| 457 | + | |
| 458 | + | |
| 459 | + | |
420 | 460 | | |
421 | 461 | | |
422 | 462 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
| 25 | + | |
25 | 26 | | |
26 | 27 | | |
27 | 28 | | |
| |||
91 | 92 | | |
92 | 93 | | |
93 | 94 | | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
94 | 105 | | |
95 | 106 | | |
96 | 107 | | |
| |||
114 | 125 | | |
115 | 126 | | |
116 | 127 | | |
| 128 | + | |
117 | 129 | | |
118 | 130 | | |
119 | 131 | | |
| |||
141 | 153 | | |
142 | 154 | | |
143 | 155 | | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
144 | 159 | | |
145 | 160 | | |
146 | 161 | | |
147 | 162 | | |
148 | 163 | | |
| 164 | + | |
149 | 165 | | |
150 | 166 | | |
151 | | - | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
152 | 170 | | |
153 | 171 | | |
154 | 172 | | |
| |||
175 | 193 | | |
176 | 194 | | |
177 | 195 | | |
| 196 | + | |
178 | 197 | | |
179 | 198 | | |
180 | 199 | | |
| |||
204 | 223 | | |
205 | 224 | | |
206 | 225 | | |
207 | | - | |
| 226 | + | |
| 227 | + | |
208 | 228 | | |
209 | 229 | | |
210 | 230 | | |
| |||
307 | 327 | | |
308 | 328 | | |
309 | 329 | | |
310 | | - | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
311 | 338 | | |
312 | 339 | | |
313 | 340 | | |
314 | | - | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
315 | 345 | | |
316 | 346 | | |
317 | 347 | | |
318 | 348 | | |
319 | 349 | | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
320 | 353 | | |
321 | 354 | | |
322 | 355 | | |
| |||
328 | 361 | | |
329 | 362 | | |
330 | 363 | | |
| 364 | + | |
331 | 365 | | |
332 | 366 | | |
333 | 367 | | |
| |||
409 | 443 | | |
410 | 444 | | |
411 | 445 | | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
| 451 | + | |
| 452 | + | |
| 453 | + | |
412 | 454 | | |
413 | 455 | | |
414 | 456 | | |
| |||
565 | 607 | | |
566 | 608 | | |
567 | 609 | | |
568 | | - | |
| 610 | + | |
| 611 | + | |
569 | 612 | | |
570 | 613 | | |
571 | 614 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
0 commit comments