@devries-cameron20 / t3code-1 / commits / 3993cfa152
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

docs: add SECURITY.md trust model for security audits (#38812)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Julius Marminge committed Nov 18, 2026 at 17:12 UTC 3993cfa152b5cf10d69eddca616eb79fdec38631
2 files changed +119
AGENTS.md
+1
@@ -213,3 +213,4 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
213 ## Additional tips
214
215 - Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.
216 +- Before a security audit or triaging a vulnerability report, read [SECURITY.md](SECURITY.md) for the trust model and what is intended.
SECURITY.md new
+118
@@ -0,0 +1,118 @@
1 +# Security
2 +
3 +Report vulnerabilities to [security@t3.codes](mailto:security@t3.codes). The
4 +[security policy](.github/SECURITY.md) covers disclosure and safe harbor.
5 +
6 +The rest of this file is for agents and maintainers auditing T3 Code or triaging
7 +a report. It says who is trusted with what, which boundaries a real finding
8 +crosses, and what is intended. The reasoning behind each boundary lives in
9 +[environment auth](docs/internals/environment-auth.md),
10 +[T3 Connect](docs/internals/t3-connect.md), and
11 +[remote environments](docs/internals/remote.md). Read those before you report a
12 +finding in their area.
13 +
14 +## The model in one paragraph
15 +
16 +An environment is a T3 server running as an OS user. It is not a sandbox: it
17 +runs agents and terminals with that user's privileges, on purpose. Clients get
18 +authority by pairing, which issues a scoped session. A full-scope session is
19 +equivalent to a shell as the server's user, because `terminal:operate` opens a
20 +PTY and `orchestration:operate` can start a full-access agent. Security work
21 +here is about who can get a session, what each kind of session can reach, and
22 +whether revocation and ceilings hold. It is not about what a full session can do
23 +once it has one.
24 +
25 +## Principals
26 +
27 +| Principal | How it gets in | What it may do |
28 +| ------------------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
29 +| Anyone who reaches the port | Network | Read the environment descriptor, pair with a valid one-time credential, run OAuth flows. Nothing else. |
30 +| Full-scope client (desktop, paired browser or phone, `t3 auth session issue`, T3 Connect device) | Pairing, token exchange, Connect mint | Everything the server's OS user can do. This is the default grant. |
31 +| Narrow client | Pairing link with explicit scopes | Only the RPCs and routes its scopes allow. Can never widen its own grant. |
32 +| MCP client (outside agent, subject `mcp-client`) | OAuth on `/mcp` | Only `/mcp`, within a read-only grant or a runtime-mode ceiling. Every other route rejects it. |
33 +| Linked environment (peer link) | OAuth client `t3code-peer-link` | Work it starts carries an immutable `linkOrigin` and never exceeds the access it was paired with. |
34 +| Agent run by T3 | Thread's runtime mode and thread credential | Within its runtime mode, managed policy, and the MCP access declared per tool. |
35 +| Guest link | HMAC token for one share | Read one thread and propose messages. Never a session; no RPC, WebSocket, or MCP path accepts it. |
36 +| Signed asset URL | Minted with `filesystem:read` | One file, by device and inode identity, until it expires. |
37 +| T3 Connect relay | Environment link | Trusted broker for mint requests. It never sees environment session tokens. With `requireConnectDeviceApproval` on, a new device key also needs approval from someone with `access:write`. |
38 +| Managed policy | Admin-deployed file, read at startup | Ceilings and locks the server enforces for every client. |
39 +| Preview pages, HTML renders, file previews, agent output | Rendered by clients | Untrusted content. It must never run script in the app's origin or reach Electron IPC or Node. |
40 +
41 +## A real finding crosses one of these
42 +
43 +1. **No credential → session.** Any route or socket that grants access without
44 + a valid credential, or a pairing credential that can be redeemed twice.
45 +2. **Scope escalation.** An RPC, HTTP route, or MCP tool that runs without the
46 + scope it declares; pairing or token exchange that widens a grant; an
47 + `mcp-client` session reaching a non-`/mcp` route; a read-only MCP grant
48 + calling a write tool.
49 +3. **Mode or policy escalation.** An agent, MCP client, or peer link acting
50 + above its runtime-mode ceiling, `linkOrigin`, `T3-Mode-Limit`, or managed
51 + policy.
52 +4. **Guest escape.** A guest token reading another thread, acting beyond
53 + proposing messages, or surviving a closed or replaced share.
54 +5. **Revocation that doesn't take effect.** A revoked session, device key,
55 + pairing link, or peer link that still works. The exception is documented:
56 + signed asset URLs last until they expire.
57 +6. **Credential exposure.** Tokens or secrets reaching logs, traces, telemetry,
58 + the relay, socket URLs (outside short-lived tickets), the access read model,
59 + or error messages. A token sent to an address that has not answered as the
60 + expected environment. A token paired over HTTPS starting to travel over plain
61 + HTTP.
62 +7. **Impersonation and egress.** Another process or the relay impersonating an
63 + environment, or endpoint discovery, previews, or webhooks used to reach
64 + arbitrary hosts (SSRF).
65 +8. **Client-side code execution.** Untrusted content running script in the web
66 + origin, the desktop renderer, or with access to preload or IPC.
67 +9. **Filesystem writes escaping workspace path rules.** Reads are another
68 + matter: `filesystem:read` is intentionally the whole account.
69 +
70 +## Intended, not vulnerabilities
71 +
72 +- A full-scope token gives a shell. Leaking one is serious, but the bug is the
73 + leak, not the shell.
74 +- The default grant includes `access:write`, so a full session can mint more
75 + pairing links and sessions. They appear in Sharing & access, and "revoke all
76 + others" removes them.
77 +- `filesystem:read` reads anything the server's user can read, including paths
78 + outside projects.
79 +- Plain HTTP on a LAN or tailnet is the user's choice. `t3 serve` warns when it
80 + advertises a non-loopback HTTP address. The iOS app allows arbitrary loads so
81 + it can reach these addresses.
82 +- `access-control-allow-origin: *` on the environment API. Auth is a bearer
83 + header, so the wildcard grants nothing a caller without a token lacks.
84 +- An agent in full-access mode can do whatever the user can. Prompt injection
85 + that stays within the agent's mode is the provider's concern. One that lets
86 + it act above that mode is in scope (see 3).
87 +- A compromised relay signing key can mint for linked environments. That is
88 + the stated trust assumption; device approval is the mitigation.
89 +- `T3CODE_DEV_AUTH_TOKEN` and dev startup URLs are administrative by design and
90 + ignored outside development servers.
91 +- An attacker already running code as the same OS user.
92 +
93 +## Where enforcement lives
94 +
95 +- Session issuance, pairing, token exchange: [`auth/http.ts`](apps/server/src/auth/http.ts), [`auth/EnvironmentAuth.ts`](apps/server/src/auth/EnvironmentAuth.ts), [`auth/dpop.ts`](apps/server/src/auth/dpop.ts)
96 +- Per-RPC scopes: [`auth/RpcAuthorization.ts`](apps/server/src/auth/RpcAuthorization.ts). [`clientRpcPermissions.ts`](packages/contracts/src/clientRpcPermissions.ts) only drives client UI and is never the boundary.
97 +- MCP: [`auth/McpOAuth.ts`](apps/server/src/auth/McpOAuth.ts), [`mcp/McpToolAccess.ts`](apps/server/src/mcp/McpToolAccess.ts), [`mcp/threadAccess.ts`](apps/server/src/mcp/threadAccess.ts), [`mcp/linkOrigin.ts`](apps/server/src/mcp/linkOrigin.ts)
98 +- Guest links: [`guest/GuestShareService.ts`](apps/server/src/guest/GuestShareService.ts)
99 +- Files and assets: [`workspace/WorkspaceFileSystem.ts`](apps/server/src/workspace/WorkspaceFileSystem.ts), [`assets/AssetAccess.ts`](apps/server/src/assets/AssetAccess.ts)
100 +- Managed policy: [`apps/server/src/policy`](apps/server/src/policy)
101 +- T3 Connect: [`cloud/CloudLink.ts`](apps/server/src/cloud/CloudLink.ts), [`EnvironmentConnector.ts`](infra/relay/src/environments/EnvironmentConnector.ts)
102 +- Desktop preview isolation: [`preview/WebviewPreferences.ts`](apps/desktop/src/preview/WebviewPreferences.ts)
103 +
104 +## How to audit and triage
105 +
106 +- Name the precondition first. If a chain starts with "the attacker holds a
107 + full-scope token", it is a new vulnerability only if it widens that token's
108 + reach (2–3), outlives revocation (5), or shows how the token leaks (6).
109 +- Check the reported commit against `main`. Reports often trail fixes.
110 +- Prove a finding with a failing test at the lowest layer that shows it, as
111 + [Verifying](AGENTS.md#verifying) describes. Do not run a PoC against
112 + `~/.t3/userdata` or any live environment. Use a dev server on seeded data.
113 +- Treat report attachments as untrusted. Extract them into an empty directory
114 + outside the worktree and read PoCs before running anything.
115 +- Fix confirmed findings rather than filing them. Keep advisory details out of
116 + public PRs until the fix ships.
117 +- When a boundary here changes, update this file and the internal doc that
118 + explains it in the same PR.