Skip to content

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.

9.2 KB
Raw Blame
import { IPC } from './ipc'

/**
 * HOST-ONLY channels: the RPC methods a relay GUEST may never reach, in ONE list both shells read.
 *
 * A relay peer (a paired phone, another desktop over 4c) is a first-class client of this machine's
 * core — that is the point of the peer registry — but it is NOT the host's user. A small set of
 * methods are the host's own control plane, and admitting one of them from a guest hands over
 * something the guest could not otherwise have:
 *
 *  - `githubControl:*` — the token/approval plane for the host's GitHub credentials.
 *  - `project-setup:run` — starts a script ON the host, in the host's shell, as the host's user.
 *  - `project-setup:consent-submit` — the ANSWER to the host's own trust prompt. Admitting `run`
 *    and this one together is the whole attack: a guest raises the prompt and then approves it
 *    itself, so a shared `.nodeterm/project.json` script executes with no human ever looking at a
 *    dialog. Either one alone is much weaker; the pair is a complete self-approval loop.
 *  - `project-setup:cancel` — the other side of the same run's control: a guest must not be able to
 *    kill the host's setup mid-write.
 *  - `project-setup:request-trust` — RAISES the host's own consent dialog for a project's launch
 *    settings. Alone it is prompt spam on someone else's screen; paired with an admitted
 *    consent-submit it is the same self-approval loop as run+consent-submit, ending in a shared
 *    `launchCmd`/`env` (or shell) approved for the host's own agent launches.
 *
 *  - `pty:launch-headless` (#925) — the desktop's canvas-control `--run-now` / `run`: it starts a
 *    node's session with no viewer and types its launch on the host. The relay guest's own bridge
 *    already refuses it (a relay tab inherits ws-bridge's `pty`), and this makes the refusal hold
 *    host-side for a peer that sends the raw request (spec §6: "Relay tab | Refuses").
 *  - `station-notice:dropped` — a DROPPED verdict makes the host tell an orchestrator, possibly in
 *    its own session, that one of its stations died. It is a pane measurement only the HOST's
 *    renderer makes (a relay tab takes the inert stub), so a guest sending it is claiming a fact
 *    about the host's panes it never measured.
 *  - `station-notice:list` — every project's failed-station ids and titles, unscoped. A relay tab
 *    never asks (it takes the inert stub), and a guest bound to ONE project must not read the rest.
 *
 * DELIBERATELY NOT LISTED: `project-setup:subscribe`/`unsubscribe` and the `project-setup:event:*`
 * push. They neither start nor authorize anything, and a peer that can see the canvas can already
 * see that a setup is running. The gate is on ACTION, not on the namespace — which is also why
 * this is an explicit list rather than a `project-setup:` prefix.
 *
 * This lives in `shared/` because it is a policy question, not a shell mechanism: two shells each
 * carrying their own `startsWith` is exactly how one of them ends up a release behind the other.
 */
export const HOST_ONLY_CHANNEL_PREFIXES: readonly string[] = [
  'githubControl:',
  // The host's credential and identity planes. None of these crosses the relay for a legitimate
  // tab (relay-api.ts keeps license/accounts/usage LOCAL), and each is something the invite never
  // granted: the license key and its seats, the managed Claude/Codex logins (a login node writes
  // credentials into the account dir, removal deletes one), and account usage read with the
  // host's stored tokens.
  'license:',
  // The free-tier open-project allowance: refuses a relay peer's INBOUND `projectLimit:state` /
  // `projectLimit:claim` requests — a claim spends THIS device's allowance under this machine's hash,
  // and the state reports the host's Pro and DO_NOT_TRACK facts. A relay tab never sends them (it
  // keeps its local preload; relay-api.ts spreads `...local`). This list gates inbound req/cast ONLY:
  // the outbound `projectLimit:changed` push is kept off relay peers separately, by sending it to
  // this machine's own windows only (core/project-limit.ts), never through `platform().broadcast`,
  // which fans out to every relay peer.
  'projectLimit:',
  'claude-accounts:',
  'codex-accounts:',
  'usage:',
  // The trust plane itself: who is paired, who may connect, and the invites that mint seats. A
  // peer that could reach these could pin its own key or revoke the host's other devices. Note the
  // trailing colons: `relay:host:` does not match the hosted-team verbs (`relay:hosted:*`), which
  // the Server Edition's hosted service intercepts and judges itself.
  'pairing:',
  'remote:',
  'relay:host:',
  'relay:client:',
  // Agent-integration consent status: paths in the host's home it kept or wrote. The consent itself
  // is in settings (already host-only).
  'integrations:',
  // Simulator node: the host's iOS simulators / Android emulators — boot, erase, install, input.
  // A relay tab never offers the node (relay-api keeps the namespace local), so a peer sending one
  // of these is asking to drive the host's devices.
  'simulator:',
  // `nodeterm://` links: a link clicked on THIS machine opens a node here after THIS machine's user
  // approves it. Raw ipcMain handlers (no peer reaches them); listed so a move onto the platform
  // table cannot quietly open them.
  'open-link:'
]

