@devries-cameron20 / t3code Mirror · read-only
Fork 0

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, 03:37 UTC

main
md 187 lines 11.2 KB
Rendered Raw
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.