The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 07:15 UTC
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.