The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * One-use pairing codes minted on an environment with the user's own session there: a code |
| 3 | * for linking, so a link card can be answered without fetching a code by hand, and a code |
| 4 | * that approves one app's sign-in at a set level. Each carries exactly what an agent |
| 5 | * sign-in with the chosen access needs. |
| 6 | */ |
| 7 | import { |
| 8 | type AuthCreatePairingCredentialInput, |
| 9 | type AuthMcpClientAccess, |
| 10 | type AuthPairingCredentialResult, |
| 11 | } from "@t3tools/contracts"; |
| 12 | import * as Schema from "effect/Schema"; |
| 13 | import * as Effect from "effect/Effect"; |
| 14 | import type * as HttpClient from "effect/http/HttpClient"; |
| 15 | import * as Option from "effect/Option"; |
| 16 | import type { Atom } from "effect/reactivity"; |
| 17 | import * as SubscriptionRef from "effect/SubscriptionRef"; |
| 18 | |
| 19 | import * as RemoteEnvironmentAuthorization from "../authorization/service.ts"; |
| 20 | import type { PreparedConnection } from "../connection/model.ts"; |
| 21 | import type { EnvironmentRegistry } from "../connection/registry.ts"; |
| 22 | import * as EnvironmentSupervisor from "../connection/supervisor.ts"; |
| 23 | import * as ManagedRelay from "../relay/managedRelay.ts"; |
| 24 | import { executeAuthenticatedEnvironmentHttpRequest } from "./environmentHttpAuth.ts"; |
| 25 | import { createEnvironmentCommand } from "./runtime.ts"; |
| 26 | |
| 27 | const MINT_TIMEOUT_MS = 8_000; |
| 28 | const PEER_PAIRING_CODE_LABEL = "T3 Code link"; |
| 29 | const MCP_APPROVAL_CODE_LABEL = "App sign-in"; |
| 30 | |
| 31 | /** Minting failed; the user can still paste a code from the other environment. */ |
| 32 | export class PeerPairingCodeError extends Schema.TaggedError<PeerPairingCodeError>()( |
| 33 | "PeerPairingCodeError", |
| 34 | { |
| 35 | reason: Schema.Literals(["not_allowed", "unavailable"]), |
| 36 | cause: Schema.Defect(), |
| 37 | }, |
| 38 | ) { |
| 39 | override get message(): string { |
| 40 | return this.reason === "not_allowed" |
| 41 | ? "Your session there cannot create pairing codes. Paste a code from there instead." |
| 42 | : "Could not get a pairing code from there. Paste a code from there instead."; |
| 43 | } |
| 44 | } |
| 45 | |
| 46 | const mintPairingCredential = Effect.fn("clientRuntime.state.mintPairingCredential")(function* ( |
| 47 | prepared: PreparedConnection, |
| 48 | payload: AuthCreatePairingCredentialInput, |
| 49 | ): Effect.fn.Return<AuthPairingCredentialResult, PeerPairingCodeError, HttpClient.HttpClient> { |
| 50 | const signer = yield* Effect.serviceOption(ManagedRelay.ManagedRelayDpopSigner); |
| 51 | const remoteAuthorization = yield* Effect.serviceOption( |
| 52 | RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization, |
| 53 | ); |
| 54 | const minted = yield* executeAuthenticatedEnvironmentHttpRequest({ |
| 55 | prepared, |
| 56 | signer, |
| 57 | remoteAuthorization, |
| 58 | group: "auth", |
| 59 | method: "POST", |
| 60 | url: (urls) => urls.pairingCredential(), |
| 61 | timeoutMs: MINT_TIMEOUT_MS, |
| 62 | request: ({ client, headers }) => client.pairingCredential({ headers, payload }), |
| 63 | }).pipe( |
| 64 | Effect.mapError( |
| 65 | (cause) => |
| 66 | new PeerPairingCodeError({ |
| 67 | reason: |
| 68 | cause._tag === "EnvironmentScopeRequiredError" || |
| 69 | cause._tag === "EnvironmentOperationForbiddenError" |
| 70 | ? "not_allowed" |
| 71 | : "unavailable", |
| 72 | cause, |
| 73 | }), |
| 74 | ), |
| 75 | ); |
| 76 | return minted; |
| 77 | }); |
| 78 | |
| 79 | // Untraced: mintPairingCredential owns the span. |
| 80 | const mintOnEnvironment = Effect.fnUntraced(function* (payload: AuthCreatePairingCredentialInput) { |
| 81 | const supervisor = yield* EnvironmentSupervisor.EnvironmentSupervisor; |
| 82 | const prepared = yield* SubscriptionRef.get(supervisor.prepared); |
| 83 | if (Option.isNone(prepared)) { |
| 84 | return yield* new PeerPairingCodeError({ |
| 85 | reason: "unavailable", |
| 86 | cause: "The environment is not connected.", |
| 87 | }); |
| 88 | } |
| 89 | if ( |
| 90 | payload.purpose === "peer-link" && |
| 91 | prepared.value.descriptor?.capabilities.peerLinkPairingCodes !== true |
| 92 | ) { |
| 93 | return yield* new PeerPairingCodeError({ |
| 94 | reason: "unavailable", |
| 95 | cause: "The environment does not support peer-link pairing codes.", |
| 96 | }); |
| 97 | } |
| 98 | return yield* mintPairingCredential(prepared.value, payload); |
| 99 | }); |
| 100 | |
| 101 | /** |
| 102 | * Mints a code on the environment it runs in. Each run mints its own: a code |
| 103 | * is one-use, so two overlapping answers must never share one. |
| 104 | */ |
| 105 | export function createPeerPairingCodeCommand<R, E>( |
| 106 | runtime: Atom.AtomRuntime<EnvironmentRegistry | HttpClient.HttpClient | R, E>, |
| 107 | ) { |
| 108 | return createEnvironmentCommand(runtime, { |
| 109 | label: "environment-data:peer-pairing-code:mint", |
| 110 | execute: (access: AuthMcpClientAccess) => |
| 111 | mintOnEnvironment({ |
| 112 | label: PEER_PAIRING_CODE_LABEL, |
| 113 | access, |
| 114 | purpose: "peer-link", |
| 115 | }).pipe( |
| 116 | Effect.filterOrFail( |
| 117 | (minted) => minted.purpose === "peer-link" && minted.access === access, |
| 118 | () => |
| 119 | new PeerPairingCodeError({ |
| 120 | reason: "unavailable", |
| 121 | cause: "The environment did not issue a peer-link code.", |
| 122 | }), |
| 123 | ), |
| 124 | Effect.map((minted) => minted.credential), |
| 125 | ), |
| 126 | }); |
| 127 | } |
| 128 | |
| 129 | /** |
| 130 | * Mints a hidden code that approves one app's sign-in at `access`, and only that. Servers |
| 131 | * without `mcpApprovalCodes` ignore the level, so check the capability first. |
| 132 | */ |
| 133 | export function createMcpApprovalCodeCommand<R, E>( |
| 134 | runtime: Atom.AtomRuntime<EnvironmentRegistry | HttpClient.HttpClient | R, E>, |
| 135 | ) { |
| 136 | return createEnvironmentCommand(runtime, { |
| 137 | label: "environment-data:mcp-approval-code:mint", |
| 138 | execute: (access: AuthMcpClientAccess) => |
| 139 | mintOnEnvironment({ label: MCP_APPROVAL_CODE_LABEL, access }), |
| 140 | }); |
| 141 | } |