The best way to control Claude Code, Codex and more from any computer or phone
| 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. |