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

main
md 118 lines 10.6 KB
Rendered Raw
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.