export const HOST_ONLY_CHANNELS: ReadonlySet<string> = new Set([
  IPC.projectSetupRun,
  IPC.projectSetupCancel,
  IPC.projectSetupConsentSubmit,
  IPC.projectSetupRequestTrust,
  IPC.ptyLaunchHeadless,
  // A relay peer never delivers a held launch (commitOwnedLaunchAttempt), and a peer that could
  // claim one would make every viewer of the host stand down from it (#1173).
  IPC.workspaceClaimLaunch,
  // Executes an agent launch on the host and reads a host-local `--prompt-file` into it. A relay
  // tab never sends it (its pty bridge omits the member); this holds the refusal host-side too.
  IPC.ptyExecuteLaunch,
  // Types into a pane of THIS machine (or its SSH host); a relay peer must never reach it.
  IPC.ptySendPaneKeys,
  // Prepare-for-update ends EVERY session on this machine's session host and quits the app. Only
  // the host's own user may do that. Raw ipcMain handlers (no peer reaches them); listed here too
  // so moving them onto the platform table later cannot quietly open them.
  IPC.appUpdatePrepInspect,
  IPC.appUpdatePrepShutdown,
  IPC.appUpdatePrepQuit,
  // A board comment that @mentions a session types into that session's pane. Only the host's own
  // user may do that: a relay peer's comment is display-only. Registered with a raw ipcMain handler
  // (so no peer can reach it at all); listed here too, so moving it onto the platform table later
  // cannot quietly open it.
  IPC.agentBoardCommentDeliver,
  IPC.stationNoticeDropped,
  // The host's own dispatcher state; a relay tab's board belongs to the host and its dispatch is
  // refused, so a peer has nothing true to report.
  IPC.boardDispatchReport,
  IPC.stationNoticeList,
  // Unscoped: every project's station outcomes and their notes. A relay guest bound to one project
  // must not read another's, and a relay tab's launch loop is refused anyway (its stub is inert).
  IPC.stationOutcomeList,
  // Same class: which of the host's stations (any project) have work handed to them.
  IPC.stationHandoverList,
  // "Open recent": the host's conversation history — titles are prompts the host's user typed, in
  // every project. A relay tab lists its OWN machine's history (relay-api keeps it `...local`), so
  // no legitimate peer asks the host for this.
  IPC.recentConversationsList,
  // The host's settings. `settings:save` is the dangerous half: `modelGateway.baseUrl` is the TRUST
  // ANCHOR `agent:discover-models` uses to decide whether it may resolve the stored
  // `${secret:model-gateway-api-key}` (core/agent-env-ipc.ts), so a peer that could save settings
  // and then ask for discovery would have the keychain-held key sent to a URL of its choosing.
  // `settings:load` goes too: settings.json carries custom agents' launch env (API keys), and a
  // relay tab keeps its settings LOCAL (relay-api.ts), so no legitimate peer reads the host's.
  IPC.settingsLoad,
  IPC.settingsSave,
  // Model-gateway discovery and the write-only gateway credential. Discovery resolves host-side
  // secrets against the saved gateway; the credential verbs write/clear the keychain-held key.
  IPC.agentDiscoverModels,
  IPC.agentGatewayCredentialStatus,
  IPC.agentGatewayCredentialSave,
  IPC.agentGatewayCredentialClear,
  // Dev-server ports: a scan lists the host's listening ports, and a forward binds a port on the
  // HOST machine's loopback over one of its SSH masters. Neither is a peer's to ask for.
  IPC.devPortsScan,
  IPC.devPortsForward,
  IPC.devPortsUnforward
])

/** What a refused peer is told. One wording, so the two shells answer identically. */
export const HOST_ONLY_REFUSAL = 'host-control method is not available to relay peers'

export function isHostOnlyChannel(channel: string): boolean {
  // The method name arrives off the wire; a non-string is never a channel (and must not throw).
  if (typeof channel !== 'string') return false
  if (HOST_ONLY_CHANNELS.has(channel)) return true
  return HOST_ONLY_CHANNEL_PREFIXES.some((prefix) => channel.startsWith(prefix))
}