The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Environment authentication |
| 2 | |
| 3 | The environment issues its own sessions and enforces their capabilities. Cloud |
| 4 | identity and relay credentials belong to a separate trust boundary, described in |
| 5 | [T3 Connect](./t3-connect.md). A relay token is never an environment login. |
| 6 | |
| 7 | ## Authority survives transport changes |
| 8 | |
| 9 | Pairing delegates a set of scopes. Exchanging a bootstrap credential can narrow |
| 10 | that grant but cannot widen it. The default grant includes access and relay |
| 11 | management: `terminal:operate` is a shell as the server's user and |
| 12 | `orchestration:operate` can start a full-access agent, and either can mint a |
| 13 | session with every scope through `t3 auth session issue`, so withholding |
| 14 | management from the default would not be a boundary. A narrower client gets |
| 15 | explicit scopes. Creating another pairing link requires both `access:write` and |
| 16 | every scope being delegated. The |
| 17 | [auth handlers](../../apps/server/src/auth/http.ts) enforce this at issuance; |
| 18 | client labels and device metadata have no authorization role. |
| 19 | |
| 20 | The access read model contains pairing metadata, never recoverable pairing |
| 21 | secrets. Only the creation response returns the raw credential. Otherwise read |
| 22 | access to the connections list would become a way to acquire another client's |
| 23 | authority. |
| 24 | |
| 25 | Browser cookies, bearer tokens, and DPoP tokens adapt the same scoped session |
| 26 | model. DPoP binds a token to a client's proof key; an invalid proof must fail |
| 27 | rather than fall back to bearer authentication. The OAuth token-exchange |
| 28 | vocabulary gives these grants a familiar meaning. |
| 29 | |
| 30 | A device that exchanges a plain pairing link with a DPoP proof gets a one-hour |
| 31 | token on a session that renews: presenting the token, even expired, with a |
| 32 | proof from the same key moves the session's expiry 30 days out and returns a |
| 33 | fresh token for the same session. The session itself must still be unexpired |
| 34 | and unrevoked, so a device idle past the window pairs again. Renewal stays in place rather than issuing a |
| 35 | successor, so live sockets keep their session, Sharing & access shows one row |
| 36 | per device for its whole renewal window, and one revoke ends it. T3 Connect, |
| 37 | CLI and desktop sessions never renew, so unlinking Connect or rotating |
| 38 | their credential still cuts a device off. |
| 39 | |
| 40 | A [peer link](remote.md#peer-links)'s session renews on use instead: its |
| 41 | bearer token is never reissued, so the session row alone holds its deadline and |
| 42 | the token's own expiry is ignored. Authenticating a call from it moves the |
| 43 | row 30 days out, at most once a day so a busy link does not write on every |
| 44 | call. Only an unexpired, unrevoked row moves, so an idle link still ends after |
| 45 | 30 days and a revoke is final. Other MCP clients keep the fixed 30 days their |
| 46 | token carries. |
| 47 | |
| 48 | ### Guest links are not sessions |
| 49 | |
| 50 | A [guest link](../user/guest-links.md) gives one browser read access to one |
| 51 | thread and a way to propose messages. Its tokens are HMACs of the thread and |
| 52 | share id under a server key ([GuestShareService](../../apps/server/src/guest/GuestShareService.ts)), |
| 53 | so nothing secret is stored. The share in the thread projection is the only |
| 54 | state: replacing, closing, or archiving it revokes every token, and the |
| 55 | orchestrator's serial commands make redeeming and sending happen once. Guest |
| 56 | tokens never enter `SessionStore`, so no RPC, WebSocket, or MCP path can accept |
| 57 | one. Guest routes also require T3 Connect to still serve the link's hostname; |
| 58 | the request's Host header is not checked, because a LAN client can forge it. |
| 59 | |
| 60 | ### MCP clients are a separate audience |
| 61 | |
| 62 | Agents T3 Code did not launch sign in to `/mcp` through a narrow OAuth |
| 63 | authorization-code server ([McpOAuth](../../apps/server/src/auth/McpOAuth.ts)). |
| 64 | It accepts loopback redirect URIs for agents on the user's machine and any |
| 65 | HTTPS redirect for hosted agents (ChatGPT, bots). An HTTPS redirect means a |
| 66 | link someone else sends the owner can deliver access to that someone, so the |
| 67 | approval page names the host access goes to and approving stays the owner's |
| 68 | call. Every client is public and proves itself with PKCE; a client that asks |
| 69 | for a secret is registered without one. Client registration is stateless, so an unauthenticated caller cannot grow server |
| 70 | state. Approval spends a one-time pairing code, or uses a browser session with |
| 71 | `access:write`; proof-bound T3 Connect codes are refused without being spent. |
| 72 | |
| 73 | The user grants either read-only access or a runtime-mode ceiling, not a |
| 74 | scope list: MCP tools are all orchestration, and `orchestration:operate` |
| 75 | alone would let an agent start a thread in full access and act through it. |
| 76 | The result is an ordinary session with subject `mcp-client`. A read-only |
| 77 | grant holds `orchestration:read` alone. On `/mcp` it passes only tools |
| 78 | declared as reads in [McpToolAccess](../../apps/server/src/mcp/McpToolAccess.ts), |
| 79 | where every tool must declare who may call it to compile. Any other grant adds |
| 80 | `orchestration:operate` and a signed ceiling. Only `/mcp` accepts these sessions, and for a |
| 81 | [peer link](remote.md#peer-links)'s session alone the thread routes in |
| 82 | [linkThreadHttp](../../apps/server/src/peer/linkThreadHttp.ts), which only read, and the |
| 83 | client pairing described below. Every other HTTP and WebSocket |
| 84 | path rejects that subject, because the RPC surface would let the agent act |
| 85 | above its ceiling. Inside MCP the credential sets the limits and tool |
| 86 | parameters only pick targets; see |
| 87 | [threadAccess](../../apps/server/src/mcp/threadAccess.ts). |
| 88 | |
| 89 | These clients have no calling thread, so `/mcp` does not offer them tools that |
| 90 | act as one, such as `request_secret` or `delegate_task`. Hiding is only |
| 91 | discovery: the handlers still refuse such a call with |
| 92 | `thread_credential_required`. A secret card belongs to a thread's run, so an |
| 93 | outside agent that needs a secret starts a thread and lets that agent ask. |
| 94 | |
| 95 | A full-access [peer link](../../apps/server/src/peer/PeerClientPairing.ts) may |
| 96 | mint a one-time pairing for a client of the environment that holds it. Its |
| 97 | agents already run as this machine's user and could run `t3 auth pairing create`, |
| 98 | so this adds no authority; a narrower link would gain some, so it is refused |
| 99 | here, on the linked side, whatever the linking side sent. The pairing carries |
| 100 | the client's scopes on the linking environment intersected with a normal |
| 101 | pairing's. A person starts it: the linking environment exposes it as a WebSocket |
| 102 | RPC behind `access:write`, and the linked side as an HTTP route that accepts only |
| 103 | a link's session. It is not an MCP tool, because a tool is reachable by whatever |
| 104 | holds a thread credential, and hiding one from tool listings is only discovery. |
| 105 | |
| 106 | Issuer and resource URLs come from the request's Host and |
| 107 | `X-Forwarded-Proto`, so one server answers over loopback, Tailscale Serve and a |
| 108 | T3 Connect tunnel. A proxy that rewrites Host or drops the protocol header |
| 109 | breaks sign-in. |
| 110 | |
| 111 | Bearer and DPoP clients obtain short-lived WebSocket tickets through authenticated |
| 112 | HTTP so long-lived tokens stay out of socket URLs. A ticket names the route it |
| 113 | opens: the RPC socket, or the media routes (device hub, preview stream), which |
| 114 | share one ticket across `<img>`, `EventSource` and several sockets. A DPoP |
| 115 | client's RPC ticket is bound to its proof key and the upgrade carries a fresh |
| 116 | proof in the `dpop` query parameter, since a WebSocket cannot set headers; a |
| 117 | ticket captured on a plain HTTP LAN route is useless without the key, and the |
| 118 | proof's `jti` is consumed like any other. Media tickets stay bearer because each |
| 119 | media request would need its own proof. Clients that predate this mint unbound |
| 120 | tickets that open either route. Browser sessions can authenticate the upgrade |
| 121 | with their cookie. A successful handshake grants no |
| 122 | extra authority: [every RPC declares a required |
| 123 | scope](../../apps/server/src/auth/RpcAuthorization.ts), and the WebSocket RPC |
| 124 | group's `RpcScopeAuthorization` middleware checks it before any handler runs. |
| 125 | |
| 126 | Scope changes must not prevent older clients from connecting. Token exchange |
| 127 | intersects recognized requests with the pairing grant; retired and unknown names |
| 128 | are dropped. A request with no granted scopes fails before consuming the link. |
| 129 | Stored credentials are never expanded when scopes split. |
| 130 | |
| 131 | Auth responses keep `scopes` within the original wire vocabulary and include |
| 132 | `permissions` for the exact grant. New clients use `permissions` when present, |
| 133 | even if empty. Older servers omit it, so clients use legacy parent checks for |
| 134 | features those servers already support. These client checks never change server |
| 135 | authorization. Permission errors likewise retain a legacy `requiredScope` and |
| 136 | add the exact `requiredPermission`, so a denied RPC stays decodable by old clients. |
| 137 | Unknown response permissions are ignored; grant inputs stay strict. |
| 138 | |
| 139 | Desktop restarts forget the previous local bearer token, so its reusable |
| 140 | bootstrap grant replaces earlier sessions for the same subject and method. |
| 141 | Revocation and insertion share a [database |
| 142 | transaction](../../apps/server/src/persistence/AuthSessions.ts); a failed |
| 143 | replacement must leave the old credential usable. Pairing and browser sessions |
| 144 | do not follow this replacement rule. |
| 145 | |
| 146 | ### Reusable dev credential |
| 147 | |
| 148 | Web development environments can accept one `T3CODE_DEV_AUTH_TOKEN` across |
| 149 | worktrees and ports on one hostname. The token and startup URLs that contain it |
| 150 | grant administrative access. Desktop and non-development servers ignore it. See |
| 151 | the [development runbook](../operations/development.md#reusable-dev-credential) |
| 152 | for setup. |
| 153 | |
| 154 | Each environment hashes the value and seeds its own database record at startup. |
| 155 | Environments do not share SQLite data, signing keys, environment IDs, session |
| 156 | records, pairing grants, or revocation state. Local revocation persists after |
| 157 | restart and does not affect another worktree. Removing or rotating the value |
| 158 | and restarting invalidates the old credential and its WebSocket tickets. |
| 159 | |
| 160 | Normal credentials keep precedence. A rejected normal credential never falls |
| 161 | back to the reusable credential. OAuth exchanges create ordinary local bearer |
| 162 | or DPoP children with normal expiry and revocation. The reusable cookie expires |
| 163 | after 30 days. |
| 164 | |
| 165 | ## The environment is the filesystem boundary |
| 166 | |
| 167 | Projects are organizational boundaries, not filesystem sandboxes. |
| 168 | `filesystem:read` permits reading files the server account can read, including |
| 169 | absolute paths outside a project. This lets clients display artifacts that an |
| 170 | agent writes in a temporary directory. Relative paths and writes still follow |
| 171 | the [workspace path rules](../../apps/server/src/workspace/WorkspaceFileSystem.ts). |
| 172 | |
| 173 | Signed asset URLs are bearer credentials. A URL for media on the host grants |
| 174 | access to one canonical file and its device/inode identity, not its containing directory. |
| 175 | [Asset access](../../apps/server/src/assets/AssetAccess.ts) rechecks the opened |
| 176 | file's identity when serving it, so atomic replacement requires a new URL while |
| 177 | editing the same file in place does not. An HTML file authorized this way cannot |
| 178 | load sibling assets; directory-scoped workspace previews are a separate grant. |
| 179 | Clients should share the authored file reference so they do not disclose the |
| 180 | temporary URL's credential. `filesystem:read` is checked when the URL is minted, |
| 181 | not when it is served: a URL issued before the grant was revoked keeps working |
| 182 | until it expires, and it is not bound to the session that minted it. |
| 183 | |
| 184 | Host videos can change in place. Their [HTTP |
| 185 | responses](../../apps/server/src/http.ts) omit cache validators because file |
| 186 | metadata cannot prove byte-for-byte identity for `If-Range`. Adding weak |
| 187 | validators would turn native-player seeks into full downloads. |