Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// The connection-level trust gate: the ONE place a peer's confirmation is accepted.
//
// Stage 4 makes two desktops equal peers, which means a pairing GRANTS THE PEER SHELL ACCESS on this
// machine. The only thing standing between a relay man-in-the-middle and that shell is mutual
// approval: BOTH humans compare the same SAS out of band and BOTH press Confirm. The pure
// latch is `mutual-approval-core.ts`; this file is the wiring it says it cannot enforce, and the
// wiring is where the property can be silently destroyed.
//
// SECURITY — obligation (a) of mutual-approval-core.ts: `onTunnelText` is called ONLY from
// `connectRelay`'s `onTunnel` callback (relay-socket.ts), which fires only for a payload that
// (1) DECRYPTED under THIS session's key (deriveSessionKey — fresh nonces both ways),
// (2) carried the PEER's role byte (so a relay cannot reflect our own confirm back at us), and
// (3) beat the per-direction monotonic replay counter.
// A plaintext frame from the relay reaches `handleControl` (which understands only `e2ee_hello` /
// `e2ee_ready`) and dies there; it can never reach this module. That is what makes `confirmRemote`
// proof that the REAL peer's human confirmed — and it is exactly what relay-trust.test.ts forges
// against. NEVER add a second call site for `confirmRemote`: not `onRpc`, not `onFrame`, not an IPC
// message from the renderer, not a plaintext handshake control. If a confirm can arrive any other
// way, mutual approval degrades back to ONE-WAY and the local human alone unlocks shell access while
// believing the remote human agreed. The SAS-mismatch backstop does NOT catch that (it catches key
// substitution, not a same-key relay forging the confirm DIRECTION).
//
// SECURITY — obligation (b): EXACTLY ONE `MutualApproval` per pairing attempt, seeded from THIS
// session's ECDH peer key (the key whose shared secret produced the SAS the humans compared). The
// state lives in this closure, is created once per gate, and each connection hangs its own gate off
// its own `onTunnel` — so a confirm arriving on session A's tunnel is physically unable to reach
// session B's state, and `recordApproval` can only ever pin the key bound into the state it is given.
//
// LOCAL confirms have exactly five call sites, three on the HOST side and two on the CLIENT side.
// Host side: `confirmHere()` from the desktop's Team Access dialog (`relay:host:confirm`), the host's
// `autoApprove` for a key its pin store holds (the hosted team's `team.json`), and a hosted owner's
// `relay:hosted:approve`. Client side: the joining human's
// `relay:client:confirm`, and the client's `autoApprove` for a hosted team's approved bookmark
// (src/main/remote/hosted-join.ts). That auto-confirm reads the bookmark's `approvedAt` alone
// (`source` is a label). Share with team's `seedBookmark` sets it without a SAS comparison; that is
// not a new confirm site, because the code it is given came back from `team bootstrap` over an
// authenticated ssh channel. A sixth is a design change.
import {
confirmLocal,
confirmRemote,
emptyMutualApproval,
isMutuallyApproved,
type MutualApproval
} from './mutual-approval-core'
import { parseRpcMessage } from '../../shared/rpc'
/**
* The ONLY remote-confirm signal, carried as an rpc.ts `cast` over the E2EE tunnel
* (`RelaySocket.sendTunnelText` → TAG_TUNNEL_TEXT inside the box). It is deliberately NOT a method
* of the peer RPC surface: a trust frame is consumed here and never forwarded to a dispatcher, so no
* handler table can ever route a confirm.
*/
export const TRUST_CONFIRM = 'trust:confirm'
/**
* A host's refusal, sent over the ENCRYPTED tunnel right before it closes a peer it will not serve.
* It is NOT a trust frame: the gate never consumes it (`onTunnelText` returns false for it) and it
* can never advance approval — it only tells the peer WHY the connection is about to end.
*/
export const TRUST_DENIED = 'trust:denied'
export type TrustDeniedReason = 'denied' | 'removed' | 'expired'
const DENIED_REASONS: readonly TrustDeniedReason[] = ['denied', 'removed', 'expired']
export interface PinStore {
/** Persist the approval. Called once, only after BOTH ends confirmed; failures are swallowed. */
record(state: MutualApproval): Promise<void>
}
export interface TrustGate {
/** SAS both humans compare ("NNN NNN NNNN", v2), or null before the key is derived. */
sas(): string | null
/** This human pressed Confirm. Latches localConfirmed and tells the peer over the tunnel. */
confirmHere(): void
/**
* A TEXT frame arrived on the ENCRYPTED tunnel. Returns true when it was a trust frame (and was
* therefore consumed — never forward it on to the RPC dispatcher). Anything that is not
* `{t:'cast', method:'trust:confirm'}` is ignored and returns false.
*
* Call this ONLY from `connectRelay`'s `onTunnel`. See the SECURITY block above.
*/
onTunnelText(json: string): boolean
/**
* Both humans confirmed. Latched the moment the second confirm arrives, BEFORE the pin write and
* `onOpen`: true while the pin is still in flight, and it never goes back to false. A host uses it
* to tell "approved, opening" (hold the peer's frames) from "not approved" (refuse them).
*/
isApproved(): boolean
/**
* Both humans confirmed → the pin attempt has settled and `onOpen` has fired. True exactly when
* `onOpen` has run: never while the pin write is still in flight.
*/
isOpen(): boolean
/** The peer's stable box public key (base64) this gate is bound to. */
peerKeyB64(): string | null
}
export interface TrustGateOptions {
/** The peer's stable box public key from THIS session's ECDH (`RelaySocket.peerPublicKeyB64()`). */
peerKeyB64: string
/** Identity of this pairing attempt. */
sessionId: string
/**
* THIS session's SAS. Pass `socket.sas()` (`sasFromSharedKey(baseKey)`, the function `mutualSas`
* aliases), NOT a value derived anywhere else: the digits the two humans compare must come from
* the same ECDH shared secret that keys this connection.
*/
sas: () => string | null
/** Send our own confirm to the peer — MUST be `socket.sendTunnelText` (encrypted). */
sendConfirm: (json: string) => void
/** Fires exactly once, when both sides have confirmed: the session may open. */
onOpen: () => void
/** Where a mutual approval is pinned. Absent = pin nothing (the session still opens). */
pins?: PinStore
/**
* Latch the LOCAL confirm at construction (and send it to the peer) — for a key this end already
* trusts. It never touches the REMOTE half: the peer's human (or the peer's own pin) must still
* confirm over the encrypted tunnel before anything opens. Absent/false = byte-identical legacy
* behavior (nothing is sent until `confirmHere()`).
*
* (a) The confirm is sent SYNCHRONOUSLY, inside `createTrustGate` itself — before the caller has
* even stored the returned gate. `sendConfirm` must therefore already be able to deliver: over an
* in-process transport the relay socket may not exist yet during `onReady`, and a confirm sent
* into nothing is lost silently (a pinned reconnect then never opens). A caller that cannot promise
* that passes `false` and calls `confirmHere()` itself once the socket and the gate exist, as the
* core relay host and client do.
*
* (b) Derive it from the caller's OWN pin store, for exactly `peerKeyB64` (this session's ECDH
* peer key) — never from anything the peer sent. A value the peer can influence turns this into a
* remote-controlled local confirm, i.e. one-way approval.
*/
autoApprove?: boolean
}
export function createTrustGate(opts: TrustGateOptions): TrustGate {
// Obligation (b): ONE state per pairing attempt, bound to THIS session's ECDH peer key.
let state: MutualApproval = emptyMutualApproval(opts.peerKeyB64, opts.sessionId)
// Two flags, deliberately: `approved` latches synchronously the moment BOTH confirms are in (so the
// pin-then-open sequence runs exactly once), while `opened` flips only when that sequence ends and
// `onOpen` fires. `isOpen()` reads `opened`, so it can never report an open session whose pin
// write is still in flight or whose `onOpen` has not run — it and `onOpen` agree by construction,
// whatever the pin store's microtask depth.
let approved = false
let opened = false
const settle = (): void => {
if (approved || !isMutuallyApproved(state)) {
return
}
approved = true
const pinned = state
void (async () => {
// Pin FIRST (the store is handed only a state in which BOTH confirmed, carrying only the key
// bound into it), then open. A failed write must not strand a session both humans confirmed —
// it only means the next connect asks for the SAS again, which is the safe direction.
try {
await opts.pins?.record(pinned)
} catch {
// Persisting the pin is best-effort; consent for THIS session is already mutual.
}
opened = true
opts.onOpen()
})()
}
const gate: TrustGate = {
sas: () => opts.sas(),
confirmHere() {
state = confirmLocal(state)
// Tell the peer over the ENCRYPTED tunnel. This is the only confirm we ever send.
opts.sendConfirm(JSON.stringify({ t: 'cast', method: TRUST_CONFIRM, args: [] }))
settle()
},
onTunnelText(json) {
const m = parseRpcMessage(json)
if (!m || m.t !== 'cast' || m.method !== TRUST_CONFIRM) {
return false
}
state = confirmRemote(state)
settle()
return true // consumed: a trust frame is NEVER forwarded to the RPC dispatcher
},
isApproved: () => approved,
isOpen: () => opened,
peerKeyB64: () => opts.peerKeyB64
}
// A fresh state has no remote confirm, so this can never open the gate by itself.
if (opts.autoApprove) gate.confirmHere()
return gate
}
/** The cast a host sends over the ENCRYPTED tunnel right before closing a refused peer. */
export function deniedFrame(reason: TrustDeniedReason): string {
return JSON.stringify({ t: 'cast', method: TRUST_DENIED, args: [reason] })
}
/** A denial reason, or null for anything that is not a well-formed denial. */
export function parseDenied(json: string): TrustDeniedReason | null {
const m = parseRpcMessage(json)
if (!m || m.t !== 'cast' || m.method !== TRUST_DENIED) return null
const r = m.args[0]
return (DENIED_REASONS as readonly unknown[]).includes(r) ? (r as TrustDeniedReason) : null
}