Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

The gateway runs in a process of its own: the relay and its E2EE leave the core's (#905)

Dee25573c050022
diff --git a/cli/AGENTS.md b/cli/AGENTS.md
index 77e7c58a1..41e1e60c7 100644
--- a/cli/AGENTS.md
+++ b/cli/AGENTS.md
@@ -19,7 +19,9 @@ SERVICES src/services/ everything else: search, viewers, models, workspaces,
together. It is the core's own entry (`harness __run`); `src/cli.ts` is the CLI, and calls in for
`__run` and `start -f`. `src/backendSocket.ts` is the transport: it receives frames and dispatches them.
`src/gateway/` is the relay: the backend link, the E2EE sessions and keys, and every rule about what a
-remote client may send and how what it is sent is sealed. The socket speaks to it in the clear through
+remote client may send and how what it is sent is sealed. It runs in a process of its own
+(`src/gateway/gatewayProcess.ts`; the core's side is `src/core/gatewayLink.ts`), or in the core's with
+`HARNESSD_SERVICES=none` (`src/gateway/start.ts`). The socket speaks to it in the clear through
`GatewayPort` and hears it through `GatewayEvents` (`src/core/api.ts`), and never holds a key.
## Where new code goes
diff --git a/cli/e2e/gatewayProcess.e2e.ts b/cli/e2e/gatewayProcess.e2e.ts
new file mode 100644
index 000000000..671bff850
--- /dev/null
+++ b/cli/e2e/gatewayProcess.e2e.ts
@@ -0,0 +1,212 @@
+/**
+ * The gateway — the relay and its end-to-end encryption — in a process of its own (docs/design/
+ * 2026-10-06-core-boundary-next.md, step 10, R2), on the real daemon, signed in on the fake backend, with a
+ * phone paired and reaching it through the fake relay (harness/relayPhone.ts) and the desktop window on the
+ * machine itself. Whatever happens to the gateway's process — killed outright, hung, leaking memory, crashing
+ * on every start — costs the remote clients alone: the window on this computer and every agent go on, the
+ * core never restarts, and once the master has the gateway back the phone opens a new session and works.
+ *
+ * Nothing here reaches beyond this machine: the daemon's every server setting is the fake backend's.
+ */
+import { execFileSync } from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { LocalClient, type Frame } from './harness/client.js'
+import { until, type IsolatedDaemon } from './harness/daemon.js'
+import { startFleet, startPhoneMachine, type Fleet, type PhoneMachine } from './harness/fleet.js'
+import { RelayPhone, type PhoneFrame } from './harness/relayPhone.js'
+
+const row = async (client: LocalClient, agentId: string) =>
+ ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
+ .find((agent) => agent.id === agentId)
+
+const isTurn = (type: string, agentId: string) => (frame: Frame | PhoneFrame) => frame.type === type && frame.agentId === agentId
+
+/** This daemon's gateway: titled `harnessd-gateway` AND started by its own master, by the pid it logged. */
+function gatewayPids(d: IsolatedDaemon): number[] {
+ const ours = new Set([...d.log().matchAll(/\[harnessd\] service gateway started \(pid (\d+)\)/g)].map((match) => Number(match[1])))
+ const table = execFileSync('ps', ['-A', '-o', 'pid=,command=']).toString().trim().split('\n')
+ return table.map((line) => line.trim().match(/^(\d+)\s+(.*)$/)).filter((match): match is RegExpMatchArray => !!match)
+ .filter(([, pid, command]) => command.trim() === 'harnessd-gateway' && ours.has(Number(pid))).map(([, pid]) => Number(pid))
+}
+const restarts = (d: IsolatedDaemon) => d.log().split('\n').filter((line) => /\[harnessd\] service gateway started .* restart \d+/.test(line)).length
+const connections = (d: IsolatedDaemon) => d.log().split('[services] gateway connected').length - 1
+
+describe('the gateway in its own process', () => {
+ let world: PhoneMachine | undefined
+ let phone: RelayPhone | undefined
+ let desk: LocalClient | undefined
+ afterEach(async () => {
+ phone?.close()
+ desk?.close()
+ await world?.close()
+ world = undefined; phone = undefined; desk = undefined
+ })
+
+ const fresh = async (env: Record<string, string> = {}, opts: { phone?: boolean } = {}) => {
+ const w = await startPhoneMachine({ env: {
+ HARNESSD_SERVICES: 'gateway',
+ HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200',
+ HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000',
+ ...env,
+ } })
+ world = w
+ const { backend, machine } = w
+ onTestFailed(() => {
+ console.log(`---- daemon log\n${machine.daemon.log().split('\n').slice(-150).join('\n')}`)
+ console.log(`---- fake backend saw\n${backend.seen.slice(-40).join('\n')}`)
+ })
+ desk = await LocalClient.connect(machine.daemon, { machineId: machine.machineId })
+ const cwd = join(machine.daemon.projectsDir, 'gateway')
+ mkdirSync(cwd, { recursive: true })
+ const created = await desk.request('agent_create', { engine: 'claude', cwd, bypassPermission: true }, 60_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ const agentId: string = created.agent.id
+ await until('the agent to bind its conversation', async () => (await row(desk!, agentId))?.sessionId || null, 45_000, 500)
+ phone = new RelayPhone({ backend, machineId: machine.machineId, identity: w.phone.identity, machinePub: machine.identity.pub, token: w.phone.token })
+ if (opts.phone !== false) {
+ await until('the machine to be on the relay', () => backend.nodeUp(machine.machineId) || null, 30_000)
+ await phone.open(30_000)
+ }
+ return { w, backend, machine, desk, phone, agentId }
+ }
+ /** A turn from the window on this computer, to its end: what the gateway's troubles must never touch. */
+ const deskTurn = async (client: LocalClient, agentId: string, content: string) => {
+ const ended = client.next(isTurn('turn_ended', agentId), 45_000, `turn_ended (${content})`)
+ client.send('message', { agentId, content })
+ await ended
+ }
+ /** A turn from the phone, to its end, as the phone sees it. */
+ const phoneTurn = async (p: RelayPhone, agentId: string, content: string) => {
+ const ended = p.next(isTurn('turn_ended', agentId), 45_000, `turn_ended on the phone (${content})`)
+ expect(p.send('message', { agentId, content })).toBe(true)
+ await ended
+ }
+ /** The phone back: once the machine is on the relay again, a new session, retried until it opens. */
+ const reopen = async (w: PhoneMachine, p: RelayPhone) => {
+ await until('the machine to be back on the relay', () => w.backend.nodeUp(w.machine.machineId) || null, 60_000, 200)
+ await until('the phone to open a new session', async () => { await p.open(10_000); return true }, 60_000, 500)
+ }
+
+ it('carries the phone from a process of its own: sealed both ways, with the core speaking to it in the clear', async () => {
+ const { backend, machine, phone, desk, agentId } = await fresh()
+ expect(gatewayPids(machine.daemon)).toHaveLength(1)
+ expect(machine.daemon.log()).toContain('[services] gateway connected')
+ await phoneTurn(phone, agentId, 'from the phone, through the gateway')
+ await deskTurn(desk, agentId, 'from the desk, beside it')
+ const relayed = [...(backend.webSent.get(phone.connId!) ?? []), ...(backend.webReceived.get(phone.connId!) ?? [])]
+ expect(relayed.filter((f) => f.type === 'message' || f.type === 'turn_started').every((f) => (f.payload as any)?.__e2e)).toBe(true)
+ expect(JSON.stringify(relayed)).not.toContain('through the gateway')
+ // The machine's E2EE fingerprint and pairings, which the core asks the gateway for.
+ const status = await (await fetch(`http://127.0.0.1:${machine.daemon.port}/api/status`)).json() as Record<string, any>
+ expect(status.fingerprint).toEqual(expect.any(String))
+ expect(status.pairs).toEqual([expect.objectContaining({ label: 'phone', role: 'web' })])
+ expect(status.connected).toBe(true)
+ expect(machine.daemon.coresStarted()).toBe(1)
+ })
+
+ it('killed outright: the phone loses the machine and gets it back; the window and the agents never notice', async () => {
+ const { w, machine, phone, desk, agentId } = await fresh()
+ const before = gatewayPids(machine.daemon)
+ expect(before).toHaveLength(1)
+ for (const pid of before) process.kill(pid, 'SIGKILL')
+ await until('the phone to know it has no session', () => !phone.ready || null, 20_000, 50)
+ // The window on this computer works on, and so does the agent.
+ await deskTurn(desk, agentId, 'while the gateway was gone')
+ await until('the master to restart the gateway', () => restarts(machine.daemon) >= 1 || null, 30_000, 200)
+ await until('the gateway to connect again', () => connections(machine.daemon) >= 2 || null, 30_000, 200)
+ await reopen(w, phone)
+ await phoneTurn(phone, agentId, 'after the gateway came back')
+ expect(gatewayPids(machine.daemon).some((pid) => !before.includes(pid))).toBe(true)
+ expect(machine.daemon.coresStarted()).toBe(1)
+ })
+
+ it('hung: the master finds it by its heartbeat and starts it again; the core never waited on it', async () => {
+ const { w, machine, phone, desk, agentId } = await fresh({ HARNESSD_SERVICE_HEARTBEAT_TIMEOUT_MS: '2000' })
+ for (const pid of gatewayPids(machine.daemon)) process.kill(pid, 'SIGSTOP')
+ // Stopped, it reads nothing: the window's turns and their every event go on regardless.
+ await deskTurn(desk, agentId, 'the core does not wait on a hung gateway')
+ await until('the master to find the gateway hung', () => machine.daemon.log().includes('[harnessd] service gateway sent no heartbeat') || null, 30_000, 200)
+ await until('the gateway to be started again', () => restarts(machine.daemon) >= 1 || null, 30_000, 200)
+ await reopen(w, phone)
+ await phoneTurn(phone, agentId, 'after the hang')
+ expect(machine.daemon.coresStarted()).toBe(1)
+ })
+
+ it('leaking: restarted at its memory budget, before it can hurt anything else', async () => {
+ const { machine, desk, agentId } = await fresh({ HARNESSD_TEST_FAULTS: 'gateway.leak', HARNESSD_SERVICE_HEAP_LIMIT_MIB: '128' }, { phone: false })
+ await until('the master to restart the gateway for memory', () => /\[harnessd\] service gateway: (its heap is at|it is using)/.test(machine.daemon.log()) || null, 60_000, 250)
+ await until('the gateway to be started again', () => restarts(machine.daemon) >= 1 || null, 30_000, 200)
+ await deskTurn(desk, agentId, 'the leak was the gateway\'s alone')
+ expect(machine.daemon.coresStarted()).toBe(1)
+ })
+
+ it('crashing on every start: parked, the phone cannot reach the machine, and the window and agents go on', async () => {
+ const { w, machine, desk, agentId } = await fresh({ HARNESSD_TEST_FAULTS: 'gateway.crash', HARNESSD_SERVICE_PARK_CRASHES: '3' }, { phone: false })
+ await until('the master to park the gateway', () => machine.daemon.log().includes('[harnessd] service gateway ended 3 times') || null, 60_000, 250)
+ // Nothing dials the backend for this machine meanwhile: the phone cannot open a session.
+ await expect(phone!.open(5_000)).rejects.toThrow()
+ expect(w.backend.nodeUp(machine.machineId)).toBe(false)
+ await deskTurn(desk, agentId, 'the gateway is parked and nothing else cares')
+ // The pairings are the gateway's to tell: refused plainly, not hung.
+ const pairs = await fetch(`http://127.0.0.1:${machine.daemon.port}/api/status`)
+ expect(pairs.ok).toBe(true)
+ expect(((await pairs.json()) as Record<string, any>).pairs).toEqual([])
+ expect(machine.daemon.coresStarted()).toBe(1)
+ })
+
+ describe('a window on this computer working on another machine, through the gateway', () => {
+ let fleet: Fleet | undefined
+ const clients: LocalClient[] = []
+ afterEach(async () => {
+ for (const client of clients.splice(0)) client.close()
+ await fleet?.close()
+ fleet = undefined
+ })
+
+ it('reaches B through A\'s gateway, sealed by it, and opens again once A\'s gateway is back', async () => {
+ const f = await startFleet({ envA: { HARNESSD_SERVICES: 'gateway', HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000' } })
+ fleet = f
+ onTestFailed(() => {
+ console.log(`---- daemon A log\n${f.a.daemon.log().split('\n').slice(-120).join('\n')}`)
+ console.log(`---- daemon B log\n${f.b.daemon.log().split('\n').slice(-60).join('\n')}`)
+ })
+ await until('both machines connected to the backend', () => f.backend.nodeUp(f.a.machineId) && f.backend.nodeUp(f.b.machineId), 30_000)
+ const onB = await LocalClient.connect(f.b.daemon, { machineId: f.b.machineId })
+ clients.push(onB)
+ const cwd = join(f.b.daemon.projectsDir, 'on-b')
+ mkdirSync(cwd, { recursive: true })
+ const created = await onB.request('agent_create', { engine: 'claude', cwd, bypassPermission: true }, 60_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ const agentId: string = created.agent.id
+ await until('the agent on B to bind', async () => (await row(onB, agentId))?.sessionId || null, 45_000, 500)
+ // The window on A selects B: A's local socket hands it to A's gateway, which holds the session to B.
+ const viaA = await LocalClient.connect(f.a.daemon, { machineId: f.b.machineId })
+ clients.push(viaA)
+ await until('B\'s agents through A', async () => ((await viaA.request<{ agents: Array<{ id: string }> }>('agents_list', {}, 30_000)).agents ?? []).some((a) => a.id === agentId) || null, 60_000, 1_000)
+ const ended = viaA.next(isTurn('turn_ended', agentId), 45_000, 'a turn on B from A\'s window')
+ viaA.send('message', { agentId, content: 'from A\'s window, on B' })
+ await ended
+ // What A's gateway sent B went sealed: the relay never read the message.
+ const relayed = [...f.backend.webSent.values(), ...f.backend.webReceived.values()].flat()
+ expect(relayed.some((frame) => frame.type === 'message')).toBe(true)
+ expect(JSON.stringify(relayed)).not.toContain('from A\'s window, on B')
+ // A's gateway killed: the window's session to B ends with it, and A's own window never notices.
+ const before = gatewayPids(f.a.daemon)
+ expect(before).toHaveLength(1)
+ const onA = await LocalClient.connect(f.a.daemon, { machineId: f.a.machineId })
+ clients.push(onA)
+ for (const pid of before) process.kill(pid, 'SIGKILL')
+ await until('the window on B to be closed', () => viaA.closed || null, 20_000, 100)
+ expect((await onA.request('agents_list', {}, 30_000)).error).toBeUndefined()
+ await until('A\'s gateway to connect again', () => connections(f.a.daemon) >= 2 || null, 30_000, 200)
+ await until('A\'s window to reach B again', async () => {
+ const again = await LocalClient.connect(f.a.daemon, { machineId: f.b.machineId })
+ clients.push(again)
+ return ((await again.request<{ agents: Array<{ id: string }> }>('agents_list', {}, 15_000)).agents ?? []).some((a) => a.id === agentId) || null
+ }, 90_000, 2_000)
+ expect(f.a.daemon.coresStarted()).toBe(1)
+ })
+ })
+})
diff --git a/cli/src/architecture.spec.ts b/cli/src/architecture.spec.ts
index 103896c73..3cf34ed73 100644
--- a/cli/src/architecture.spec.ts
+++ b/cli/src/architecture.spec.ts
@@ -144,8 +144,10 @@ const WALK_TIMEOUT_MS = 60_000
* those moves, and runForeground gained 28.
*/
const RUN_FOREGROUND_BUDGET = 2_600
-/** Lowered from 2,180 when the relay and its E2EE left the socket for the gateway (step 10, R1). */
-const BACKEND_SOCKET_BUDGET = 1_440
+/** Lowered from 2,180 when the relay and its E2EE left the socket for the gateway (step 10, R1: 1,440).
+ * The Wi-Fi device's relay came back to it in R2, beside the device service it answers for, over the
+ * gateway's sessions (lib/autonomous-device/overGateway.ts): 1,460. */
+const BACKEND_SOCKET_BUDGET = 1_460
/** Exceptions, each with its reason. Keep this short. */
const SERVICE_MAY_IMPORT: Record<string, string> = {
@@ -186,17 +188,25 @@ const SERVICE_MAY_IMPORT: Record<string, string> = {
* through (`GatewayPort`, `GatewayEvents` in core/api.ts), still in the core's process. The socket lost
* 742 lines; the gateway's 1,193 and the interfaces' 110 are loaded until R2 runs the gateway in a process
* of its own, which takes them, the E2EE manager and the P2P channels out of the core's process.
+ *
+ * Then at 95,689 in 420 (step 10, R2), from 102,524 in 433: the gateway runs in a process of its own (gateway/gatewayProcess.ts),
+ * and the core loads it only to run it in its own process instead (services/inline.ts). With it went the
+ * E2EE manager, the backend link, P2P and STUN, the windows' relay pool, the trust group and the device
+ * key log. What of lib/e2ee the core still loads is the fleet's lane (R3) and Share's own crypto (step 8).
*/
//
// Connected TUI shells added a literal-argv launch port and shell service (#893, 160 loaded lines); moving
// the search filename out of its CLI command removed 188, so that change lowered the closure by 28.
-const CORE_CLOSURE_BUDGET = 102_600
+const CORE_CLOSURE_BUDGET = 95_800
/** What is not the core's, by path: each goes to a service or its own process, in the plan's order. */
const EDGE: RegExp[] = [
/^gateway\//, /^lib\/e2ee\//, /^cable\//, /^device\//, /^lib\/autonomous-device\//, /^sharing\//, /^teams\//, /^orchestrator\//, /^services\//,
/^lib\/grid(Attach|Credentials|Derive|Ensure|Exec|FleetRpc|Handoff|Install|McpUrl|Models|ModelsPayload|Picture|Presence|Reader|Target|Wake)\.ts$/,
/^lib\/localModels\.ts$/,
+ // The relay's own parts, the gateway's alone: the windows' sessions to other machines, P2P and STUN, the
+ // remote viewers' proxy, and the shaping of what goes up the link.
+ /^lib\/(remoteRelay|terminalP2p|stunSelect|remoteViewerProxy|deviceRecentTrim|commanderReplay)\.ts$/,
// The Store's and the viewers' parts of dsh; the launch path (installed, manifest, launch, runtime, …) is the core's.
/^dsh\/(catalog|install|update|updates|registry|wire|service|lock|builtins|viewer|viewerLedger|verdict|artifacts)\.ts$/,
// Search's index; the readers of other engines' sessions (external.ts, externals/) are the core's, for adoption.
@@ -244,13 +254,10 @@ const CORE_MAY_REACH: Record<string, string> = {
'dsh/service.ts': STORE_BYPASS,
'dsh/update.ts': STORE_BYPASS,
'dsh/updates.ts': STORE_BYPASS,
- 'gateway/gateway.ts': 'step 10, R2: the gateway, in a process of its own',
- 'gateway/upstream.ts': 'step 10, R2: the gateway, in a process of its own',
- 'lib/autonomous-device/direct.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
- 'lib/autonomous-device/discovery.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/dump.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/input.ts': 'step 9: the pane writer lock, into core/input.ts',
'lib/autonomous-device/localApi.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
+ 'lib/autonomous-device/overGateway.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/parts.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/relay.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/resultContract.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
@@ -261,20 +268,14 @@ const CORE_MAY_REACH: Record<string, string> = {
'lib/autonomous-device/storeContract.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/storeRuntime.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/stream.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
- 'lib/e2ee/applicationFrames.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/core.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/deviceHistory.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/deviceLog.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/deviceLogStore.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/deviceLogSyncer.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/groupSyncer.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/machinePeers.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/manager.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/passwordPake.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/relayClient.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/replayWindow.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/store.ts': 'step 10: the relay and E2EE, in the gateway',
- 'lib/e2ee/trustGroup.ts': 'step 10: the relay and E2EE, in the gateway',
+ 'lib/e2ee/applicationFrames.ts': 'step 10, R3: the fleet\'s lane, signed and sealed through the gateway',
+ 'lib/e2ee/core.ts': 'step 8: Share seals its own frames with it (and R3: the fleet\'s lane)',
+ 'lib/e2ee/machinePeers.ts': 'step 10, R3: the fleet\'s lane, signed and sealed through the gateway',
+ 'lib/e2ee/passwordPake.ts': 'with lib/e2ee/store.ts',
+ 'lib/e2ee/relayClient.ts': 'step 10, R3: the fleet\'s lane, signed and sealed through the gateway',
+ 'lib/e2ee/replayWindow.ts': 'step 10, R3: the fleet\'s lane, signed and sealed through the gateway',
+ 'lib/e2ee/store.ts': 'step 8 and R3: this machine\'s identity, for Share and the fleet\'s lane',
+ 'lib/e2ee/terminalSeal.ts': 'step 10, R3: the fleet\'s lane, signed and sealed through the gateway',
'lib/gridAttach.ts': 'step 7: models, in its own process',
'lib/gridCredentials.ts': 'step 7: models, in its own process',
'lib/gridDerive.ts': 'step 7: models, in its own process',
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index d6858afbb..93f592d4c 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -179,7 +179,7 @@ describe('reviewed permanent deletion RPCs', () => {
it('tells a relayed client whose terminal bytes find no session that its session is gone', async () => {
const socket = relaySocket('fixture')
const internals = socket as any
- const { sealTerminalBinary } = await import('./lib/terminalBinary.js')
+ const { sealTerminalBinary } = await import('./lib/e2ee/terminalSeal.js')
const raw = sealTerminalBinary(new Uint8Array(32).fill(7), 9, { kind: 1, streamId: '00112233-4455-6677-8899-aabbccddeeff', seq: 1, bytes: new TextEncoder().encode('ls\r'), compressed: false })!
const gateway = gatewayOf(socket) as any
gateway.enqueueTerminalBinary('web:gone', raw)
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 1e42234ee..1404c8b46 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -6,6 +6,8 @@ import type { ActivityFrame } from './lib/turnActivity.js'
import { MonitorCompletions } from './lib/harnessMonitor.js'
import type { HarnessShareOwner } from './sharing/owner.js'
import { SHARE_REQUEST_TYPES } from './sharing/protocol.js'
+import { deviceRelayOverGateway, type DeviceRelayOverGateway } from './lib/autonomous-device/overGateway.js'
+import type { AutonomousDeviceService, AutonomousDeviceFrame } from './lib/autonomous-device/service.js'
/**
* BackendSocket — the clients' hub and the request dispatch: the windows and tools on this computer
* (localWsServer.ts), and the remote clients the gateway hands on (gateway/gateway.ts), each in its own
@@ -62,8 +64,7 @@ import { OwnerCommands, OWNER_COMMAND_TYPES } from './lib/ownerCommands.js'
import { VIEWER_DOWN_TYPES } from './lib/viewerWire.js'
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
import { encodeTerminalLocal, type TerminalBinaryClear } from './lib/terminalBinary.js'
-import { PAIR_REQUESTS, PLATE_REQUEST, rpcResultType } from './lib/e2ee/applicationFrames.js'
-import { BACKEND_ONLY_DOWN_TYPES, GATEWAY_REQUEST_TYPES, isLocalClientId, logSafeType, type DownTransport } from './lib/relayFrames.js'
+import { BACKEND_ONLY_DOWN_TYPES, GATEWAY_REQUEST_TYPES, isLocalClientId, logSafeType, PAIR_REQUESTS, PLATE_REQUEST, rpcResultType, type DownTransport } from './lib/relayFrames.js'
import { sid, logFrame } from './lib/log.js'
export { isLocalClientId, type DownTransport }
@@ -446,6 +447,11 @@ export class BackendSocket {
return this.localClients.size > this.toolClients.size
}
+ /** True after a paired device has completed the E2EE hello/welcome session (the local dashboard's dot). */
+ deviceE2eeConnected(): boolean {
+ return [...this.remoteClients.values()].some((client) => client.role === 'device')
+ }
+
/** Live backend link state (local dashboard), as the gateway last said. */
isConnected(): boolean {
return this.linkUp
@@ -485,6 +491,7 @@ export class BackendSocket {
this.viewerForwarder.closeConnection(connId); this.interactiveViewers.closeConnection(connId); this.ownerCommands.closeConnection(connId)
},
disconnected: async (connId) => {
+ this.autonomousDeviceRelay?.drop(connId)
this.remoteClients.delete(connId)
this.viewerForwarder.closeConnection(connId)
this.interactiveViewers.closeConnection(connId); this.ownerCommands.closeConnection(connId)
@@ -534,7 +541,26 @@ export class BackendSocket {
},
revoked: () => this.onRevoked?.(),
busy: () => this.onBusy?.(),
+ device: async (connId, frame, opened) => { await this.autonomousDeviceRelay?.handle(connId, frame, opened) },
+ deviceRevoked: (identity) => this.autonomousDeviceRelay?.revoke(identity),
+ toWindows: (frame) => this.sendLocal(frame),
+ }
+
+ /** The Wi-Fi device's application protocol, beside the device service it answers for, over the
+ * gateway's sessions (lib/autonomous-device/overGateway.ts). */
+ private autonomousDeviceRelay?: DeviceRelayOverGateway
+ setAutonomousDeviceService(service: AutonomousDeviceService, onRemoteRevoke: (identity: string) => void): void {
+ this.autonomousDeviceRelay = deviceRelayOverGateway({
+ client: (connId) => this.remoteClients.get(connId),
+ send: (connId, type, payload) => { this.throughGateway('device', (gateway) => gateway.device(connId, type, payload), false) },
+ service, machineId: this.machineId, onReady: () => this.onCommanderJoin?.(), onRemoteRevoke,
+ onClient: (connId, identity) => this.gatewayPort?.deviceClient(connId, identity),
+ })
}
+ /** Wi-Fi device sessions on a direct link that said hello to the device service. */
+ directAutonomousDeviceSessions(): number { return this.autonomousDeviceRelay?.directSessions() ?? 0 }
+ autonomousDeviceConnected(): boolean { return this.autonomousDeviceRelay?.connected() ?? false }
+ emitAutonomousDeviceEvent(frame: AutonomousDeviceFrame, deviceId?: string): void { this.autonomousDeviceRelay?.emit(frame, deviceId) }
setTerminalStreamManager(manager: TerminalStreamManager): void {
this.terminalStreams = manager
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index fd0af4083..b328df1c9 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -40,3 +40,5 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
theirs. `teamsLink.ts`: every change to the teams' prompt scopes, kept until their process has it.
`monitorLink.ts`: the monitor's port, asked of its process. `storeLink.ts`: what the Store in its
process tells the core. `agentQueries.ts`: what a service in its own process may ask of the agents.
+ `gatewayLink.ts`: the relay and its E2EE in their own process (src/gateway/), as the core sees them:
+ the link's state and the remote clients it reads in line, the frames it hands over in the clear.
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 2c32ac278..c4d3e616f 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -381,11 +381,15 @@ export const FLEET_FALLBACKS: PortFallbacks<FleetPort> = {
/** What a remote client proved with its E2EE session: an owner's app or browser, or a device. */
export type RemoteRole = 'web' | 'device'
-/** A remote client the gateway holds a session with, as the core may know it: its role, and the label
- * its identity was paired under (null for none), for naming it to the person. */
+/** A remote client the gateway holds a session with, as the core may know it: its role, the label its
+ * identity was paired under (null for none) for naming it to the person, its identity's public key (the
+ * Wi-Fi device's requests are kept apart by it), and whether it is on a device's direct link rather than
+ * the relay. Nothing here is a secret. */
export interface RemoteClient {
role: RemoteRole
label: string | null
+ identity: string
+ direct: boolean
}
/** How a remote client's frame arrived: the backend's relay, or a paired client's own P2P channel. */
@@ -436,6 +440,12 @@ export interface GatewayPort {
/** A local connection's request the gateway answers (the E2EE pairings), answered back to it through
* `GatewayEvents.toLocal`. */
local(connId: string, frame: Record<string, unknown>): Promise<void>
+ /** The Wi-Fi device's answer or event for one of its sessions, sealed to it, over its direct link or the
+ * relay; false when that session is gone. */
+ device(connId: string, type: string, payload: Record<string, unknown>): boolean
+ /** Which identity's app said hello on a Wi-Fi device session (null: it left), so that the gateway can
+ * tell the device it was unpaired while its session still stands. */
+ deviceClient(connId: string, identity: string | null): void
stop(): Promise<void>
}
@@ -475,6 +485,102 @@ export interface GatewayEvents {
revoked(): void
/** Another computer holds this machine: stop for good, keeping the session. */
busy(): void
+ /** A Wi-Fi device's request (`autonomous_device_request`), as it arrived sealed and as the session that
+ * sealed it opened it (null when it could not be opened, or was not the device's to send). */
+ device(connId: string, frame: Record<string, unknown>, opened: Record<string, unknown> | null): Promise<void> | void
+ /** A paired identity was unpaired: the Wi-Fi device service forgets it. */
+ deviceRevoked(identity: string): void
+ /** Something the windows on this computer show of the account's devices (the device key log's notices). */
+ toWindows(frame: Record<string, unknown>): void
+}
+
+/** An HTTP answer for the daemon's own routes (`harness pair`, `harness devices`, …), as the hook server sends it. */
+export interface HttpAnswer {
+ status: number
+ body: Record<string, unknown>
+}
+
+/** What the core's status reads of the relay: the machine's E2EE fingerprint, its pairings and the one
+ * waiting to pair. */
+export interface GatewayStatus {
+ fingerprint: string | null
+ pairs: Array<Record<string, unknown>>
+ pending: Record<string, unknown> | null
+}
+
+/** The account's sign-in as the gateway's device key log reads it: no credential, only which sign-in. */
+export interface GatewayAccount {
+ /** The machine id the backend gave this sign-in; null signed out. */
+ machineId: string | null
+ /** Which sign-in by hand this is (lib/authSession.ts `signInOf`), or null. */
+ signIn: { epoch: string; adopted: boolean; at: number | null } | null
+}
+
+/** A Wi-Fi device operation refused, with the code the device's local API answers it under. */
+export interface GatewayRefusal {
+ code: string
+ message: string
+}
+
+/**
+ * The daemon's own commands about the keys, which the gateway holds: `harness pair`, `unpair`,
+ * `remote-password`, `link connect`, `group`, `devices`, and the Wi-Fi device's pairing. Each answers as
+ * the hook server's route does; while the gateway is down, a 503.
+ */
+export interface GatewayOps {
+ status(): Promise<GatewayStatus>
+ pair(code: string): Promise<HttpAnswer>
+ listPairs(): Promise<HttpAnswer>
+ revoke(id: string): Promise<HttpAnswer>
+ revokeAll(): Promise<HttpAnswer>
+ setRemotePassword(password: string): Promise<HttpAnswer>
+ clearRemotePassword(): Promise<HttpAnswer>
+ remotePasswordStatus(): Promise<HttpAnswer>
+ trustLinkedPeer(peer: { pub: string; machineId: string; label: string }): Promise<HttpAnswer>
+ groupList(): Promise<HttpAnswer>
+ groupSync(): Promise<HttpAnswer>
+ groupRemove(selector: string): Promise<HttpAnswer>
+ devicesList(): Promise<HttpAnswer>
+ devicesRemove(pub: string): Promise<HttpAnswer>
+ devicesHistory(): Promise<HttpAnswer>
+ devicesDismiss(body: { pub?: string; pubs?: string[]; baseline?: boolean }): Promise<HttpAnswer>
+ devicesRebaseline(confirm: boolean, head?: { seq: number; hash: string }): Promise<HttpAnswer>
+ /** The Wi-Fi device's direct links: discovered devices, pairing one, and its pairings. A refusal is an
+ * answer (`{ refused }`), as the device's local API words it. */
+ wifi(request: { op: 'discover' | 'pair' | 'pairStatus' | 'list' | 'revoke'; device?: string; code?: string; id?: string }):
+ Promise<{ result: Record<string, unknown> } | { refused: GatewayRefusal }>
+ /** The local dashboard's port, said to the web in `e2e_status` so it can link there to approve a pairing. */
+ dashboardPort(port: number): void
+ /** The Wi-Fi device service is up (its direct links start) or gone (they stop). */
+ wifiService(on: boolean): void
+ /** A Wi-Fi device asked to be unpaired, over its own authenticated session. */
+ revokeIdentity(identity: string): void
+ /** The account's sign-in, as it is now (after start-up recorded which sign-in it is); the device key log
+ * registers this machine with it. */
+ account(account: GatewayAccount): void
+ /** The owner's machines the backend last said were online, for the trust group's exchanges; null when
+ * the list is not the backend's. */
+ reachable(machineIds: string[] | null): void
+}
+
+/** A window on this computer working on another of the owner's machines, through the relay: what the
+ * local socket asks of the gateway for it (lib/remoteRelay.ts `RemoteRelayPool`, or its link). */
+export interface WindowRelaySession {
+ send(frame: Record<string, unknown>): Promise<void>
+ sendBinary(clear: TerminalBinaryClear): Promise<void>
+ detach(): void
+}
+export interface WindowRelaySink {
+ sendFrame(frame: Record<string, unknown>): boolean
+ sendBinary(frame: Uint8Array): boolean
+}
+export interface WindowRelay {
+ acquire(machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>, sink: WindowRelaySink,
+ onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
+ acquireIsolated(machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>, sink: WindowRelaySink,
+ onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
+ invalidate(machineId: string): void
+ invalidateIsolated(machineId: string): void
}
/** Each port is filled by the service that owns it when that service starts, and is null while the
diff --git a/cli/src/core/gatewayLink.spec.ts b/cli/src/core/gatewayLink.spec.ts
new file mode 100644
index 000000000..4b982a52b
--- /dev/null
+++ b/cli/src/core/gatewayLink.spec.ts
@@ -0,0 +1,362 @@
+import { describe, expect, it, vi } from 'vitest'
+import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { decodeTerminalLocal, encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from '../lib/terminalBinary.js'
+import type { GatewayEvents } from './api.js'
+import { createGatewayLink, GATEWAY_BUFFER_LIMIT, PAIR_WAIT_MS, WINDOW_GATEWAY_GONE } from './gatewayLink.js'
+
+const STREAM = '00000000-0000-4000-8000-000000000001'
+const bytesOf = (text: string): TerminalBinaryClear => ({ kind: TerminalBinaryKind.output, streamId: STREAM, seq: 1, compressed: false, bytes: new TextEncoder().encode(text) })
+
+function events(): { [K in keyof GatewayEvents]: ReturnType<typeof vi.fn> } {
+ return {
+ frame: vi.fn(), binary: vi.fn(), client: vi.fn(), disconnected: vi.fn(), observer: vi.fn(), toLocal: vi.fn(), status: vi.fn(),
+ linkDown: vi.fn(), commanders: vi.fn(), commanderJoined: vi.fn(), meta: vi.fn(), notice: vi.fn(), revoked: vi.fn(), busy: vi.fn(),
+ device: vi.fn(), deviceRevoked: vi.fn(), toWindows: vi.fn(),
+ }
+}
+
+function setup(over: { buffered?: number; call?: (type: string, payload: Record<string, unknown>, waitMs?: number) => Promise<Record<string, unknown>> } = {}) {
+ const heard = events()
+ const sent: Array<Record<string, unknown>> = []
+ const binary: Uint8Array[] = []
+ let buffered = over.buffered ?? 0
+ const log = vi.fn()
+ let clock = 1_000_000
+ const call = vi.fn(over.call ?? (async () => ({ status: 200, body: { ok: true } })))
+ const tokens = { accessToken: vi.fn(async () => 'token-1') }
+ const backend = vi.fn(async () => ({ status: 200, body: { data: { seen: {} } } }))
+ const link = createGatewayLink({
+ events: heard as unknown as GatewayEvents,
+ notify: (frame) => { sent.push(frame.payload as Record<string, unknown>); return true },
+ notifyBinary: (bytes) => { binary.push(bytes); return true },
+ buffered: () => buffered,
+ call,
+ start: () => ({ machineId: 'm1', computerId: 'c1', autonomousEnv: 'prod', signedIn: true }),
+ tokens, backend, log, now: () => clock,
+ })
+ return {
+ link, heard, sent, binary, call, tokens, backend, log,
+ kinds: () => sent.map((payload) => payload.kind),
+ setBuffered: (bytes: number) => { buffered = bytes },
+ tick: (ms: number) => { clock += ms },
+ }
+}
+
+/** A remote client the gateway has registered with the core. */
+const register = (link: ReturnType<typeof setup>['link'], connId: string, role: 'web' | 'device' = 'web') =>
+ link.notice({ kind: 'client', connId, client: { role, label: null, identity: 'PUB', direct: false } })
+
+describe('the gateway in its own process, as the core sees it', () => {
+ it('says nothing to a gateway that is not there, and tells one that connects everything it starts from', () => {
+ const { link, sent, kinds } = setup()
+ link.port.connect()
+ link.port.holdRequests()
+ link.port.localClients(2)
+ link.ops.dashboardPort(41000)
+ link.ops.wifiService(true)
+ link.ops.account({ machineId: 'm1', signIn: null })
+ link.ops.reachable(['m2'])
+ expect(sent).toEqual([])
+ link.connected()
+ expect(kinds()).toEqual(['start'])
+ expect(sent[0]).toEqual({
+ kind: 'start', machineId: 'm1', computerId: 'c1', autonomousEnv: 'prod', signedIn: true,
+ requestsOpen: false, dial: 'connect', localClients: 2, dashboardPort: 41000, wifiService: true, reachable: ['m2'],
+ })
+ link.port.openRequests()
+ link.port.serveThisComputerOnly()
+ expect(kinds().slice(1)).toEqual(['open', 'thisComputerOnly'])
+ })
+
+ it('carries the core\'s frames for remote clients, and refuses what it knows cannot reach one', async () => {
+ const { link, sent, binary, kinds } = setup()
+ link.connected()
+ // No backend link yet, and nobody registered: nothing for a remote client can go.
+ expect(link.port.connected()).toBe(false)
+ expect(link.port.target('phone-1', 'viewer_data', {})).toBe(false)
+ expect(link.port.terminal('phone-1', 'terminal_ready', {})).toBe(false)
+ expect(link.port.terminalBinary('phone-1', bytesOf('hi'))).toBe(false)
+ expect(link.port.observer('observer:1', 'observer_frame', {})).toBe(false)
+ expect(link.port.device('dial-1', 'autonomous_device_event', {})).toBe(false)
+ link.notice({ kind: 'status', connected: true })
+ register(link, 'phone-1')
+ expect(link.port.connected()).toBe(true)
+ link.port.broadcast({ type: 'turn_started' })
+ link.port.commander({ type: 'commander_event' })
+ link.port.user({ type: 'notification' })
+ link.port.reply('phone-1', 'agents_list', 'r-1', { agents: [] })
+ expect(link.port.target('phone-1', 'viewer_data', { a: 1 })).toBe(true)
+ expect(link.port.terminal('phone-1', 'terminal_ready', { streamId: STREAM })).toBe(true)
+ expect(link.port.observer('observer:1', 'observer_frame', { b: 2 })).toBe(true)
+ expect(link.port.device('phone-1', 'autonomous_device_result', { c: 3 })).toBe(true)
+ link.port.deviceClient('phone-1', 'PUB')
+ link.port.windowOpened()
+ await link.port.local('local:w', { type: 'e2ee_pairings_list', payload: {} })
+ expect(link.port.terminalBinary('phone-1', bytesOf('hi'))).toBe(true)
+ // An id the binary frame cannot carry: refused, never sent half-framed.
+ register(link, 'x'.repeat(300))
+ expect(link.port.terminalBinary('x'.repeat(300), bytesOf('hi'))).toBe(false)
+ expect(kinds().slice(1)).toEqual(['broadcast', 'commander', 'user', 'reply', 'target', 'terminal', 'observer', 'device', 'deviceClient', 'windowOpened', 'localFrame'])
+ expect(sent[4]).toEqual({ kind: 'reply', connId: 'phone-1', type: 'agents_list', requestId: 'r-1', payload: { agents: [] } })
+ const framed = decodeGatewayBinary(binary[0])!
+ expect(framed).toMatchObject({ kind: GatewayBinary.remote, id: 'phone-1' })
+ expect(decodeTerminalLocal(framed.bytes)).toEqual(bytesOf('hi'))
+ await link.stop()
+ expect(kinds().at(-1)).toBe('stop')
+ })
+
+ it('drops what would pile up on the socket to a gateway that reads nothing, and says so once a minute', () => {
+ const { link, kinds, setBuffered, log, tick } = setup()
+ link.connected()
+ register(link, 'phone-1')
+ setBuffered(GATEWAY_BUFFER_LIMIT + 1)
+ link.port.broadcast({ type: 'text_delta' })
+ link.port.commander({ type: 'commander_event' })
+ expect(link.port.terminalBinary('phone-1', bytesOf('hi'))).toBe(false)
+ expect(kinds()).toEqual(['start'])
+ expect(log).toHaveBeenCalledTimes(1)
+ tick(61_000)
+ link.port.broadcast({ type: 'text_delta' })
+ expect(log).toHaveBeenCalledTimes(2)
+ expect(log.mock.calls[1][0]).toContain('2 more since')
+ // What is not bulk (a reply) still goes: it is one frame, and the client is waiting for it.
+ link.port.reply('phone-1', 'agents_list', 'r', {})
+ expect(kinds()).toEqual(['start', 'reply'])
+ })
+
+ it('hands the core what the gateway tells it, read as data', () => {
+ const { link, heard } = setup()
+ link.connected()
+ link.notice({ kind: 'frame', connId: 'phone-1', frame: { type: 'message' }, transport: 'p2p', role: 'web' })
+ link.notice({ kind: 'frame', connId: 'dial-1', frame: 'not a frame', transport: 'relay', role: 'device' })
+ link.notice({ kind: 'client', connId: 'phone-1', client: null })
+ link.notice({ kind: 'disconnected', connId: 'phone-1' })
+ link.notice({ kind: 'observer', connId: 'observer:1', type: 'observer_hello', payload: { a: 1 } })
+ link.notice({ kind: 'toLocal', connId: 'local:w', frame: { type: 'x' } })
+ link.notice({ kind: 'status', connected: true })
+ link.notice({ kind: 'linkDown' })
+ link.notice({ kind: 'commanders', count: 2, active: 1, recheck: true })
+ link.notice({ kind: 'commanders', count: 'x', active: null })
+ link.notice({ kind: 'commanderJoined' })
+ link.notice({ kind: 'meta', meta: { name: 'Mac' } })
+ link.notice({ kind: 'notice', notice: { type: 'desk_changed', revision: 3 } })
+ link.notice({ kind: 'revoked' })
+ link.notice({ kind: 'busy' })
+ link.notice({ kind: 'device', connId: 'dial-1', frame: { type: 'autonomous_device_request' }, opened: { type: 'hello' } })
+ link.notice({ kind: 'device', connId: 'dial-1', frame: { type: 'autonomous_device_request' }, opened: null })
+ link.notice({ kind: 'deviceRevoked', identity: 'PUB' })
+ link.notice({ kind: 'toWindows', frame: { type: 'device_key_added' } })
+ link.notice({ kind: 'mystery' })
+ expect(heard.frame.mock.calls).toEqual([['phone-1', { type: 'message' }, 'p2p', 'web'], ['dial-1', {}, 'relay', 'device']])
+ expect(heard.client).toHaveBeenCalledWith('phone-1', null)
+ expect(heard.disconnected).toHaveBeenCalledWith('phone-1')
+ expect(heard.observer).toHaveBeenCalledWith('observer:1', 'observer_hello', { a: 1 })
+ expect(heard.toLocal).toHaveBeenCalledWith('local:w', { type: 'x' })
+ expect(heard.status).toHaveBeenCalledWith(true)
+ expect(heard.linkDown).toHaveBeenCalled()
+ expect(heard.commanders.mock.calls).toEqual([[2, 1, true], [0, null, false]])
+ expect(heard.commanderJoined).toHaveBeenCalled()
+ expect(heard.meta).toHaveBeenCalledWith({ name: 'Mac' })
+ expect(heard.notice).toHaveBeenCalledWith({ type: 'desk_changed', revision: 3 })
+ expect(heard.revoked).toHaveBeenCalled()
+ expect(heard.busy).toHaveBeenCalled()
+ expect(heard.device.mock.calls).toEqual([['dial-1', { type: 'autonomous_device_request' }, { type: 'hello' }], ['dial-1', { type: 'autonomous_device_request' }, null]])
+ expect(heard.deviceRevoked).toHaveBeenCalledWith('PUB')
+ expect(heard.toWindows).toHaveBeenCalledWith({ type: 'device_key_added' })
+ })
+
+ it('hands on a remote client\'s terminal bytes, and drops what it cannot read', () => {
+ const { link, heard } = setup()
+ const local = encodeTerminalLocal(bytesOf('ls\r'))!
+ link.binary(encodeGatewayBinary(GatewayBinary.remote, 'phone-1', local)!)
+ link.binary(encodeGatewayBinary(GatewayBinary.remote, 'phone-1', new Uint8Array([1, 2]))!)
+ link.binary(new Uint8Array([9, 9]))
+ expect(heard.binary.mock.calls).toEqual([['phone-1', bytesOf('ls\r')]])
+ })
+
+ it('a gateway that goes takes the relay with it: every remote client, the link and the devices watching', async () => {
+ const { link, heard } = setup()
+ link.connected()
+ link.notice({ kind: 'status', connected: true })
+ register(link, 'phone-1')
+ register(link, 'dial-1', 'device')
+ link.notice({ kind: 'disconnected', connId: 'dial-1' })
+ link.disconnected()
+ expect(heard.disconnected.mock.calls).toEqual([['dial-1'], ['phone-1']])
+ expect(heard.linkDown).toHaveBeenCalled()
+ expect(heard.commanders).toHaveBeenLastCalledWith(0, null)
+ expect(heard.status).toHaveBeenLastCalledWith(false)
+ expect(link.port.connected()).toBe(false)
+ // Gone while the link was down: nothing more to say about the link.
+ heard.status.mockClear()
+ link.connected()
+ link.disconnected()
+ expect(heard.status).not.toHaveBeenCalled()
+ })
+
+ it('a gateway that connects again without having been seen to go starts afresh, and the last one\'s clients go', () => {
+ const { link, heard, kinds } = setup()
+ link.connected()
+ register(link, 'phone-1')
+ link.connected()
+ expect(heard.disconnected).toHaveBeenCalledWith('phone-1')
+ expect(kinds()).toEqual(['start', 'start'])
+ expect(link.port.terminal('phone-1', 'terminal_ready', {})).toBe(false)
+ })
+
+ it('answers the daemon\'s own commands about the keys from the gateway, and 503 while it is down', async () => {
+ const answers: Record<string, Record<string, unknown>> = {
+ [GATEWAY_CALLS.pair]: { status: 200, body: { label: 'Phone' } },
+ [GATEWAY_CALLS.listPairs]: { error: 'SERVICE_UNAVAILABLE', service: 'gateway', retryable: true },
+ [GATEWAY_CALLS.devicesList]: { status: 200, body: 'not an object' },
+ }
+ const { link, call } = setup({ call: async (type) => answers[type] ?? { status: 204, body: { type } } })
+ expect(await link.ops.pair('ABCD')).toEqual({ status: 200, body: { label: 'Phone' } })
+ expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.pair, { code: 'ABCD' }, PAIR_WAIT_MS)
+ expect(await link.ops.listPairs()).toEqual({ status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } })
+ expect(await link.ops.devicesList()).toEqual({ status: 200, body: {} })
+ const each = [
+ link.ops.revoke('1'), link.ops.revokeAll(), link.ops.setRemotePassword('pw'), link.ops.clearRemotePassword(),
+ link.ops.remotePasswordStatus(), link.ops.trustLinkedPeer({ pub: 'P', machineId: 'm', label: 'l' }), link.ops.groupList(),
+ link.ops.groupSync(), link.ops.groupRemove('2'), link.ops.devicesRemove('P'), link.ops.devicesHistory(),
+ link.ops.devicesDismiss({ pub: 'P' }), link.ops.devicesRebaseline(true, { seq: 1, hash: 'h' }), link.ops.devicesRebaseline(false),
+ ]
+ expect((await Promise.all(each)).map((answer) => answer.status)).toEqual(Array(each.length).fill(204))
+ expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.devicesRebaseline, { confirm: true, head: { seq: 1, hash: 'h' } }, undefined)
+ expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.devicesRebaseline, { confirm: false }, undefined)
+ })
+
+ it('reads the gateway\'s status, with nothing to show while it is down', async () => {
+ const said = { fingerprint: 'AB12', pairs: [{ fingerprint: 'CD34' }], pending: { label: 'Phone' } }
+ let answer: Record<string, unknown> = said
+ const { link, call } = setup({ call: async () => answer })
+ expect(await link.ops.status()).toEqual(said)
+ expect(call).toHaveBeenCalledWith(GATEWAY_CALLS.status, {}, 2_000)
+ answer = { error: 'SERVICE_UNAVAILABLE' }
+ expect(await link.ops.status()).toEqual({ fingerprint: null, pairs: [], pending: null })
+ })
+
+ it('carries the Wi-Fi device\'s requests, a refusal as the device\'s local API words it', async () => {
+ let answer: Record<string, unknown> = { result: { devices: [] } }
+ const { link, call } = setup({ call: async () => answer })
+ expect(await link.ops.wifi({ op: 'list' })).toEqual({ result: { devices: [] } })
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.wifi, { op: 'list' }, undefined)
+ answer = { refused: { code: 'UNKNOWN_DEVICE', message: 'Device pairing not found' } }
+ expect(await link.ops.wifi({ op: 'pair', device: 'd', code: 'c' })).toEqual({ refused: { code: 'UNKNOWN_DEVICE', message: 'Device pairing not found' } })
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.wifi, { op: 'pair', device: 'd', code: 'c' }, PAIR_WAIT_MS)
+ answer = { refused: { code: 7 } }
+ expect((await link.ops.wifi({ op: 'discover' })) as { refused: { code: string } }).toMatchObject({ refused: { code: 'UNAVAILABLE' } })
+ answer = { error: 'SERVICE_UNAVAILABLE' }
+ expect(await link.ops.wifi({ op: 'revoke', id: 'x' })).toMatchObject({ refused: { code: 'UNAVAILABLE' } })
+ })
+
+ it('tells the gateway what the core learns for it', () => {
+ const { link, sent } = setup()
+ link.connected()
+ link.ops.revokeIdentity('PUB')
+ link.ops.reachable(null)
+ expect(sent.slice(1)).toEqual([{ kind: 'revokeIdentity', identity: 'PUB' }, { kind: 'reachable', machineIds: null }])
+ })
+
+ it('hands the gateway a token from the account, and the session\'s own refusal when there is none', async () => {
+ const { link, tokens, backend } = setup()
+ expect(await link.answer('access_token', { force: true, failedToken: 'old' })).toEqual({ token: 'token-1' })
+ expect(tokens.accessToken).toHaveBeenLastCalledWith({ force: true, failedToken: 'old' })
+ await link.answer('access_token', {})
+ expect(tokens.accessToken).toHaveBeenLastCalledWith({ force: false })
+ tokens.accessToken.mockRejectedValueOnce(Object.assign(new Error('refresh refused'), { code: 'INVALID_REFRESH' }))
+ expect(await link.answer('access_token', {})).toEqual({ code: 'INVALID_REFRESH', message: 'refresh refused' })
+ tokens.accessToken.mockRejectedValueOnce('down')
+ expect(await link.answer('access_token', {})).toEqual({ code: 'UNAVAILABLE', message: 'down' })
+ // The device key log's reads of the backend, and nothing else the core's session could reach.
+ expect(await link.answer('backend', { method: 'GET', path: '/api/device-keys?since=4' })).toEqual({ status: 200, body: { data: { seen: {} } } })
+ expect(backend).toHaveBeenCalledWith('GET', '/api/device-keys?since=4')
+ expect(await link.answer('backend', { method: 'GET', path: '/api/machines' })).toEqual({ error: 'UNKNOWN_QUERY' })
+ expect(await link.answer('backend', { method: 'POST', path: '/api/device-keys' })).toEqual({ error: 'UNKNOWN_QUERY' })
+ expect(await link.answer('agents', {})).toEqual({ error: 'UNKNOWN_QUERY' })
+ expect(backend).toHaveBeenCalledTimes(1)
+ })
+})
+
+describe('the link\'s defaults', () => {
+ it('logs on the console and stamps with the clock when not told otherwise', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ const link = createGatewayLink({
+ events: events() as unknown as GatewayEvents, notify: () => true, notifyBinary: () => true, buffered: () => GATEWAY_BUFFER_LIMIT + 1,
+ call: async () => ({}), start: () => ({}), tokens: { accessToken: async () => 't' }, backend: async () => ({ status: 200, body: {} }),
+ })
+ link.connected()
+ link.port.broadcast({ type: 'text_delta' })
+ link.notice({ kind: 'mystery' })
+ expect(warn).toHaveBeenCalledTimes(2)
+ warn.mockRestore()
+ })
+})
+
+describe('a window here working on another machine, through the gateway', () => {
+ const select = { type: 'machine_select', payload: { machineId: 'm2' } }
+ const sink = () => ({ sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) })
+
+ it('opens when the gateway says it did, and carries its frames and bytes both ways', async () => {
+ const { link, sent, binary, kinds } = setup()
+ link.connected()
+ const window = sink()
+ const onClosed = vi.fn()
+ const opening = link.windowRelay.acquire('m2', 'prod', select, window, onClosed)
+ expect(sent.at(-1)).toEqual({ kind: 'windowOpen', id: 'window-1', machineId: 'm2', autonomousEnv: 'prod', frame: select, isolated: false })
+ link.notice({ kind: 'windowOpened', id: 'window-1' })
+ link.notice({ kind: 'windowOpened', id: 'window-1' })
+ const session = await opening
+ await session.send({ type: 'agents_list' })
+ await session.sendBinary(bytesOf('ls\r'))
+ expect(sent.at(-1)).toEqual({ kind: 'windowSend', id: 'window-1', frame: { type: 'agents_list' } })
+ expect(decodeGatewayBinary(binary[0])).toMatchObject({ kind: GatewayBinary.window, id: 'window-1' })
+ link.notice({ kind: 'windowFrame', id: 'window-1', frame: { type: 'agents_list_result' } })
+ link.notice({ kind: 'windowFrame', id: 'window-9', frame: { type: 'stray' } })
+ link.binary(encodeGatewayBinary(GatewayBinary.window, 'window-1', new Uint8Array([7, 7]))!)
+ expect(window.sendFrame).toHaveBeenCalledWith({ type: 'agents_list_result' })
+ expect(window.sendBinary).toHaveBeenCalledWith(new Uint8Array([7, 7]))
+ link.notice({ kind: 'windowClosed', id: 'window-1', code: 4404, reason: 'NO_PEER_LINK' })
+ expect(onClosed).toHaveBeenCalledWith(4404, 'NO_PEER_LINK')
+ // Said twice, or of a window it never had: nothing more.
+ link.notice({ kind: 'windowClosed', id: 'window-1', code: 4404, reason: 'NO_PEER_LINK' })
+ expect(onClosed).toHaveBeenCalledOnce()
+ session.detach()
+ expect(kinds()).not.toContain('windowDetach')
+ link.windowRelay.invalidate('m2')
+ link.windowRelay.invalidateIsolated('m2')
+ expect(sent.slice(-2)).toEqual([{ kind: 'windowInvalidate', machineId: 'm2', isolated: false }, { kind: 'windowInvalidate', machineId: 'm2', isolated: true }])
+ })
+
+ it('a window that leaves says so; one the gateway could not open fails as the pool failed it', async () => {
+ const { link, kinds } = setup()
+ link.connected()
+ const opening = link.windowRelay.acquireIsolated('m2', 'prod', select, sink(), vi.fn())
+ link.notice({ kind: 'windowOpened', id: 'window-1' })
+ ;(await opening).detach()
+ expect(kinds().at(-1)).toBe('windowDetach')
+ const failing = link.windowRelay.acquire('m2', 'prod', select, sink(), vi.fn())
+ link.notice({ kind: 'windowFailed', id: 'window-2', reason: 'NO_PEER_LINK' })
+ await expect(failing).rejects.toEqual(new RelayConnectError('NO_PEER_LINK', 1011))
+ const refused = link.windowRelay.acquire('m2', 'prod', select, sink(), vi.fn())
+ link.notice({ kind: 'windowFailed', id: 'window-3', code: 4403 })
+ await expect(refused).rejects.toMatchObject({ closeCode: 4403, message: 'relay failed' })
+ })
+
+ it('the gateway gone: a window waiting to open and one open are both told to try again', async () => {
+ const { link } = setup()
+ await expect(link.windowRelay.acquire('m2', 'prod', select, sink(), vi.fn())).rejects.toMatchObject({ closeCode: WINDOW_GATEWAY_GONE })
+ link.connected()
+ const onClosed = vi.fn()
+ const open = link.windowRelay.acquire('m2', 'prod', select, sink(), onClosed)
+ link.notice({ kind: 'windowOpened', id: 'window-1' })
+ const session = await open
+ const waiting = link.windowRelay.acquire('m3', 'prod', select, sink(), vi.fn())
+ link.disconnected()
+ expect(onClosed).toHaveBeenCalledWith(WINDOW_GATEWAY_GONE, 'the relay restarted')
+ await expect(waiting).rejects.toMatchObject({ closeCode: WINDOW_GATEWAY_GONE })
+ // Its bytes go nowhere now: the gateway is not there to take them.
+ await session.sendBinary(bytesOf('x'))
+ })
+})
diff --git a/cli/src/core/gatewayLink.ts b/cli/src/core/gatewayLink.ts
new file mode 100644
index 000000000..2b71d62d8
--- /dev/null
+++ b/cli/src/core/gatewayLink.ts
@@ -0,0 +1,356 @@
+/**
+ * The gateway in its own process, as the core sees it (docs/design/2026-10-06-core-boundary-next.md, step
+ * 10, R2; the process's side is gateway/gatewayProcess.ts). The relay, the E2EE sessions and every key
+ * live there; the core keeps what it must read in line, as the gateway last said it, and sends what it has
+ * for remote clients in the clear, over the service link only the master's token opens.
+ *
+ * - What the core reads synchronously is kept here from the gateway's notices: whether the backend link
+ * is up, and the remote clients it holds a session with (the socket keeps their roles and labels).
+ * - What the core has for a remote client goes to the gateway as it is, never held: a frame the gateway
+ * is not there to seal is a frame no remote client could have got. While the gateway reads nothing
+ * (hung), what would pile up on the socket to it is dropped at GATEWAY_BUFFER_LIMIT and said once a
+ * minute; the master kills a hung gateway soon after.
+ * - The gateway gone (crashed, killed, restarting) is the relay gone: every remote client with it, the
+ * link down, no device watching. A window working on another machine through it is closed, and opens
+ * again on its own. The windows on this computer and the agents never notice.
+ * - Each time the gateway connects it is told everything it starts from (`start`): it builds its relay
+ * afresh, as a core's restart did when the relay ran in the core.
+ */
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
+import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
+import type {
+ BackendNotice, GatewayEvents, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer,
+ RemoteClient, RemoteRole, RemoteTransport, WindowRelay, WindowRelaySession, WindowRelaySink,
+} from './api.js'
+import type { ServiceFrame } from './serviceLinks.js'
+
+export interface GatewayLinkDeps {
+ /** The core's side of what the gateway tells it (BackendSocket's `fromGateway`). */
+ events: GatewayEvents
+ /** The service link to the gateway (core/serviceLinks.ts, for `gateway`). */
+ notify(frame: ServiceFrame): boolean
+ notifyBinary(bytes: Uint8Array): boolean
+ buffered(): number
+ call(type: string, payload: Record<string, unknown>, waitMs?: number): Promise<Record<string, unknown>>
+ /** What the gateway starts from each time it connects: this machine's ids, whether it is signed in. */
+ start(): Record<string, unknown>
+ /** The account's tokens (`core.account`): the gateway asks for one each time it dials, and holds none. */
+ tokens: { accessToken(opts?: { force?: boolean; failedToken?: string }): Promise<string> }
+ /** A read of the backend's REST API under the account's session (the core's proxy). */
+ backend(method: 'GET', path: string): Promise<HttpAnswer>
+ newId?: () => string
+ now?: () => number
+ log?: (line: string) => void
+}
+
+/** Bytes waiting on the socket to the gateway past which a frame for remote clients is dropped. A hung
+ * gateway reads nothing for up to its heartbeat deadline (30 s); every event and terminal byte for
+ * remote clients would wait in the core's memory meanwhile. */
+export const GATEWAY_BUFFER_LIMIT = 16 * 1024 * 1024
+
+/** How long a pairing may take: the code is typed on one screen and checked over the relay, round by round. */
+export const PAIR_WAIT_MS = 120_000
+
+/** The close a window on another machine gets when the gateway it went through is gone: try again shortly. */
+export const WINDOW_GATEWAY_GONE = 1013
+
+const UNAVAILABLE: HttpAnswer = { status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } }
+
+interface Window {
+ sink: WindowRelaySink
+ onClosed: (code: number, reason: string) => void
+ opening: { resolve: (session: WindowRelaySession) => void; reject: (error: Error) => void } | null
+}
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : '')
+const record = (value: unknown): Record<string, unknown> =>
+ (value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {})
+
+export function createGatewayLink(deps: GatewayLinkDeps) {
+ const { events } = deps
+ const log = deps.log ?? ((line: string) => console.warn(line))
+ const now = deps.now ?? Date.now
+ let counter = 0
+ const newId = deps.newId ?? (() => `window-${++counter}`)
+ /** The gateway's process is connected to this core. */
+ let up = false
+ /** The backend link, as the gateway last said. */
+ let linkUp = false
+ // What the gateway is told again whenever it connects.
+ let requestsOpen = true
+ let dial: 'connect' | 'local' | null = null
+ let localClients = 0
+ let dashboardPort: number | null = null
+ let wifiService = false
+ let reachable: string[] | null = null
+ /** The remote clients the gateway registered, to forget each when it goes. */
+ const clients = new Set<string>()
+ const windows = new Map<string, Window>()
+ let droppedSaidAt = -Infinity
+ let droppedUnsaid = 0
+
+ const send = (kind: string, payload: Record<string, unknown> = {}): boolean =>
+ up && deps.notify({ type: 'service_event', payload: { ...payload, kind } })
+ /** A frame for remote clients: dropped rather than held while the gateway reads nothing. */
+ const fits = (): boolean => {
+ if (deps.buffered() <= GATEWAY_BUFFER_LIMIT) return true
+ const at = now()
+ if (at - droppedSaidAt < 60_000) droppedUnsaid++
+ else {
+ log(`[gateway] it is not reading: frames for remote clients dropped${droppedUnsaid ? ` · ${droppedUnsaid} more since` : ''}`)
+ droppedSaidAt = at
+ droppedUnsaid = 0
+ }
+ return false
+ }
+ const bulk = (kind: string, payload: Record<string, unknown>): boolean => up && fits() && send(kind, payload)
+ const reachableClient = (connId: string): boolean => up && clients.has(connId)
+
+ const port: GatewayPort = {
+ connect: () => { dial = 'connect'; send('connect') },
+ serveThisComputerOnly: () => { dial = 'local'; send('thisComputerOnly') },
+ holdRequests: () => { requestsOpen = false; send('hold') },
+ openRequests: () => { requestsOpen = true; send('open') },
+ connected: () => up && linkUp,
+ broadcast: (frame) => { bulk('broadcast', { frame }) },
+ commander: (frame) => { bulk('commander', { frame }) },
+ user: (frame) => { send('user', { frame }) },
+ reply: (connId, type, requestId, payload) => { send('reply', { connId, type, requestId, payload }) },
+ target: (connId, type, payload) => up && linkUp && clients.has(connId) && bulk('target', { connId, type, payload }),
+ terminal: (connId, type, payload) => reachableClient(connId) && bulk('terminal', { connId, type, payload }),
+ terminalBinary: (connId, clear) => {
+ if (!reachableClient(connId) || !fits()) return false
+ const local = encodeTerminalLocal(clear)
+ const bytes = local && encodeGatewayBinary(GatewayBinary.remote, connId, local)
+ return !!bytes && deps.notifyBinary(bytes)
+ },
+ observer: (connId, type, payload) => up && linkUp && send('observer', { connId, type, payload }),
+ windowOpened: () => { send('windowOpened') },
+ localClients: (count) => { localClients = count; send('localClients', { count }) },
+ local: async (connId, frame) => { send('localFrame', { connId, frame }) },
+ device: (connId, type, payload) => reachableClient(connId) && send('device', { connId, type, payload }),
+ deviceClient: (connId, identity) => { send('deviceClient', { connId, identity }) },
+ stop: async () => { send('stop') },
+ }
+
+ const http = async (type: string, payload: Record<string, unknown> = {}, waitMs?: number): Promise<HttpAnswer> => {
+ const answer = await deps.call(type, payload, waitMs)
+ return typeof answer.status === 'number' ? { status: answer.status, body: record(answer.body) } : UNAVAILABLE
+ }
+
+ const ops: GatewayOps = {
+ status: async (): Promise<GatewayStatus> => {
+ const answer = await deps.call(GATEWAY_CALLS.status, {}, 2_000)
+ return {
+ fingerprint: typeof answer.fingerprint === 'string' ? answer.fingerprint : null,
+ pairs: Array.isArray(answer.pairs) ? answer.pairs as Array<Record<string, unknown>> : [],
+ pending: answer.pending && typeof answer.pending === 'object' ? answer.pending as Record<string, unknown> : null,
+ }
+ },
+ pair: (code) => http(GATEWAY_CALLS.pair, { code }, PAIR_WAIT_MS),
+ listPairs: () => http(GATEWAY_CALLS.listPairs),
+ revoke: (id) => http(GATEWAY_CALLS.revoke, { id }),
+ revokeAll: () => http(GATEWAY_CALLS.revokeAll),
+ setRemotePassword: (password) => http(GATEWAY_CALLS.setRemotePassword, { password }),
+ clearRemotePassword: () => http(GATEWAY_CALLS.clearRemotePassword),
+ remotePasswordStatus: () => http(GATEWAY_CALLS.remotePasswordStatus),
+ trustLinkedPeer: (peer) => http(GATEWAY_CALLS.trustLinkedPeer, { peer }),
+ groupList: () => http(GATEWAY_CALLS.groupList),
+ groupSync: () => http(GATEWAY_CALLS.groupSync),
+ groupRemove: (selector) => http(GATEWAY_CALLS.groupRemove, { selector }),
+ devicesList: () => http(GATEWAY_CALLS.devicesList),
+ devicesRemove: (pub) => http(GATEWAY_CALLS.devicesRemove, { pub }),
+ devicesHistory: () => http(GATEWAY_CALLS.devicesHistory),
+ devicesDismiss: (body) => http(GATEWAY_CALLS.devicesDismiss, { body }),
+ devicesRebaseline: (confirm, head) => http(GATEWAY_CALLS.devicesRebaseline, { confirm, ...(head ? { head } : {}) }),
+ wifi: async (request) => {
+ const answer = await deps.call(GATEWAY_CALLS.wifi, request, request.op === 'pair' ? PAIR_WAIT_MS : undefined)
+ if (answer.result && typeof answer.result === 'object') return { result: answer.result as Record<string, unknown> }
+ const refused = record(answer.refused)
+ const why: GatewayRefusal = typeof refused.code === 'string'
+ ? { code: refused.code, message: text(refused.message) }
+ : { code: 'UNAVAILABLE', message: 'The Wi-Fi device link is not reachable on this computer right now. Try again.' }
+ return { refused: why }
+ },
+ dashboardPort: (port) => { dashboardPort = port; send('dashboardPort', { port }) },
+ wifiService: (on) => { wifiService = on; send('wifiService', { on }) },
+ revokeIdentity: (identity) => { send('revokeIdentity', { identity }) },
+ account: (next) => { send('account', { account: next }) },
+ reachable: (machineIds) => { reachable = machineIds; send('reachable', { machineIds }) },
+ }
+
+ const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
+ sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
+ new Promise((resolve, reject) => {
+ if (!up) { reject(new RelayConnectError('the relay is restarting', WINDOW_GATEWAY_GONE)); return }
+ const id = newId()
+ windows.set(id, { sink, onClosed, opening: { resolve, reject } })
+ send('windowOpen', { id, machineId, autonomousEnv, frame: selectFrame, isolated })
+ })
+ const sessionOf = (id: string): WindowRelaySession => ({
+ send: async (frame) => { send('windowSend', { id, frame }) },
+ sendBinary: async (clear) => {
+ const local = encodeTerminalLocal(clear)
+ const bytes = local && encodeGatewayBinary(GatewayBinary.window, id, local)
+ if (bytes && up) deps.notifyBinary(bytes)
+ },
+ detach: () => { if (windows.delete(id)) send('windowDetach', { id }) },
+ })
+ const windowRelay: WindowRelay = {
+ acquire: open(false),
+ acquireIsolated: open(true),
+ invalidate: (machineId) => { send('windowInvalidate', { machineId, isolated: false }) },
+ invalidateIsolated: (machineId) => { send('windowInvalidate', { machineId, isolated: true }) },
+ }
+
+ /** A window's connection ended, from the gateway's side or because the gateway went. */
+ const closeWindow = (id: string, code: number, reason: string): void => {
+ const window = windows.get(id)
+ if (!window) return
+ windows.delete(id)
+ if (window.opening) window.opening.reject(new RelayConnectError(reason, code))
+ else window.onClosed(code, reason)
+ }
+
+ /** What the gateway tells the core (`service_notice`): trusted as the gateway's, the master's token
+ * having opened the link, but read as data, never thrown on. */
+ const notice = (payload: Record<string, unknown>): void => {
+ const connId = text(payload.connId)
+ switch (payload.kind) {
+ case 'frame':
+ void events.frame(connId, record(payload.frame), payload.transport === 'p2p' ? 'p2p' : 'relay' as RemoteTransport,
+ payload.role === 'web' ? 'web' : 'device' as RemoteRole)
+ return
+ case 'client': {
+ const client = payload.client ? record(payload.client) as unknown as RemoteClient : null
+ if (client) clients.add(connId)
+ else clients.delete(connId)
+ events.client(connId, client)
+ return
+ }
+ case 'disconnected':
+ clients.delete(connId)
+ void events.disconnected(connId)
+ return
+ case 'observer':
+ void events.observer(connId, text(payload.type), record(payload.payload))
+ return
+ case 'toLocal':
+ events.toLocal(connId, record(payload.frame))
+ return
+ case 'status':
+ linkUp = payload.connected === true
+ events.status(linkUp)
+ return
+ case 'linkDown':
+ events.linkDown()
+ return
+ case 'commanders':
+ events.commanders(Number(payload.count) || 0, typeof payload.active === 'number' ? payload.active : null, payload.recheck === true)
+ return
+ case 'commanderJoined':
+ events.commanderJoined()
+ return
+ case 'meta':
+ events.meta(record(payload.meta) as { name?: string | null; gridName?: string | null })
+ return
+ case 'notice':
+ events.notice(record(payload.notice) as unknown as BackendNotice)
+ return
+ case 'revoked':
+ events.revoked()
+ return
+ case 'busy':
+ events.busy()
+ return
+ case 'device':
+ void events.device(connId, record(payload.frame), payload.opened ? record(payload.opened) : null)
+ return
+ case 'deviceRevoked':
+ events.deviceRevoked(text(payload.identity))
+ return
+ case 'toWindows':
+ events.toWindows(record(payload.frame))
+ return
+ case 'windowOpened': {
+ const window = windows.get(text(payload.id))
+ if (!window?.opening) return
+ const { resolve } = window.opening
+ window.opening = null
+ resolve(sessionOf(text(payload.id)))
+ return
+ }
+ case 'windowFailed':
+ case 'windowClosed':
+ closeWindow(text(payload.id), typeof payload.code === 'number' ? payload.code : 1011, text(payload.reason) || 'relay failed')
+ return
+ case 'windowFrame':
+ windows.get(text(payload.id))?.sink.sendFrame(record(payload.frame))
+ return
+ default:
+ log(`[gateway] an unknown notice from the gateway was ignored: ${JSON.stringify(String(payload.kind)).slice(0, 80)}`)
+ }
+ }
+
+ const binary = (raw: Uint8Array): void => {
+ const decoded = decodeGatewayBinary(raw)
+ if (!decoded) return
+ if (decoded.kind === GatewayBinary.window) { windows.get(decoded.id)?.sink.sendBinary(decoded.bytes); return }
+ const clear = decodeTerminalLocal(decoded.bytes)
+ if (clear) void events.binary(decoded.id, clear)
+ }
+
+ /**
+ * What the gateway asks the core (`service_query`): a token to dial with, and the device key log's reads
+ * of the backend. Nothing else: the gateway is the relay, and the core's own REST reads are not its to
+ * make. A refused token comes back as the session's own error, so the gateway can tell a session that
+ * is over (stop for good) from one that could not be refreshed just now (try again).
+ */
+ const answer = async (query: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> => {
+ if (query === 'access_token') {
+ try {
+ return { token: await deps.tokens.accessToken({ force: payload.force === true, ...(typeof payload.failedToken === 'string' ? { failedToken: payload.failedToken } : {}) }) }
+ } catch (error) {
+ return { code: text((error as { code?: unknown }).code) || 'UNAVAILABLE', message: error instanceof Error ? error.message : String(error) }
+ }
+ }
+ if (query === 'backend' && payload.method === 'GET' && text(payload.path).startsWith('/api/device-keys')) {
+ return { ...await deps.backend('GET', text(payload.path)) }
+ }
+ return { error: 'UNKNOWN_QUERY' }
+ }
+
+ return {
+ port,
+ ops,
+ windowRelay,
+ notice,
+ binary,
+ answer,
+ /** The core is stopping: the gateway closes its link to the backend (its process is the master's to end). */
+ stop: (): Promise<void> => port.stop(),
+ /** The gateway's process connected: it starts from everything it is told here, each time. */
+ connected(): void {
+ // A gateway that connects again without the core having seen it go (its link replaced) started afresh
+ // all the same: what the core kept of the last one goes first.
+ if (up) this.disconnected()
+ up = true
+ // The account as the core reads it now (`start`), which is never older than the last one it said.
+ send('start', { requestsOpen, dial, localClients, dashboardPort, wifiService, reachable, ...deps.start() })
+ },
+ /** The gateway's process went: the relay with it, as far as everything in the core is concerned. */
+ disconnected(): void {
+ up = false
+ for (const id of [...windows.keys()]) closeWindow(id, WINDOW_GATEWAY_GONE, 'the relay restarted')
+ // Each remote client's connection ended with it: what it had open here goes (its terminals, its
+ // viewers, the Wi-Fi device service's hold on it).
+ for (const connId of [...clients]) { clients.delete(connId); void events.disconnected(connId) }
+ events.linkDown()
+ events.commanders(0, null)
+ if (linkUp) { linkUp = false; events.status(false) }
+ },
+ }
+}
+
+export type GatewayLink = ReturnType<typeof createGatewayLink>
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 2179b3bf9..d5a1bc34a 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -15,10 +15,8 @@ import { HarnessGrantStore } from '../sharing/grants.js'
import { HarnessCollaborationStore } from '../sharing/collaboration.js'
import { HarnessShareRelay, type SharedMachineReference } from '../sharing/relay.js'
import { SharedViewerPool } from '../sharing/viewer.js'
-import { fingerprint as e2eeCoreFingerprint, b64d as e2eeCoreDecode } from '../lib/e2ee/core.js'
-import { AutonomousDeviceDirect } from '../lib/autonomous-device/direct.js'
import { runningDevicePart, startDevicePart } from '../lib/autonomous-device/parts.js'
-import { readFileSync, writeFileSync, openSync, existsSync, rmSync, statSync, renameSync } from 'fs'
+import { readFileSync, writeFileSync, openSync, existsSync, rmSync, statSync } from 'fs'
import { join } from 'path'
import { spawn } from 'child_process'
import { createServer, type Server } from 'http'
@@ -131,10 +129,10 @@ import { createAgentUpdate } from './agents/update.js'
import { createEngineHooks, installEngineHooks } from './engines/hooks.js'
import { createCursorTaskHooks } from './engines/cursorTasks.js'
import { databaseHistory } from './transcripts/databaseHistory.js'
-import { createCoreApi, emptyPorts, FLEET_FALLBACKS, MODELS_FALLBACKS, MODELS_REQUESTS, MONITOR_FALLBACKS, MONITOR_OFF, MONITOR_REQUESTS, PROJECTS_REQUESTS, SEARCH_FALLBACKS, SEARCH_REQUESTS, STORE_REQUESTS, TEAMS_FALLBACKS, USAGE_REQUESTS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type TeamsPort } from './api.js'
+import { createCoreApi, emptyPorts, FLEET_FALLBACKS, MODELS_FALLBACKS, MODELS_REQUESTS, MONITOR_FALLBACKS, MONITOR_OFF, MONITOR_REQUESTS, PROJECTS_REQUESTS, SEARCH_FALLBACKS, SEARCH_REQUESTS, STORE_REQUESTS, TEAMS_FALLBACKS, USAGE_REQUESTS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type GatewayAccount, type GatewayOps, type GatewayStatus, type TeamsPort } from './api.js'
import { createServiceHost, testFaults } from './serviceHost.js'
import { startStalls } from './stall.js'
-import { createServiceLinks } from './serviceLinks.js'
+import { createServiceLinks, type ServiceLinks } from './serviceLinks.js'
import { createViewersLink } from './viewersLink.js'
import { createWorkspacesLink } from './workspacesLink.js'
import { createMonitorLink } from './monitorLink.js'
@@ -149,7 +147,7 @@ import { localSocketPath, refuseServedDataFolder, type LocalSocketServer } from
import { saveDaemonPort } from '../lib/daemonEndpoint.js'
import { commandBarService } from '../lib/commandBar.js'
import { BackendSocket, isLocalClientId } from '../backendSocket.js'
-import { RelayGateway } from '../gateway/gateway.js'
+import { createGatewayLink } from './gatewayLink.js'
import { AutonomousDeviceService } from '../lib/autonomous-device/service.js'
import { autonomousDeviceLocalRequest } from '../lib/autonomous-device/localApi.js'
import { attachLocalWsServer, LOCAL_WS_PATH, LOCAL_WS_PROTOCOL_VERSION } from '../localWsServer.js'
@@ -157,18 +155,11 @@ import { createWindowRouter } from '../cable/windowRoute.js'
import { WindowSelection } from '../cable/windowSelection.js'
import { WindowVisit } from '../cable/windowVisit.js'
import { WindowForm } from '../cable/windowForm.js'
-import { RemoteRelayPool } from '../lib/remoteRelay.js'
import { TERMINAL_BINARY_VERSION } from '../lib/terminalBinary.js'
import { TeamError } from '../teams/model.js'
import { setVoiceRouterDeviceConnected, setVoiceRouterSessions, shutdownVoiceRouter } from '../lib/voiceRouter.js'
import { E2eeStore } from '../lib/e2ee/store.js'
import { isLoopbackRequest, loopbackHosts } from '../lib/loopbackRequest.js'
-import { b64e } from '../lib/e2ee/core.js'
-import { MachinePeerStore } from '../lib/e2ee/machinePeers.js'
-import { GroupSyncer, relayRequester, SELF_STAMP } from '../lib/e2ee/groupSyncer.js'
-import { DeviceLogSyncer, type DeviceLogFetched } from '../lib/e2ee/deviceLogSyncer.js'
-import { DeviceLogStore } from '../lib/e2ee/deviceLogStore.js'
-import { TrustGroupStore, type GroupMember } from '../lib/e2ee/trustGroup.js'
import { startSelfUpdater, restore as restoreUpdate, confirm as confirmUpdate, DOWNLOAD_LIMITS, type Poller } from '../lib/selfUpdate.js'
import { managedNodePath } from '../lib/nodeRuntime.js'
import { startTuiUpdater } from '../tui/update.js'
@@ -770,7 +761,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
}
}
}
- let autonomousDeviceDirect: AutonomousDeviceDirect | undefined
let deviceStoreRef: ReturnType<typeof createDeviceStore> | undefined
let autonomousDeviceService: AutonomousDeviceService | undefined
let devicePartsBuilt = false
@@ -786,17 +776,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// not. Both are just "the id this daemon serves under" to everything downstream — the local
// websocket binds clients to it, the app selects by it — and the backend binds a machine to the
// computer id at login, so a sign-in ADOPTS this machine rather than minting a second one.
- // The trust group (lib/e2ee/groupSyncer.ts). Built once the relay pool exists, far below; the hook
- // handlers and the backend callbacks declared before then reach it through this.
- let groupSyncer: GroupSyncer | null = null
- // The account's device key log (lib/e2ee/deviceLogSyncer.ts): signing in is what makes this machine's
- // devices trust it, and it them. Built beside the trust group, which it feeds.
- let devLogSyncer: DeviceLogSyncer | null = null
- /** The identity this machine was removed under is never used again: the next start mints a new one. */
- const spendIdentity = (): void => {
- const identityFile = join(env.ADAPTER_DATA_DIR, 'e2e', 'identity.json')
- try { renameSync(identityFile, `${identityFile}.removed-${Date.now()}`) } catch { /* already gone */ }
- }
const autonomousEnv = session?.autonomousEnv ?? env.AUTONOMOUS_ENV
const backend = new BackendSocket(session?.machineId ?? computerId(), (connected) => {
if (!connected) return
@@ -809,11 +788,34 @@ async function runForeground(session: AuthSession | null): Promise<void> {
backendRef = backend
// Nothing is answered until start-up is done (see the end of this function).
backend.holdRequests()
- // The relay and its E2EE (gateway/gateway.ts): the backend link, the sessions and the keys, which every
- // remote client's frames go through, held at the same gate. The socket hears it through `fromGateway`
- // and speaks to it in the clear; it holds no key of its own.
- const gateway = new RelayGateway({ machineId: backend.machineId, auth, computerId: computerId(), autonomousEnv, core: backend.fromGateway })
- backend.useGateway(gateway)
+ // The services harnessd's master runs in their own processes (harnessd/services.ts, `HARNESSD_SERVICES`):
+ // only under a master, which is what gives this core the token they connect with. Their requests are
+ // routed to them, and answered SERVICE_UNAVAILABLE while they are down (core/serviceLinks.ts).
+ const serviceToken = process.env.HARNESSD_SUPERVISED === '1' ? process.env.HARNESSD_SERVICE_TOKEN : undefined
+ const outOfProcess = servicesTheMasterRuns(process.env, KNOWN_SERVICES)
+ // The services' own code, for those that run in this process (services/inline.ts): loaded only then, so
+ // one in its own process, as each is by default, is never loaded here.
+ const inline = KNOWN_SERVICES.some((name) => !outOfProcess.has(name)) ? await import('../services/inline.js') : null
+ // The relay and its E2EE (gateway/): the backend link, the sessions and the keys, which every remote
+ // client's frames go through, held at the same gate. In its own process by default (core/gatewayLink.ts),
+ // or here (gateway/start.ts); the socket hears it through `fromGateway` and speaks to it in the clear.
+ const account = (): GatewayAccount => ({ machineId: readAuthSession()?.machineId ?? null, signIn: signInOf(readAuthSession()?.signInEpoch) })
+ let serviceLinksRef: ServiceLinks | null = null
+ const gatewayLink = outOfProcess.has('gateway') ? createGatewayLink({
+ events: backend.fromGateway,
+ notify: (frame) => serviceLinksRef?.notify('gateway', frame) ?? false,
+ notifyBinary: (bytes) => serviceLinksRef?.notifyBinary('gateway', bytes) ?? false,
+ buffered: () => serviceLinksRef?.buffered('gateway') ?? 0,
+ call: (type, payload, waitMs) => serviceLinksRef?.call('gateway', type, payload, waitMs) ?? Promise.resolve({ error: 'SERVICE_UNAVAILABLE' }),
+ start: () => ({ machineId: backend.machineId, computerId: computerId(), autonomousEnv, signedIn: !!session?.machineId, account: account() }),
+ tokens: auth, backend: (method, path) => proxyBackend(method, path),
+ }) : null
+ const gateway = gatewayLink ?? inline!.startGateway({
+ events: backend.fromGateway, machineId: backend.machineId, computerId: computerId(), autonomousEnv,
+ signedIn: !!session?.machineId, tokens: auth, backend: (method, path) => proxyBackend(method, path), account: account(),
+ })
+ backend.useGateway(gateway.port)
+ const gatewayOps = gateway.ops
daemonBoot.openRequests = () => backend.openRequests()
const teams: TeamsPort = {
prepare: (...args) => ports.teams?.prepare(...args) ?? (() => {}),
@@ -874,7 +876,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
appWindowForeground && openPaneAgents.has(agentId)
const cableWatchingLocal = (): boolean => cableRef?.isConnected === true
- const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal() || gateway.autonomousDeviceConnected()
+ const deviceIsWatching = (): boolean => backend.hasCommander() || cableWatchingLocal() || backend.autonomousDeviceConnected()
/** Anyone who can DRAW a question: a device, a cabled dial, or a desktop window on this computer. */
const someoneCanAnswer = (): boolean => deviceIsWatching() || backend.hasLocalClient()
const terminalStreams = new TerminalStreamManager({
@@ -1125,11 +1127,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
backend.handoffRequestProvider = createHandoffRequest({ prepare: (req) => prepareAgentHandoff(handoffDeps, req) })
- // The services harnessd's master runs in their own processes (harnessd/services.ts, `HARNESSD_SERVICES`):
- // only under a master, which is what gives this core the token they connect with. Their requests are
- // routed to them, and answered SERVICE_UNAVAILABLE while they are down (core/serviceLinks.ts).
- const serviceToken = process.env.HARNESSD_SUPERVISED === '1' ? process.env.HARNESSD_SERVICE_TOKEN : undefined
- const outOfProcess = servicesTheMasterRuns(process.env, KNOWN_SERVICES)
// The requests each service that can run in its own process answers, as core/api.ts declares them.
const requestsOf: Record<string, readonly string[]> = { search: SEARCH_REQUESTS, store: STORE_REQUESTS, usage: USAGE_REQUESTS, monitor: MONITOR_REQUESTS, projects: PROJECTS_REQUESTS }
// What the core keeps of the viewers in their own process, for the frames it builds (core/viewersLink.ts).
@@ -1146,15 +1143,18 @@ async function runForeground(session: AuthSession | null): Promise<void> {
answer: (service, query, payload) => service === 'viewers' ? viewersLink.answer(query, payload)
: service === 'workspaces' ? workspacesLink.answer(query, payload)
: service === 'store' ? storeLink.answer(query, payload)
- : service === 'teams' ? teamsLink.answer(query, payload) : answerAgentQuery(coreApi, query),
- })
+ : service === 'teams' ? teamsLink.answer(query, payload)
+ : service === 'gateway' && gatewayLink ? gatewayLink.answer(query, payload) : answerAgentQuery(coreApi, query),
+ // The gateway's own traffic: its remote clients and what they sent, and its comings and goings.
+ notice: (service, payload) => { if (service === 'gateway') gatewayLink?.notice(payload) },
+ binary: (service, bytes) => { if (service === 'gateway') gatewayLink?.binary(bytes) },
+ connected: (service) => { if (service === 'gateway') gatewayLink?.connected() },
+ disconnected: (service) => { if (service === 'gateway') gatewayLink?.disconnected() },
+ })
+ serviceLinksRef = serviceLinks
// A request a service declared goes to it: in its own process, or in this one (core/serviceHost.ts).
backend.serviceRouter = (type, payload, asker, reply) =>
serviceLinks.route(type, payload, asker, reply) || serviceHost.route(type, payload, asker, reply)
- // The services' own code, for those that run in this process (services/inline.ts): loaded only then, so
- // one in its own process, as each is by default, is never loaded here.
- const inline = KNOWN_SERVICES.some((name) => !outOfProcess.has(name)) ? await import('../services/inline.js') : null
-
// Session search (services/search.ts): in this process, or in its own (services/searchProcess.ts),
// where the core tells it what changed. A purge's forgetting waits for it if it is down.
if (outOfProcess.has('search')) {
@@ -1490,6 +1490,11 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// Which of the owner's other computers have been reading offline — a label on the models only they
// serve on a sleeping grid, never a removal (grid-reads-without-waking issue 03).
machineListCache.listen((body) => observeMachineList(body, computerId()))
+ // The trust group swaps rosters only with the members the backend last said were online (gateway/start.ts).
+ machineListCache.listen(() => {
+ const { machines, source } = machineListCache.list()
+ gatewayOps.reachable(source !== 'backend' ? null : machines.filter((m) => m.state !== 'offline').map((m) => m.machineId))
+ })
/**
* `GET /api/machines` for local clients, answered from the last known-good list when the backend leg
@@ -1531,128 +1536,10 @@ async function runForeground(session: AuthSession | null): Promise<void> {
}
- const turnHooks = createTurnHooks({
- resolve: (id) => registry.resolve(id),
- normalizers,
- emit: (sessionId, events) => emitSessionEvents(sessionId, events),
- drain: (sessionId) => watcher.pollSession(sessionId),
- onCursorTaskStart,
- cursorTaskHooks,
- cursorSubagents,
- announceTurnAborted,
- armAgyIdleWatch,
- clearAgyIdleWatch,
- mirror,
- dataDir: env.ADAPTER_DATA_DIR,
- })
- // Which agent a hook belongs to, and what a SessionEnd means (core/engines/hooks.ts).
- const engineHooks = createEngineHooks({ tmuxBackend, agentReconciler, registry })
- const { server: hookServer, port: hookPort, localSocket } = await startHookServer(daemonPort(), {
- onCommandBar: commandBarService,
- onAutonomousDeviceRequest: async (method, target, body) => {
- // Until the pieces below are built; after, a piece that could not be is refused by the requests
- // that need it, and the rest (list, status, revoke) answer from the pairings.
- if (!devicePartsBuilt) return { status: 503, body: { error: { code: 'UNAVAILABLE', message: 'Autonomous device service is starting' } } }
- return autonomousDeviceLocalRequest({
- discover: async () => ({ devices: await runningDevicePart(autonomousDeviceDirect, 'Wi-Fi device link').discover() }),
- pairStart: ({ code, device }) => runningDevicePart(autonomousDeviceDirect, 'Wi-Fi device link').pair(device, code),
- pairStatus: () => {
- const pending = gateway.pendingPair()
- return pending?.role === 'device' ? { state: pending.active ? 'running' : 'waiting', pairId: pending.pairId, deviceLabel: pending.label, expiresAt: pending.expiresAt } : { state: 'idle' }
- },
- list: () => ({ devices: gateway.listPairs().filter(p => p.role === 'device').map(p => ({ ...p, id: p.fingerprint })) }),
- status: () => ({ transport: 'direct', connected: gateway.directAutonomousDeviceSessions() > 0, paired: gateway.listPairs().filter(p => p.role === 'device').length, sessions: gateway.directAutonomousDeviceSessions(), proto: 1 }),
- revoke: ({ id }) => {
- if (!gateway.listPairs().some(p => p.role === 'device' && p.fingerprint === id)) throw Object.assign(new Error('Device pairing not found'), { code: 'UNKNOWN_DEVICE' })
- const result = gateway.revoke(id)
- if (!result.ok) throw Object.assign(new Error(result.error), { code: result.error })
- return { revoked: 1 }
- },
- receipt: target => ({ receipt: runningDevicePart(autonomousDeviceService, 'Wi-Fi device service').receipt(target.deviceId, target.idempotencyKey) }),
- }, method, target, body)
- },
- resolveHookAgent: engineHooks.resolveHookAgent,
- onRegistered: handleRegistered,
- onPromptSubmitted: (id, text) => teams.started(id, text, 'hook', registry.byAgent(id)?.engine),
- onSessionEnd: engineHooks.onSessionEnd,
- // What the engines' own hooks say about a turn (core/turns/turnHooks.ts).
- onTurnStart: turnHooks.onTurnStart,
- onToolStart: turnHooks.onToolStart,
- onTurnStop: turnHooks.onTurnStop,
- // `harness pair <code>` → run CPace toward the waiting browser; map the result to an HTTP outcome.
- onPair: async (code) => {
- const r = await gateway.pair(code)
- if (r.ok) return { status: 200, body: { label: r.label, fingerprint: r.fingerprint } }
- const codeMap: Record<string, number> = {
- NO_INTENT: 409, EXPIRED: 409, CODE_MISMATCH: 403, BACKEND_DOWN: 503,
- RATE_LIMITED: 429, BUSY: 409, TIMEOUT: 504,
- }
- return { status: codeMap[r.error] ?? 400, body: { error: r.error } }
- },
- onListPairs: () => ({ status: 200, body: { pairs: gateway.listPairs() } }),
- onRevoke: (id) => {
- const r = gateway.revoke(id)
- if (r.ok) return { status: 200, body: { label: r.label, fingerprint: r.fingerprint } }
- return { status: r.error === 'AMBIGUOUS' ? 409 : 404, body: { error: r.error } }
- },
- onRevokeAll: () => ({ status: 200, body: gateway.revokeAll() }),
- // `harness remote-password set|clear|status` — mutate/read the running daemon's live E2EE state
- // directly, so `harness link connect` from another machine sees a just-set password immediately.
- onSetRemotePassword: async (password) => {
- const r = await gateway.setRemotePassword(password)
- return { status: 200, body: r }
- },
- onClearRemotePassword: () => { gateway.clearRemotePassword(); return { status: 200, body: { ok: true } } },
- onRemotePasswordStatus: () => ({ status: 200, body: gateway.remotePasswordStatus() }),
- onTrustLinkedPeer: (peer) => {
- gateway.trustPeer({ ...peer, kind: 'machine' })
- groupSyncer?.linked({ ...peer, kind: 'machine' })
- return { status: 200, body: { ok: true } }
- },
- onGroupList: () => ({ status: 200, body: { self: groupSelf(), members: new TrustGroupStore().list() } }),
- onGroupSync: () => { void groupSyncer?.syncAll(); return { status: 200, body: { ok: true } } },
- onGroupRemove: (selector) => {
- const found = findGroupMember(selector)
- if (!found.ok) return { status: found.error === 'AMBIGUOUS' ? 409 : 404, body: { error: found.error } }
- groupSyncer?.remove(found.pub)
- // And out of the device key log, or the next read of it would put the device back.
- void devLogSyncer?.remove(found.pub)
- return { status: 200, body: { label: found.label, fingerprint: found.fingerprint } }
- },
- onDevicesList: async () => {
- if (!devLogSyncer) return { status: 503, body: { error: 'UNAVAILABLE' } }
- // When each key last opened a session, from the backend — a hint for removing apps not used in a
- // long while. Without it the list is still the list.
- const seen = await proxyBackend('GET', '/api/device-keys/seen').catch(() => null)
- const lastSeen = seen?.status === 200 ? (seen.body.data as { seen?: unknown } | undefined)?.seen : undefined
- return { status: 200, body: { ...devLogSyncer.list(), lastSeen: lastSeen && typeof lastSeen === 'object' ? lastSeen : {} } }
- },
- onDevicesRemove: async (pub) => {
- if (!devLogSyncer) return { status: 503, body: { error: 'UNAVAILABLE' } }
- groupSyncer?.remove(pub)
- const r = await devLogSyncer.remove(pub)
- if (r.ok) return { status: 200, body: { ok: true } }
- const status = r.error === 'NOT_IN_LOG' ? 404 : r.error === 'UNAVAILABLE' ? 503 : 409
- return { status, body: { error: r.error, ...(r.detail ? { detail: r.detail } : {}) } }
- },
- onDevicesHistory: async () => {
- if (!devLogSyncer) return { status: 503, body: { error: 'UNAVAILABLE' } }
- return { status: 200, body: { ...(await devLogSyncer.history()) } }
- },
- onDevicesDismiss: (body) => {
- if (!devLogSyncer) return { status: 503, body: { error: 'UNAVAILABLE' } }
- devLogSyncer.dismiss(body)
- return { status: 200, body: { ok: true } }
- },
- onDevicesRebaseline: async (confirm, head) => {
- if (!devLogSyncer) return { status: 503, body: { error: 'UNAVAILABLE' } }
- const r = await devLogSyncer.rebaseline(confirm, head)
- if (r && 'error' in r) return { status: 409, body: { error: r.error } }
- return r ? { status: 200, body: { ...r, applied: confirm } } : { status: 502, body: { error: 'LOG_UNAVAILABLE' } }
- },
- // Local dashboard (GET /api/status): adapter health + computer fingerprint + local pairings. It
- // deliberately does NOT expose chat/transcripts — those live in the cloud web (WEB_URL/commander).
- onStatus: async () => ({
+ // Local dashboard (GET /api/status): adapter health + computer fingerprint + local pairings. It
+ // deliberately does NOT expose chat/transcripts — those live in the cloud web (WEB_URL/commander). The
+ // fingerprint and the pairings are the gateway's, asked for each time (bounded: core/gatewayLink.ts).
+ const statusBody = async (relay: GatewayStatus): Promise<Record<string, unknown>> => ({
machineId: backend.machineId,
computerId: computerId(),
// Whether this daemon booted with an account. Read LIVE, not from the boot session: a login or
@@ -1676,7 +1563,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
webUrl: env.WEB_URL,
connected: backend.isConnected(),
deviceTransportConnected: backend.hasCommander(),
- deviceE2eeConnected: gateway.deviceE2eeConnected(),
+ deviceE2eeConnected: backend.deviceE2eeConnected(),
uptimeSec: Math.round((Date.now() - startedAt) / 1000),
// The daemon as everything outside knows it: the pid file's pid, which `harness stop` signals
// and the desktop app judges the owner of. Under a master that is the master's. A core's pid
@@ -1700,7 +1587,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// gone in a second; one that stays here names the store that is slow, which no other field does.
attaching: attaches.attaching(),
attachQueue: attaches.queued(),
- fingerprint: gateway.fingerprint(),
+ fingerprint: relay.fingerprint,
config: {
watching: `${terminalConfig.backends.join(' + ')} terminals across all supported engines`,
terminalBackends: terminalConfig.backends,
@@ -1723,9 +1610,77 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// When the conversation last moved, as in every agent frame — not the row's `touchedAt`.
updatedAt: await lastActivityAt(s),
}))),
- pairs: gateway.listPairs(),
- pending: gateway.pendingPair(),
- }),
+ pairs: relay.pairs,
+ pending: relay.pending,
+ })
+
+ const turnHooks = createTurnHooks({
+ resolve: (id) => registry.resolve(id),
+ normalizers,
+ emit: (sessionId, events) => emitSessionEvents(sessionId, events),
+ drain: (sessionId) => watcher.pollSession(sessionId),
+ onCursorTaskStart,
+ cursorTaskHooks,
+ cursorSubagents,
+ announceTurnAborted,
+ armAgyIdleWatch,
+ clearAgyIdleWatch,
+ mirror,
+ dataDir: env.ADAPTER_DATA_DIR,
+ })
+ // Which agent a hook belongs to, and what a SessionEnd means (core/engines/hooks.ts).
+ const engineHooks = createEngineHooks({ tmuxBackend, agentReconciler, registry })
+ const { server: hookServer, port: hookPort, localSocket } = await startHookServer(daemonPort(), {
+ onCommandBar: commandBarService,
+ onAutonomousDeviceRequest: async (method, target, body) => {
+ // Until the pieces below are built; after, a piece that could not be is refused by the requests
+ // that need it, and the rest (list, status, revoke) answer from the pairings.
+ if (!devicePartsBuilt) return { status: 503, body: { error: { code: 'UNAVAILABLE', message: 'Autonomous device service is starting' } } }
+ // The Wi-Fi device's pairings and direct links are the gateway's (gateway/start.ts); its receipts the
+ // device service's, here.
+ const viaGateway = async (request: Parameters<GatewayOps['wifi']>[0]): Promise<Record<string, unknown>> => {
+ const answer = await gatewayOps.wifi(request)
+ if ('refused' in answer) throw Object.assign(new Error(answer.refused.message), { code: answer.refused.code })
+ return answer.result
+ }
+ return autonomousDeviceLocalRequest({
+ discover: () => viaGateway({ op: 'discover' }),
+ pairStart: ({ code, device }) => viaGateway({ op: 'pair', code, device }),
+ pairStatus: () => viaGateway({ op: 'pairStatus' }),
+ list: () => viaGateway({ op: 'list' }),
+ status: async () => ({ transport: 'direct', connected: backend.directAutonomousDeviceSessions() > 0,
+ paired: ((await viaGateway({ op: 'list' })).devices as unknown[]).length, sessions: backend.directAutonomousDeviceSessions(), proto: 1 }),
+ revoke: ({ id }) => viaGateway({ op: 'revoke', id }),
+ receipt: target => ({ receipt: runningDevicePart(autonomousDeviceService, 'Wi-Fi device service').receipt(target.deviceId, target.idempotencyKey) }),
+ }, method, target, body)
+ },
+ resolveHookAgent: engineHooks.resolveHookAgent,
+ onRegistered: handleRegistered,
+ onPromptSubmitted: (id, text) => teams.started(id, text, 'hook', registry.byAgent(id)?.engine),
+ onSessionEnd: engineHooks.onSessionEnd,
+ // What the engines' own hooks say about a turn (core/turns/turnHooks.ts).
+ onTurnStart: turnHooks.onTurnStart,
+ onToolStart: turnHooks.onToolStart,
+ onTurnStop: turnHooks.onTurnStop,
+ // `harness pair`, `unpair`, `remote-password`, `link connect`, `group` and `devices`: the keys are the
+ // gateway's, and so are these answers (gateway/start.ts).
+ onPair: (code) => gatewayOps.pair(code),
+ onListPairs: () => gatewayOps.listPairs(),
+ onRevoke: (id) => gatewayOps.revoke(id),
+ onRevokeAll: () => gatewayOps.revokeAll(),
+ onSetRemotePassword: (password) => gatewayOps.setRemotePassword(password),
+ onClearRemotePassword: () => gatewayOps.clearRemotePassword(),
+ onRemotePasswordStatus: () => gatewayOps.remotePasswordStatus(),
+ onTrustLinkedPeer: (peer) => gatewayOps.trustLinkedPeer(peer),
+ onGroupList: () => gatewayOps.groupList(),
+ onGroupSync: () => gatewayOps.groupSync(),
+ onGroupRemove: (selector) => gatewayOps.groupRemove(selector),
+ onDevicesList: () => gatewayOps.devicesList(),
+ onDevicesRemove: (pub) => gatewayOps.devicesRemove(pub),
+ onDevicesHistory: () => gatewayOps.devicesHistory(),
+ onDevicesDismiss: (body) => gatewayOps.devicesDismiss(body),
+ onDevicesRebaseline: (confirm, head) => gatewayOps.devicesRebaseline(confirm, head),
+ onStatus: async () => statusBody(await gatewayOps.status()),
onLogs: () => {
try { return readFileSync(LOG_FILE, 'utf-8').split('\n').slice(-120).join('\n') } catch { return '' }
},
@@ -1772,141 +1727,13 @@ async function runForeground(session: AuthSession | null): Promise<void> {
daemonBoot.hookServer = hookServer
daemonBoot.localSocket = localSocket
console.log(`[cli] daemon pid ${process.pid} · v${VERSION}${process.env.ADAPTER_UPDATED_TO ? ' · updated' : ''} · listening on 127.0.0.1:${hookPort}`)
- // Same on-disk identity `harness remote-password set`/`link connect` use (E2eeStore.init() is
- // idempotent per file, so a separate in-memory instance here just reads the one this machine
- // already has).
+ // The fleet's lane signs and seals as this machine, with the same on-disk identity `harness link connect`
+ // proves knowledge against (services/fleet.ts). Until it goes through the gateway (step 10, R3).
const relayIdentityStore = new E2eeStore()
relayIdentityStore.init()
- const relayPeers = new MachinePeerStore()
- const relayPool = new RemoteRelayPool(
- auth,
- env.BACKEND_WS_URL.replace(/\/$/, ''),
- relayIdentityStore.getIdentity(),
- relayPeers,
- {
- onSessionReady: (machineId) => groupSyncer?.sessionOpened(machineId),
- // A machine the account's device key log names under this very key will trust us as soon as it
- // reads the log: keep its pin through a few denials, and nudge it (and us) to read.
- expectsTrust: (machineId, pub) => {
- const m = devLogSyncer?.list().members.find((x) => x.pub === pub)
- const expected = !!m && m.kind === 'machine' && m.machineId === machineId && !devLogSyncer?.suspendedKeys().includes(pub)
- if (expected) void devLogSyncer?.refresh()
- return expected
- },
- },
- )
- // Every machine and phone linked to this one, directly or through another member, trusts every other:
- // rosters are swapped over any session that opens, and pushed on whenever they change.
- groupSyncer = new GroupSyncer({
- store: new TrustGroupStore(),
- peers: new MachinePeerStore(),
- self: groupSelf,
- trust: (peer) => gateway.trustPeer(peer),
- untrust: (pub) => { gateway.untrustPeer(pub) },
- paired: () => gateway.pairedPeers(),
- request: relayRequester(relayPool, () => readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV),
- dropSessions: (machineId) => { relayPool.invalidate(machineId); relayPool.invalidateIsolated(machineId) },
- suspended: () => new Set(devLogSyncer?.suspendedKeys() ?? []),
- reachable: () => {
- // Only a list the backend answered says who is offline; otherwise try every member.
- const { machines, source } = machineListCache.list()
- return source !== 'backend' ? null : new Set(machines.filter((m) => m.state !== 'offline').map((m) => m.machineId))
- },
- log: (line) => console.log(line),
- })
- gateway.groupSync = groupSyncer
- gateway.onPeerLinked = (peer) => groupSyncer?.linked(peer)
- gateway.onUnpaired = (pub) => {
- groupSyncer?.unpaired(pub)
- // Unpairing a device here takes it out of the account's log too — or the log would trust it again.
- void devLogSyncer?.remove(pub)
- }
- if (session?.machineId) groupSyncer.start()
- devLogSyncer = new DeviceLogSyncer({
- store: new DeviceLogStore(),
- identity: () => { const id = relayIdentityStore.getIdentity(); return { pub: b64e(id.pub), priv: id.priv } },
- self: () => ({ machineId: readAuthSession()?.machineId ?? null, label: thisDeviceLabel() }),
- // Which sign-in by hand this machine is under (minted by `harness login`, never a backend answer —
- // the machine id is one): the device log can start over only when THIS changes.
- signIn: () => signInOf(readAuthSession()?.signInEpoch),
- fetch: async (since) => {
- const r = await proxyBackend('GET', `/api/device-keys?since=${since}`)
- const data = r.status === 200 ? r.body.data as Partial<DeviceLogFetched> | undefined : undefined
- const head = data?.head as { seq?: unknown; hash?: unknown } | undefined
- if (!data || typeof data.acct !== 'string' || !Array.isArray(data.entries) || typeof head?.seq !== 'number'
- || !Number.isSafeInteger(head.seq) || head.seq < 0 || typeof head.hash !== 'string') return null
- return { acct: data.acct, head: { seq: head.seq, hash: head.hash }, entries: data.entries }
- },
- append: async (entry) => {
- const p = await gateway.appendDeviceLog(entry as unknown as Record<string, unknown>)
- if (!p) return null
- const head = p.head as { seq?: unknown; hash?: unknown } | undefined
- const parsedHead = typeof head?.seq === 'number' && typeof head.hash === 'string' ? { seq: head.seq, hash: head.hash } : undefined
- if (typeof p.error === 'string') return { error: p.error, ...(parsedHead ? { head: parsedHead } : {}) }
- return parsedHead ? { head: parsedHead } : null
- },
- adopt: (members) => groupSyncer?.adoptFromLog(members),
- drop: (pub) => { groupSyncer?.remove(pub) },
- // Snapshotted once, when this machine joins the log: what it already trusts then is never news.
- trustedNow: () => [...new Set([
- ...gateway.pairedPeers().map((p) => p.identityPub),
- ...relayPeers.list().map((p) => p.pub),
- ...(groupSyncer?.roster().members.map((m) => m.pub) ?? []),
- ])],
- tombstoned: (pub) => !!groupSyncer?.tombstoned(pub),
- blocked: (pub) => !!groupSyncer?.isBlocked(pub),
- announce: (m) => {
- const fp = e2eeCoreFingerprint(e2eeCoreDecode(m.pub))
- console.log(`[devlog] NEW DEVICE on this account: ${m.label || '(no name)'} (${m.kind}) ${fp} — not yours? harness devices remove ${fp}`)
- backend.sendLocal({ type: 'device_key_added', payload: { pub: m.pub, label: m.label, kind: m.kind, machineId: m.machineId, at: m.addedAt, fingerprint: fp } })
- },
- removed: (n) => {
- if (n.selfRemoved) console.log(`[devlog] ${n.label || '(no name)'} signed out of this account (${n.fingerprint})`)
- else if (n.signerPending) console.log(`[devlog] ⚠ ${n.label || '(no name)'} (${n.fingerprint}) was removed by a NEW device you have not looked at: ${n.signerLabel || 'another device'} (${n.signerFingerprint}) — not yours? harness devices remove ${n.signerFingerprint}`)
- else console.log(`[devlog] ${n.label || '(no name)'} (${n.fingerprint}) was removed from this account by ${n.signerLabel || 'another device'}`)
- backend.sendLocal({ type: 'device_key_removed', payload: { ...n } })
- },
- conflict: (c) => {
- backend.sendLocal({ type: 'device_conflict', payload: { pub: c.pub, label: c.label, fingerprint: c.fingerprint, addedAt: c.addedAt, afterJoin: c.afterJoin } })
- },
- suspend: (pubs) => groupSyncer?.suspend(pubs),
- resume: () => groupSyncer?.resume(),
- signedOut: () => {
- // This machine's key was removed from the account: it is signed out, and comes back — after a
- // new `harness login` — with a NEW key, which every other device announces as a new device.
- console.log('[devlog] this machine was removed from the account\'s devices — signing out')
- spendIdentity()
- backend.onRevoked?.()
- },
- changed: () => backend.sendLocal({ type: 'device_keys_changed', payload: {} }),
- log: (line) => console.log(line),
- })
- groupSyncer.devlog = devLogSyncer
- // Removed while online: the backend's `machine_revoked` arrives before this machine reads the log, and
- // stops it. The key is spent all the same, or the next `harness login` would come back under a banned
- // key and be signed out again.
- gateway.onDeviceRemoved = (pub) => {
- if (pub === b64e(relayIdentityStore.getIdentity().pub)) spendIdentity()
- }
- // A removal of another key under this machine id — the earlier install a reinstall waits behind — is
- // not this machine signed out: the log re-read that follows registers this key (deviceLogSyncer).
- gateway.isOwnDeviceKey = (pub) => pub === b64e(relayIdentityStore.getIdentity().pub)
- // A removal the trust group carried in — typically `harness group remove` on a machine that predates
- // the log — goes into the log as well, signed by this machine, so a device that only reads the log
- // stops trusting that key too. A key the log no longer has is left alone.
- groupSyncer.onDropped = (pub) => {
- if (devLogSyncer?.list().members.some((m) => m.pub === pub && !m.self)) void devLogSyncer.remove(pub)
- }
- gateway.onDeviceKeysChanged = () => { void devLogSyncer?.refresh() }
- if (session?.machineId) {
- // Every time the link comes up: a sign-in from before the log existed joins it with no one doing
- // anything, and one that joined already only reads what it missed while offline.
- gateway.onLinkUp = () => { void devLogSyncer?.register() }
- // The link may have come up before this line; a second register in flight is harmless. A session
- // from before sign-in epochs gets one first: adopted, so it never starts the device log over.
- void ensureSignInEpoch().catch(() => null).then(() => devLogSyncer?.register())
- setInterval(() => { void devLogSyncer?.refresh() }, 10 * 60_000).unref()
- }
+ // The device key log records which sign-in this machine is under: a session from before sign-in epochs
+ // gets one first, adopted so it never starts the log over, and the gateway registers with it then.
+ if (session?.machineId) void ensureSignInEpoch().catch(() => null).then(() => gatewayOps.account(account()))
// The dial, the window bridges and the WiFi device answer for themselves. A throw in any of them is
// logged — at most once a minute each, with a count of the rest (core/turns/funnel.ts) — and goes no
// further: the local socket closes a connection whose frame handler throws, so a device fault left
@@ -2074,7 +1901,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
onVoiceRouteReply: (voiceId, reply) => devices('window', () => windowRouter.reply(voiceId, reply)),
machineId: backend.machineId,
backend,
- relayPool,
+ relayPool: gateway.windowRelay,
autonomousEnv: readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV,
// A window from before it introduced itself still gets named on the far side's "took control"
// banner: the relay knows it is this machine's desktop. Same source as `describeClient` above.
@@ -2083,7 +1910,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
// Every engine's hooks, pointed at the port the local server actually bound (core/engines/hooks.ts).
if (!env.DISABLE_HOOK_INSTALL) installEngineHooks(hookPort, { only: env.HOOK_INSTALL_ENGINES, loginShell: loginShellEnvPromise })
- gateway.setDashboardPort(hookPort) // surfaced to the web (e2e_status) so it can link here to approve
+ gatewayOps.dashboardPort(hookPort) // surfaced to the web (e2e_status) so it can link here to approve
console.log(`[cli] local dashboard → http://127.0.0.1:${hookPort}`)
// Each transcript line, through its engine's normalizer, into the funnel (core/transcripts/ingest.ts).
@@ -2631,7 +2458,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
['the local socket', () => localSocket?.close()], ['Codex activity', () => codexActivity.close()],
['the voice router', () => shutdownVoiceRouter()],
// The successor starts its own viewers for the agents it restores; ours must not hold the ports.
- ['the viewers', () => ports.viewers?.stop()], ['the device link', () => autonomousDeviceDirect?.stop()],
+ ['the viewers', () => ports.viewers?.stop()], ['the gateway', () => gateway.stop()],
// A graceful close releases the backend's one-machine claim, given a moment before the reclaim.
['the backend', () => backend.stop()], ['a grace', () => new Promise((r) => setTimeout(r, 1000))],
]).catch((err) => {
@@ -2685,7 +2512,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
codexActivity.close()
shutdownVoiceRouter()
await ports.viewers?.stop()
- autonomousDeviceDirect?.stop()
+ await gateway.stop()
await backend.stop()
try { if (readPid() === process.pid) rmSync(PID_FILE, { force: true }) } catch { /* ignore */ }
process.exit(coreLink.supervised && forGood(signal) ? CORE_EXIT_STOP : 0)
@@ -2864,23 +2691,16 @@ async function runForeground(session: AuthSession | null): Promise<void> {
answer: async (agentId, requestId, answers) => (await questions.answer({ agentId, requestId, answers, allowPermissions: false })).ok,
recent: (id, n) => mirror.recent(registry.byAgent(id)?.sessionId ?? id, n),
fullText: id => mirror.lastFullText(registry.byAgent(id)?.sessionId ?? id),
- emit: (frame, deviceId) => gateway.emitAutonomousDeviceEvent(frame, deviceId),
+ emit: (frame, deviceId) => backend.emitAutonomousDeviceEvent(frame, deviceId),
}))
if (appVoiceFocus) autonomousDeviceService?.appFocus(appVoiceFocus.machineId, appVoiceFocus.agentId, appVoiceFocus.connId)
- if (autonomousDeviceService) gateway.setAutonomousDeviceService(autonomousDeviceService)
- // No link without the service: a device it connected would be answered by nothing.
- autonomousDeviceDirect = autonomousDeviceService && startDevicePart('Wi-Fi device link', () => new AutonomousDeviceDirect({
- machineId: backend.machineId, label: hostname(),
- receive: (connId, frame, pairing) => gateway.receiveDirectDevice(connId, frame, pairing),
- attach: (connId, send) => gateway.attachDirectDevice(connId, send),
- detach: connId => gateway.detachDirectDevice(connId),
- pending: () => gateway.pendingPair(), pendingConnection: () => gateway.e2ee.pendingConnection(),
- authenticatedFingerprint: connId => { const pub = gateway.e2ee.sessionIdentity(connId); return pub ? e2eeCoreFingerprint(e2eeCoreDecode(pub)) : null },
- pairedFingerprint: connId => gateway.pairedDirectFingerprint(connId),
- pair: code => gateway.pair(code), paired: () => gateway.listPairs(),
- }, env.ADAPTER_DATA_DIR))
- gateway.onDirectDeviceRevoked = fp => autonomousDeviceDirect?.revoked(fp)
- autonomousDeviceDirect?.start()
+ // The device's requests reach the service through its relay in the socket; its sessions and its direct
+ // links are the gateway's, which starts the links only with the service up: a device it connected would
+ // be answered by nothing.
+ if (autonomousDeviceService) {
+ backend.setAutonomousDeviceService(autonomousDeviceService, (identity) => gatewayOps.revokeIdentity(identity))
+ gatewayOps.wifiService(true)
+ }
devicePartsBuilt = true
// Worktrees Harness made that no live or stopped harness uses and nothing would miss
@@ -2964,30 +2784,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
console.log('[cli] ready')
}
-/** This machine as its trust group knows it — see groupSyncer.ts's SELF_STAMP for the stamp. */
-let groupSelfPub: string | null = null
-
-function groupSelf(): GroupMember {
- groupSelfPub ??= b64e(new E2eeStore().init().pub)
- const machineId = readAuthSession()?.machineId
- return { pub: groupSelfPub, kind: 'machine', label: hostname(), at: SELF_STAMP, ...(machineId ? { machineId } : {}) }
-}
-
-/** A trust-group member by machine id, list number, or fingerprint (full or unique prefix). */
-function findGroupMember(selector: string): { ok: true; pub: string; label: string; fingerprint: string } | { ok: false; error: 'NOT_FOUND' | 'AMBIGUOUS' } {
- const members = new TrustGroupStore().list()
- const norm = (v: string): string => v.toUpperCase().replace(/[·\s-]/g, '')
- const byIndex = /^\d+$/.test(selector) ? members[Number(selector) - 1] : undefined
- const byMachine = members.find((m) => m.machineId === selector)
- const hit = byMachine ?? byIndex ?? (() => {
- const matches = members.filter((m) => norm(m.fingerprint).startsWith(norm(selector)))
- return matches.length > 1 ? 'AMBIGUOUS' as const : matches[0]
- })()
- if (hit === 'AMBIGUOUS') return { ok: false, error: 'AMBIGUOUS' }
- if (!hit || !selector.trim()) return { ok: false, error: 'NOT_FOUND' }
- return { ok: true, pub: hit.pub, label: hit.label, fingerprint: hit.fingerprint }
-}
-
/**
* The daemon's start-up threw. STAY UP anyway, running nothing but the updater.
*
diff --git a/cli/src/core/serviceLinks.spec.ts b/cli/src/core/serviceLinks.spec.ts
index eb823970e..614884eaa 100644
--- a/cli/src/core/serviceLinks.spec.ts
+++ b/cli/src/core/serviceLinks.spec.ts
@@ -39,6 +39,50 @@ describe('service links', () => {
expect(make({ token: undefined }).accept('search', TOKEN, sink(), vi.fn())).toBeNull()
})
+ it('hands on what a service tells the core without asking, its bytes and its comings and goings (the gateway)', () => {
+ const notice = vi.fn(), binary = vi.fn(), connected = vi.fn(), disconnected = vi.fn()
+ const links = make({ owned: { gateway: [] }, notice, binary, connected, disconnected })
+ // Nothing to send bytes to, and nothing waiting, while it is away.
+ expect(links.notifyBinary('gateway', Uint8Array.of(1))).toBe(false)
+ expect(links.buffered('gateway')).toBe(0)
+ const gateway = { ...sink(), sendBinary: vi.fn(() => true), buffered: vi.fn(() => 42) }
+ const link = links.accept('gateway', TOKEN, gateway, vi.fn())!
+ expect(connected).toHaveBeenCalledWith('gateway')
+ link.receive({ type: 'service_notice', payload: { kind: 'status', connected: true } })
+ expect(notice).toHaveBeenCalledWith('gateway', { kind: 'status', connected: true })
+ link.receiveBinary(Uint8Array.of(7))
+ expect(binary).toHaveBeenCalledWith('gateway', Uint8Array.of(7))
+ expect(links.notifyBinary('gateway', Uint8Array.of(2))).toBe(true)
+ expect(gateway.sendBinary).toHaveBeenCalledWith(Uint8Array.of(2))
+ expect(links.buffered('gateway')).toBe(42)
+ link.closed()
+ expect(disconnected).toHaveBeenCalledWith('gateway')
+ // A service whose sink carries no bytes, and that says nothing of what waits on it.
+ const plain = links.accept('gateway', TOKEN, sink(), vi.fn())!
+ expect(links.notifyBinary('gateway', Uint8Array.of(3))).toBe(false)
+ expect(links.buffered('gateway')).toBe(0)
+ // Without the hooks, the same frames are taken and nothing is said.
+ const bare = make({ owned: { gateway: [] } })
+ const quiet = bare.accept('gateway', TOKEN, sink(), vi.fn())!
+ quiet.receive({ type: 'service_notice', payload: {} })
+ quiet.receiveBinary(Uint8Array.of(1))
+ quiet.closed()
+ plain.closed()
+ })
+
+ it('waits as long as a call says it may (a pairing), and answers SERVICE_UNAVAILABLE after', async () => {
+ const links = make({ owned: { gateway: [] } })
+ links.accept('gateway', TOKEN, sink(), vi.fn())
+ const answer = links.call('gateway', 'gateway_pair', { code: 'X' }, 60_000)
+ vi.advanceTimersByTime(30_000)
+ let settled = false
+ void answer.then(() => { settled = true })
+ await vi.advanceTimersByTimeAsync(0)
+ expect(settled).toBe(false)
+ vi.advanceTimersByTime(30_000)
+ await expect(answer).resolves.toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'gateway' })
+ })
+
it('routes a request to its service and relays the answer under the asker\'s own request', async () => {
const links = make()
const search = sink()
diff --git a/cli/src/core/serviceLinks.ts b/cli/src/core/serviceLinks.ts
index 1da3a947d..30e5098e8 100644
--- a/cli/src/core/serviceLinks.ts
+++ b/cli/src/core/serviceLinks.ts
@@ -21,11 +21,18 @@ export interface ServiceFrame {
/** Where frames to one service's connection go. */
export interface ServiceSink {
sendFrame(frame: ServiceFrame): boolean
+ /** Bytes, for a service that carries terminals (the gateway); false when the socket refused them. */
+ sendBinary?(bytes: Uint8Array): boolean
+ /** How many bytes are waiting on the socket to the service: a hung one stops reading, and what the core
+ * keeps sending it would pile up in the core's memory. */
+ buffered?(): number
}
/** What the local socket hands back for a service connection: its frames in, its end. */
export interface ServiceLink {
receive(frame: ServiceFrame): void
+ /** A binary frame from the service. */
+ receiveBinary(bytes: Uint8Array): void
closed(): void
}
@@ -36,6 +43,13 @@ export interface ServiceLinksOptions {
owned: Readonly<Record<string, readonly string[]>>
/** The core's answer to a service's question (`service_query`): `query` names it. */
answer(service: string, query: string, payload: Record<string, unknown>): Record<string, unknown> | Promise<Record<string, unknown>>
+ /** What a service tells the core without asking (`service_notice`), and its binary frames: the gateway's
+ * remote clients and what they sent. Only the services that send them are given these. */
+ notice?(service: string, payload: Record<string, unknown>): void
+ binary?(service: string, bytes: Uint8Array): void
+ /** A service connected (each time, a restarted one too), or its connection ended. */
+ connected?(service: string): void
+ disconnected?(service: string): void
/** How long a routed request may wait for its service before it is answered SERVICE_UNAVAILABLE. */
timeoutMs?: number
log?: (line: string) => void
@@ -91,13 +105,13 @@ export function createServiceLinks(options: ServiceLinksOptions) {
}
/** Send `type` to `service`, its answer to `reply`, whatever becomes of the service. */
- const ask = (service: string, type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void): void => {
+ const ask = (service: string, type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void, waitMs = timeoutMs): void => {
const link = links.get(service)
if (!link) { reply(unavailable(service)); return }
const id = newId()
const entry: Waiting = { service, type, reply, timer: null }
// Cleared whenever the entry is settled, so it only ever fires for one still waiting.
- entry.timer = setTimer(() => settle(id, entry, unavailable(service)), timeoutMs)
+ entry.timer = setTimer(() => settle(id, entry, unavailable(service)), waitMs)
waiting.set(id, entry)
if (!link.sink.sendFrame({ type, payload: { ...payload, requestId: id }, asker })) settle(id, entry, unavailable(service))
}
@@ -117,9 +131,11 @@ export function createServiceLinks(options: ServiceLinksOptions) {
const owed = held.get(service) ?? []
held.delete(service)
for (const frame of owed) sink.sendFrame(frame)
+ options.connected?.(service)
return {
receive: (frame) => {
const payload = frame.payload ?? {}
+ if (frame.type === 'service_notice') { options.notice?.(service, payload); return }
if (frame.type === 'service_query') {
const requestId = payload.requestId
const query = typeof payload.query === 'string' ? payload.query : ''
@@ -136,11 +152,13 @@ export function createServiceLinks(options: ServiceLinksOptions) {
const { requestId: _routed, ...result } = payload
settle(id, entry, result)
},
+ receiveBinary: (bytes) => { options.binary?.(service, bytes) },
closed: () => {
if (links.get(service) !== connected) return
links.delete(service)
log(`[services] ${service} disconnected`)
for (const [id, entry] of waiting) if (entry.service === service) settle(id, entry, unavailable(service))
+ options.disconnected?.(service)
},
}
},
@@ -157,8 +175,18 @@ export function createServiceLinks(options: ServiceLinksOptions) {
/** Ask a service what the core itself needs (a port's call, core/monitorLink.ts): answered by its
* handler for `type` in its process, or SERVICE_UNAVAILABLE as a routed request is, while it is down
* or slow. Never rejects. The types it asks are no client's to route: only the core sends them. */
- call(service: string, type: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
- return new Promise((resolve) => { ask(service, type, payload, THE_CORE, resolve) })
+ call(service: string, type: string, payload: Record<string, unknown>, waitMs?: number): Promise<Record<string, unknown>> {
+ return new Promise((resolve) => { ask(service, type, payload, THE_CORE, resolve, waitMs) })
+ },
+
+ /** Bytes for a service that carries terminals; false when it is not connected or would not take them. */
+ notifyBinary(service: string, bytes: Uint8Array): boolean {
+ return links.get(service)?.sink.sendBinary?.(bytes) ?? false
+ },
+
+ /** How many bytes wait on the socket to a service; 0 when it is not connected. */
+ buffered(service: string): number {
+ return links.get(service)?.sink.buffered?.() ?? 0
},
/** Tell a service something it needs to know; false when it is not connected to hear it. With
diff --git a/cli/src/gateway/gateway.spec.ts b/cli/src/gateway/gateway.spec.ts
index 4ed2635c6..98ecc0d54 100644
--- a/cli/src/gateway/gateway.spec.ts
+++ b/cli/src/gateway/gateway.spec.ts
@@ -53,8 +53,8 @@ describe('a remote client, as the core hears it', () => {
it('is registered with the role and label its session proved, and forgotten when the relay says it left', async () => {
const socket = relaySocket(MACHINE)
expect(socket.remoteClient('phone-1')).toBeNull()
- await pairedClient(socket, 'phone-1', { label: 'Dee’s phone' })
- expect(socket.remoteClient('phone-1')).toEqual({ role: 'web', label: 'Dee’s phone' })
+ const phone = await pairedClient(socket, 'phone-1', { label: 'Dee’s phone' })
+ expect(socket.remoteClient('phone-1')).toEqual({ role: 'web', label: 'Dee’s phone', identity: phone.pub, direct: false })
await dispatchDown(socket, { type: '__client_disconnected', payload: {} }, 'phone-1')
expect(socket.remoteClient('phone-1')).toBeNull()
await socket.stop()
@@ -212,3 +212,49 @@ describe('terminal streams on a client\'s P2P channel', () => {
await socket.stop()
})
})
+
+describe('the Wi-Fi device, over the gateway\'s sessions', () => {
+ it('an unpaired device is told so, sealed, while its session still stands, and the service forgets it after', async () => {
+ // The device clears its own pin on this frame; told after its session is gone, it could not open it
+ // and would show "paired, disconnected" for ever (lib/autonomous-device/relay.ts `revoke`).
+ const socket = relaySocket(MACHINE)
+ const gateway = gatewayOf(socket)
+ const revoked = vi.fn()
+ socket.fromGateway.deviceRevoked = revoked
+ const dial = await pairedClient(socket, 'dial-1', { role: 'device', label: 'Desk dial' })
+ gateway.deviceClient('dial-1', dial.pub)
+ gateway.revoke(C.fingerprint(C.b64d(dial.pub)))
+ const told = queuedFor(socket, 'dial-1').map((frame) => frame.type)
+ expect(told.indexOf('autonomous_device_event')).toBeGreaterThanOrEqual(0)
+ expect(told.indexOf('autonomous_device_event')).toBeLessThan(told.indexOf('e2e_denied'))
+ const event = queuedFor(socket, 'dial-1').find((frame) => frame.type === 'autonomous_device_event')!
+ expect(dial.open(event)).toEqual({ type: 'pair.revoke', machineId: MACHINE })
+ // The service hears of it once the session is gone, so its relay has nobody left to tell twice.
+ expect(revoked).not.toHaveBeenCalled()
+ expect(socket.remoteClient('dial-1')).toBeNull()
+ await new Promise((done) => setImmediate(done))
+ expect(revoked).toHaveBeenCalledWith(dial.pub)
+ await socket.stop()
+ })
+
+ it('opens a device\'s request only when the relay would, and hands it on with the frame as it came', async () => {
+ const socket = relaySocket(MACHINE)
+ const heard = vi.fn()
+ socket.fromGateway.device = heard
+ const dial = await pairedClient(socket, 'dial-1', { role: 'device', label: 'Desk dial' })
+ const phone = await pairedClient(socket, 'phone-1')
+ const sealed = dial.seal('autonomous_device_request', { type: 'hello', proto: 1, requestId: 'h' })
+ await dispatchDown(socket, sealed, 'dial-1')
+ expect(heard).toHaveBeenLastCalledWith('dial-1', sealed, { type: 'autonomous_device_request', payload: { type: 'hello', proto: 1, requestId: 'h' } })
+ // A web session's, an unsealed one, or one beside a session id: never opened, as the relay never did.
+ const fromPhone = phone.seal('autonomous_device_request', { type: 'hello' })
+ await dispatchDown(socket, fromPhone, 'phone-1')
+ expect(heard).toHaveBeenLastCalledWith('phone-1', fromPhone, null)
+ await dispatchDown(socket, { type: 'autonomous_device_request', payload: { type: 'hello' } }, 'dial-1')
+ expect(heard.mock.lastCall?.[2]).toBeNull()
+ const withSession = { ...dial.seal('autonomous_device_request', { type: 'hello' }), dbSessionId: 's1' }
+ await dispatchDown(socket, withSession, 'dial-1')
+ expect(heard.mock.lastCall?.[2]).toBeNull()
+ await socket.stop()
+ })
+})
diff --git a/cli/src/gateway/gateway.ts b/cli/src/gateway/gateway.ts
index b6989acd4..4a169787f 100644
--- a/cli/src/gateway/gateway.ts
+++ b/cli/src/gateway/gateway.ts
@@ -16,8 +16,6 @@
import { env } from '../config/env.js'
import type { GatewayEvents, GatewayPort, RemoteRole, RemoteTransport } from '../core/api.js'
import { deviceDump } from '../lib/autonomous-device/dump.js'
-import { AutonomousDeviceRelay } from '../lib/autonomous-device/relay.js'
-import type { AutonomousDeviceFrame, AutonomousDeviceService } from '../lib/autonomous-device/service.js'
import type { AuthSessionManager } from '../lib/authSession.js'
import { shouldReplayCommander } from '../lib/commanderReplay.js'
import { DEVICE_RECENT_SAFE_FRAME_BYTES, fitRecentReplyPayloadForDevice } from '../lib/deviceRecentTrim.js'
@@ -42,7 +40,7 @@ type Frame = Record<string, unknown>
export interface RelayGatewayOptions {
/** Backend-resolved machine id, persisted by the SSO login preflight; in isolated unit tests, the token. */
machineId: string
- auth?: AuthSessionManager
+ auth?: Pick<AuthSessionManager, 'accessToken'>
computerId?: string
autonomousEnv?: string
/** The core, as the gateway tells it what happened. */
@@ -86,7 +84,9 @@ export class RelayGateway implements GatewayPort {
private localClientCount = 0
private readonly directDeviceSinks = new Map<string, (frame: Frame) => void>()
private readonly directDevicePins = new Map<string, string>()
- private autonomousDeviceRelay?: AutonomousDeviceRelay
+ /** The Wi-Fi device sessions whose app said hello to the device service (in the core), by connection:
+ * the ones told, sealed, that they were unpaired (`onIdentityRevoked`). */
+ private readonly deviceClients = new Map<string, string>()
/** Answers the trust group's roster exchange (`group_sync`); null until the daemon wires it. */
groupSync: { handle: (peerPub: string, payload: Record<string, unknown>) => Record<string, unknown> } | null = null
@@ -128,8 +128,10 @@ export class RelayGateway implements GatewayPort {
isConnected: () => this.connected(),
isConnectionAvailable: connId => this.directDeviceSinks.has(connId) || this.connected(),
onIdentityPaired: (connId, pub) => { if (this.directDeviceSinks.has(connId)) this.directDevicePins.set(connId, pub) },
- onIdentityRevoked: identity => { this.autonomousDeviceRelay?.revoke(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },
- onSessionOpened: (connId, role) => this.core.client(connId, { role, label: this.e2ee.sessionLabel(connId) }),
+ onIdentityRevoked: identity => { this.deviceUnpaired(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },
+ onSessionOpened: (connId, role, identity) => this.core.client(connId, {
+ role, label: this.e2ee.sessionLabel(connId), identity, direct: this.directDeviceSinks.has(connId),
+ }),
onSessionDropped: (connId) => this.core.client(connId, null),
onPeerLinked: (peer) => {
// The mutual half of a password link: a machine that proved this one's password is pinned back,
@@ -431,7 +433,7 @@ export class RelayGateway implements GatewayPort {
return
}
if (type === 'autonomous_device_request') {
- await this.autonomousDeviceRelay?.handle(connId, frame)
+ await this.deviceRequest(connId, frame)
return
}
// ⚠️ Default-deny: the relay is NOT trusted. A frame is acted on only if it opens under this connId's
@@ -523,7 +525,7 @@ export class RelayGateway implements GatewayPort {
// The backend is authoritative for the outer connId. Drop both kinds of
// connection-scoped state immediately; otherwise a dead Desktop keeps a
// terminal controller lease until the 30-second heartbeat timeout.
- this.autonomousDeviceRelay?.drop(connId)
+ this.deviceClients.delete(connId)
this.e2ee.dropSession(connId)
await this.terminalP2p.closeConnection(connId, 'client_disconnected', false)
this.p2pPendingOpens.delete(connId)
@@ -757,7 +759,8 @@ export class RelayGateway implements GatewayPort {
}
attachDirectDevice(connId: string, send: (frame: Frame) => void): void { this.directDeviceSinks.set(connId, send) }
detachDirectDevice(connId: string): void {
- this.directDeviceSinks.delete(connId); this.directDevicePins.delete(connId); this.e2ee.dropSession(connId); this.autonomousDeviceRelay?.drop(connId)
+ this.directDeviceSinks.delete(connId); this.directDevicePins.delete(connId); this.deviceClients.delete(connId); this.e2ee.dropSession(connId)
+ void this.core.disconnected(connId)
this.core.commanders(this.commanderCount, this.commanderActive, true)
}
pairedDirectFingerprint(connId: string): string | null { const pub = this.directDevicePins.get(connId); return pub ? fingerprint(b64d(pub)) : null }
@@ -766,24 +769,59 @@ export class RelayGateway implements GatewayPort {
const type = frame.type
if (type !== 'autonomous_device_request') deviceDump.record('in', 'wire', connId, frame) // requests: decrypted in the relay
if (type === 'machine_selected') return
- if (type === 'autonomous_device_request') { await this.autonomousDeviceRelay?.handle(connId, frame); return }
+ if (type === 'autonomous_device_request') { await this.deviceRequest(connId, frame); return }
const controls = pairingAllowed ? ['e2e_pair_intent', 'e2e_pair_cancel', 'e2e_pake', 'e2e_hello', 'e2e_status'] : ['e2e_hello', 'e2e_status']
if ((type === 'e2e_pake' || type === 'e2e_pair_cancel') && this.e2ee.pendingConnection() !== connId) return
if (typeof type === 'string' && controls.includes(type)) this.e2ee.handleFrame(connId, frame)
}
- setAutonomousDeviceService(service: AutonomousDeviceService): void {
- this.autonomousDeviceRelay = new AutonomousDeviceRelay(
- this.e2ee,
- (connId, frame) => this.sendTo(connId, frame),
- service,
- this.machineId,
- () => this.core.commanderJoined(),
- identity => this.e2ee.revoke(fingerprint(b64d(identity))),
- )
- }
- directAutonomousDeviceSessions(): number { return this.autonomousDeviceRelay?.count(id => this.directDeviceSinks.has(id)) ?? 0 }
- autonomousDeviceConnected(): boolean { return this.autonomousDeviceRelay?.connected() ?? false }
- emitAutonomousDeviceEvent(frame: AutonomousDeviceFrame, deviceId?: string): void { this.autonomousDeviceRelay?.emit(frame, deviceId) }
+
+ /**
+ * A Wi-Fi device's request, for the device service's relay in the core (lib/autonomous-device/relay.ts),
+ * opened here under the session that sealed it. Opened only when the relay would open it (a device's
+ * session, a sealed frame, no session id beside it), so its replay window moves exactly as it did when
+ * the relay opened the frame itself.
+ */
+ private async deviceRequest(connId: string, frame: Frame): Promise<void> {
+ const opens = !!this.e2ee.sessionIdentity(connId) && this.e2ee.sessionRole(connId) === 'device' && isWrapped(frame.payload) && frame.dbSessionId === undefined
+ await this.core.device(connId, frame, opens ? this.e2ee.unwrapDown(connId, frame) : null)
+ }
+
+ /** The device service's answer or event for one Wi-Fi device session, sealed to it. */
+ device(connId: string, type: string, payload: Record<string, unknown>): boolean {
+ const wrapped = this.e2ee.wrapTarget(connId, type, payload)
+ if (!wrapped) return false
+ this.sendTo(connId, wrapped)
+ return true
+ }
+
+ deviceClient(connId: string, identity: string | null): void {
+ if (identity) this.deviceClients.set(connId, identity)
+ else this.deviceClients.delete(connId)
+ }
+
+ /**
+ * App-side revoke: tell the device while its authenticated session still exists (the E2eeManager drops
+ * the session right after this), so it clears its own pin instead of showing "paired / disconnected"
+ * forever. The device service's relay did this itself when it shared this process; the core is now a
+ * frame away, and the session would be gone by the time it answered, so the gateway sends the same frame
+ * to the same sessions here, and the service hears of the unpairing once they are gone. Best-effort: a
+ * device that is offline learns it on reconnect, when its e2e_hello gets e2e_denied.
+ */
+ private deviceUnpaired(identity: string): void {
+ for (const [connId, client] of [...this.deviceClients]) {
+ if (client !== identity) continue
+ this.deviceClients.delete(connId)
+ if (this.e2ee.sessionIdentity(connId) !== identity || this.e2ee.sessionRole(connId) !== 'device') continue
+ const event = { type: 'pair.revoke', machineId: this.machineId }
+ try {
+ deviceDump.record('out', 'rpc', connId, { type: 'autonomous_device_event', payload: event })
+ this.device(connId, 'autonomous_device_event', event)
+ } catch { /* Local removal must proceed regardless. */ }
+ }
+ // After the sessions are dropped, which the manager does once this returns: the service's relay then
+ // finds none left to tell, and only forgets the identity.
+ setImmediate(() => this.core.deviceRevoked(identity))
+ }
// ── the pairings, for the daemon's own commands (`harness pair`, `unpair`, `remote-password`, …) ──
diff --git a/cli/src/gateway/gatewayProcess.spec.ts b/cli/src/gateway/gatewayProcess.spec.ts
new file mode 100644
index 000000000..ce7aa5021
--- /dev/null
+++ b/cli/src/gateway/gatewayProcess.spec.ts
@@ -0,0 +1,298 @@
+/**
+ * The gateway's process and the core's link to it, spoken end to end in memory: what one side says, the
+ * other hears as the same call. The relay itself is a stand-in here (gateway/gateway.spec.ts and the socket's
+ * specs hold its rules); what this holds is that nothing is lost or renamed on the way between the processes.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { GatewayEvents, GatewayOps, GatewayPort, WindowRelay } from '../core/api.js'
+import { createGatewayLink } from '../core/gatewayLink.js'
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { TerminalBinaryKind, type TerminalBinaryClear } from '../lib/terminalBinary.js'
+import type { CoreConnection, ServiceProcessOptions } from '../services/process.js'
+import { runGatewayService } from './gatewayProcess.js'
+import type { GatewayHost, StartedGateway } from './start.js'
+
+const STREAM = '00000000-0000-4000-8000-000000000002'
+const clear: TerminalBinaryClear = { kind: TerminalBinaryKind.input, streamId: STREAM, seq: 3, compressed: false, bytes: new Uint8Array([108, 115]) }
+
+function stubGateway() {
+ const port = {
+ connect: vi.fn(), serveThisComputerOnly: vi.fn(), holdRequests: vi.fn(), openRequests: vi.fn(), connected: vi.fn(() => true),
+ broadcast: vi.fn(), commander: vi.fn(), user: vi.fn(), reply: vi.fn(), target: vi.fn(() => true), terminal: vi.fn(() => true),
+ terminalBinary: vi.fn(() => true), observer: vi.fn(() => true), windowOpened: vi.fn(), localClients: vi.fn(), local: vi.fn(async () => {}),
+ device: vi.fn(() => true), deviceClient: vi.fn(), stop: vi.fn(async () => {}),
+ } satisfies GatewayPort
+ const answer = { status: 200, body: { ok: true } }
+ const ops = {
+ status: vi.fn(async () => ({ fingerprint: 'AB12', pairs: [], pending: null })),
+ pair: vi.fn(async () => answer), listPairs: vi.fn(async () => answer), revoke: vi.fn(async () => answer), revokeAll: vi.fn(async () => answer),
+ setRemotePassword: vi.fn(async () => answer), clearRemotePassword: vi.fn(async () => answer), remotePasswordStatus: vi.fn(async () => answer),
+ trustLinkedPeer: vi.fn(async () => answer), groupList: vi.fn(async () => answer), groupSync: vi.fn(async () => answer),
+ groupRemove: vi.fn(async () => answer), devicesList: vi.fn(async () => answer), devicesRemove: vi.fn(async () => answer),
+ devicesHistory: vi.fn(async () => answer), devicesDismiss: vi.fn(async () => answer), devicesRebaseline: vi.fn(async () => answer),
+ wifi: vi.fn(async () => ({ result: { devices: [] } })), dashboardPort: vi.fn(), wifiService: vi.fn(), revokeIdentity: vi.fn(),
+ account: vi.fn(), reachable: vi.fn(),
+ } satisfies GatewayOps
+ const sessions: Array<{ send: ReturnType<typeof vi.fn>; sendBinary: ReturnType<typeof vi.fn>; detach: ReturnType<typeof vi.fn> }> = []
+ const windowRelay = {
+ acquire: vi.fn(async () => { const session = { send: vi.fn(async () => {}), sendBinary: vi.fn(async () => {}), detach: vi.fn() }; sessions.push(session); return session }),
+ acquireIsolated: vi.fn(async () => { throw new RelayConnectError('NO_PEER_LINK') }),
+ invalidate: vi.fn(), invalidateIsolated: vi.fn(),
+ } satisfies WindowRelay
+ return { port, ops, windowRelay, sessions, stop: vi.fn(async () => {}) }
+}
+
+function wire() {
+ let options!: ServiceProcessOptions
+ const gateways: Array<ReturnType<typeof stubGateway>> = []
+ const hosts: GatewayHost[] = []
+ runGatewayService({
+ dataDir: '/data', socketPath: '/data/daemon.sock', machineId: 'computer-1', token: 'token',
+ run: (given) => { options = given; return { stop: vi.fn() } },
+ start: (host) => { hosts.push(host); const stub = stubGateway(); gateways.push(stub); return stub as unknown as StartedGateway },
+ })
+ const heard = {
+ frame: vi.fn(), binary: vi.fn(), client: vi.fn(), disconnected: vi.fn(), observer: vi.fn(), toLocal: vi.fn(), status: vi.fn(),
+ linkDown: vi.fn(), commanders: vi.fn(), commanderJoined: vi.fn(), meta: vi.fn(), notice: vi.fn(), revoked: vi.fn(), busy: vi.fn(),
+ device: vi.fn(), deviceRevoked: vi.fn(), toWindows: vi.fn(),
+ }
+ const tokens = { accessToken: vi.fn(async () => 'token-a') }
+ const backend = vi.fn(async () => ({ status: 200, body: { data: { acct: 'a' } } }))
+ const link = createGatewayLink({
+ events: heard as unknown as GatewayEvents,
+ notify: (frame) => { options.onEvent!(frame.payload as Record<string, unknown>); return true },
+ notifyBinary: (bytes) => { options.onBinary!(bytes); return true },
+ buffered: () => 0,
+ call: async (type, payload) => {
+ try { return { ...await options.requests[type](payload, { local: true, owner: true }) } } catch { return { error: 'SERVICE_FAILED' } }
+ },
+ start: () => ({ machineId: 'machine-1', computerId: 'computer-1', autonomousEnv: 'prod', signedIn: true, account: { machineId: 'machine-1', signIn: null } }),
+ tokens, backend,
+ })
+ const core: CoreConnection = {
+ query: (query, payload = {}) => link.answer(query, payload),
+ notice: (kind, payload = {}) => link.notice({ ...payload, kind }),
+ sendBinary: (bytes) => { link.binary(bytes); return true },
+ }
+ const connect = () => { options.onConnected!(core); link.connected() }
+ const disconnect = () => { options.onDisconnected!(); link.disconnected() }
+ return { link, heard, gateways, hosts, connect, disconnect, tokens, backend, options: () => options }
+}
+
+describe('the gateway\'s process, spoken to by the core', () => {
+ it('builds the gateway only when a core says start, with what the core holds, and again on each start', async () => {
+ const w = wire()
+ w.link.port.holdRequests()
+ w.link.port.connect()
+ w.link.port.localClients(1)
+ w.link.ops.dashboardPort(41000)
+ w.link.ops.reachable(['m2'])
+ w.link.ops.wifiService(true)
+ expect(w.gateways).toHaveLength(0)
+ w.connect()
+ expect(w.gateways).toHaveLength(1)
+ const [gateway] = w.gateways
+ expect(w.hosts[0]).toMatchObject({ machineId: 'machine-1', computerId: 'computer-1', autonomousEnv: 'prod', signedIn: true, account: { machineId: 'machine-1', signIn: null } })
+ expect(gateway.port.holdRequests).toHaveBeenCalled()
+ expect(gateway.port.localClients).toHaveBeenCalledWith(1)
+ expect(gateway.ops.dashboardPort).toHaveBeenCalledWith(41000)
+ expect(gateway.ops.reachable).toHaveBeenCalledWith(['m2'])
+ expect(gateway.ops.wifiService).toHaveBeenCalledWith(true)
+ expect(gateway.port.connect).toHaveBeenCalled()
+ // Its tokens and its reads of the backend are the core's to hand out.
+ expect(await w.hosts[0].tokens.accessToken({ force: true })).toBe('token-a')
+ expect(w.tokens.accessToken).toHaveBeenCalledWith({ force: true })
+ expect(await w.hosts[0].backend('GET', '/api/device-keys?since=0')).toEqual({ status: 200, body: { data: { acct: 'a' } } })
+ w.tokens.accessToken.mockRejectedValueOnce(Object.assign(new Error('session over'), { code: 'INVALID_REFRESH' }))
+ await expect(w.hosts[0].tokens.accessToken()).rejects.toMatchObject({ name: 'AuthSessionError', code: 'INVALID_REFRESH' })
+ // The core going stops it; the next core builds a new one, signed out this time serving this computer only.
+ w.disconnect()
+ expect(gateway.stop).toHaveBeenCalled()
+ await expect(w.hosts[0].tokens.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE' })
+ expect(await w.hosts[0].backend('GET', '/api/device-keys')).toMatchObject({ status: 502 })
+ w.link.port.serveThisComputerOnly()
+ w.link.port.openRequests()
+ w.connect()
+ expect(w.gateways).toHaveLength(2)
+ expect(w.gateways[1].port.serveThisComputerOnly).toHaveBeenCalled()
+ expect(w.gateways[1].port.holdRequests).not.toHaveBeenCalled()
+ })
+
+ it('starts once it knows the core took its link, though the core says start a frame before', () => {
+ const w = wire()
+ // The core's link says start as it takes the connection, before the `connected` that tells this process.
+ w.link.connected()
+ expect(w.gateways).toHaveLength(0)
+ w.options().onConnected!({ query: async () => ({}), notice: () => {}, sendBinary: () => true })
+ expect(w.gateways).toHaveLength(1)
+ // And a core that went before saying it was connected leaves nothing to start.
+ w.options().onDisconnected!()
+ w.link.disconnected()
+ w.link.connected()
+ w.options().onDisconnected!()
+ w.options().onConnected!({ query: async () => ({}), notice: () => {}, sendBinary: () => true })
+ expect(w.gateways).toHaveLength(1)
+ })
+
+ it('carries every frame the core has for remote clients to the gateway, as the same call', async () => {
+ const w = wire()
+ w.connect()
+ const { port } = w.gateways[0]
+ w.link.notice({ kind: 'status', connected: true })
+ w.link.notice({ kind: 'client', connId: 'phone-1', client: { role: 'web', label: null, identity: 'P', direct: false } })
+ w.link.port.broadcast({ type: 'turn_started' })
+ w.link.port.commander({ type: 'commander_event' })
+ w.link.port.user({ type: 'notification' })
+ w.link.port.reply('phone-1', 'agents_list', 'r-1', { agents: [] })
+ w.link.port.target('phone-1', 'viewer_data', { a: 1 })
+ w.link.port.terminal('phone-1', 'terminal_ready', { streamId: STREAM })
+ w.link.port.terminalBinary('phone-1', clear)
+ w.link.port.observer('observer:1', 'observer_frame', { b: 2 })
+ w.link.port.windowOpened()
+ await w.link.port.local('local:w', { type: 'e2ee_pairings_list', payload: {} })
+ w.link.port.device('phone-1', 'autonomous_device_result', { c: 3 })
+ w.link.port.deviceClient('phone-1', 'P')
+ w.link.port.deviceClient('phone-1', null)
+ w.link.ops.revokeIdentity('P')
+ w.link.ops.account({ machineId: 'machine-1', signIn: { epoch: 'e', adopted: false, at: 1 } })
+ w.link.ops.reachable(null)
+ w.link.ops.wifiService(false)
+ await w.link.stop()
+ expect(port.broadcast).toHaveBeenCalledWith({ type: 'turn_started' })
+ expect(port.commander).toHaveBeenCalledWith({ type: 'commander_event' })
+ expect(port.user).toHaveBeenCalledWith({ type: 'notification' })
+ expect(port.reply).toHaveBeenCalledWith('phone-1', 'agents_list', 'r-1', { agents: [] })
+ expect(port.target).toHaveBeenCalledWith('phone-1', 'viewer_data', { a: 1 })
+ expect(port.terminal).toHaveBeenCalledWith('phone-1', 'terminal_ready', { streamId: STREAM })
+ expect(port.terminalBinary).toHaveBeenCalledWith('phone-1', clear)
+ expect(port.observer).toHaveBeenCalledWith('observer:1', 'observer_frame', { b: 2 })
+ expect(port.windowOpened).toHaveBeenCalled()
+ expect(port.local).toHaveBeenCalledWith('local:w', { type: 'e2ee_pairings_list', payload: {} })
+ expect(port.device).toHaveBeenCalledWith('phone-1', 'autonomous_device_result', { c: 3 })
+ expect(port.deviceClient.mock.calls).toEqual([['phone-1', 'P'], ['phone-1', null]])
+ const { ops } = w.gateways[0]
+ expect(ops.revokeIdentity).toHaveBeenCalledWith('P')
+ expect(ops.account).toHaveBeenCalledWith({ machineId: 'machine-1', signIn: { epoch: 'e', adopted: false, at: 1 } })
+ expect(ops.reachable).toHaveBeenCalledWith(null)
+ expect(ops.wifiService).toHaveBeenLastCalledWith(false)
+ // Stopped: what the core says after is for no gateway, and is dropped.
+ expect(w.gateways[0].stop).toHaveBeenCalled()
+ w.link.port.broadcast({ type: 'after' })
+ expect(port.broadcast).toHaveBeenCalledTimes(1)
+ })
+
+ it('tells the core everything the gateway says, as the same call', () => {
+ const w = wire()
+ w.connect()
+ const events = w.hosts[0].events
+ events.frame('phone-1', { type: 'message' }, 'p2p', 'web')
+ events.binary('phone-1', clear)
+ events.client('phone-1', { role: 'device', label: 'Dial', identity: 'P', direct: true })
+ events.disconnected('phone-1')
+ events.observer('observer:1', 'observer_hello', { a: 1 })
+ events.toLocal('local:w', { type: 'x' })
+ events.status(true)
+ events.linkDown()
+ events.commanders(2, null, true)
+ events.commanders(1, 1)
+ events.commanderJoined()
+ events.meta({ gridName: 'grid-1' })
+ events.notice({ type: 'zoo_changed', revision: 4 })
+ events.revoked()
+ events.busy()
+ events.device('dial-1', { type: 'autonomous_device_request' }, { type: 'hello' })
+ events.deviceRevoked('P')
+ events.toWindows({ type: 'device_keys_changed', payload: {} })
+ const { heard } = w
+ expect(heard.frame).toHaveBeenCalledWith('phone-1', { type: 'message' }, 'p2p', 'web')
+ expect(heard.binary).toHaveBeenCalledWith('phone-1', clear)
+ expect(heard.client).toHaveBeenCalledWith('phone-1', { role: 'device', label: 'Dial', identity: 'P', direct: true })
+ expect(heard.disconnected).toHaveBeenCalledWith('phone-1')
+ expect(heard.observer).toHaveBeenCalledWith('observer:1', 'observer_hello', { a: 1 })
+ expect(heard.toLocal).toHaveBeenCalledWith('local:w', { type: 'x' })
+ expect(heard.status).toHaveBeenCalledWith(true)
+ expect(heard.linkDown).toHaveBeenCalled()
+ expect(heard.commanders.mock.calls).toEqual([[2, null, true], [1, 1, false]])
+ expect(heard.commanderJoined).toHaveBeenCalled()
+ expect(heard.meta).toHaveBeenCalledWith({ gridName: 'grid-1' })
+ expect(heard.notice).toHaveBeenCalledWith({ type: 'zoo_changed', revision: 4 })
+ expect(heard.revoked).toHaveBeenCalled()
+ expect(heard.busy).toHaveBeenCalled()
+ expect(heard.device).toHaveBeenCalledWith('dial-1', { type: 'autonomous_device_request' }, { type: 'hello' })
+ expect(heard.deviceRevoked).toHaveBeenCalledWith('P')
+ expect(heard.toWindows).toHaveBeenCalledWith({ type: 'device_keys_changed', payload: {} })
+ })
+
+ it('answers the core\'s commands about the keys from the gateway it runs, and 503 with none running', async () => {
+ const w = wire()
+ expect(await w.link.ops.listPairs()).toEqual({ status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } })
+ w.connect()
+ const { ops } = w.gateways[0]
+ expect(await w.link.ops.status()).toEqual({ fingerprint: 'AB12', pairs: [], pending: null })
+ for (const ask of [
+ () => w.link.ops.pair('CODE'), () => w.link.ops.listPairs(), () => w.link.ops.revoke('1'), () => w.link.ops.revokeAll(),
+ () => w.link.ops.setRemotePassword('pw'), () => w.link.ops.clearRemotePassword(), () => w.link.ops.remotePasswordStatus(),
+ () => w.link.ops.trustLinkedPeer({ pub: 'P', machineId: 'm', label: 'l' }), () => w.link.ops.groupList(), () => w.link.ops.groupSync(),
+ () => w.link.ops.groupRemove('2'), () => w.link.ops.devicesList(), () => w.link.ops.devicesRemove('P'), () => w.link.ops.devicesHistory(),
+ () => w.link.ops.devicesDismiss({ baseline: true }), () => w.link.ops.devicesRebaseline(true, { seq: 2, hash: 'h' }),
+ ]) expect(await ask()).toEqual({ status: 200, body: { ok: true } })
+ expect(ops.pair).toHaveBeenCalledWith('CODE')
+ expect(ops.revoke).toHaveBeenCalledWith('1')
+ expect(ops.setRemotePassword).toHaveBeenCalledWith('pw')
+ expect(ops.trustLinkedPeer).toHaveBeenCalledWith({ pub: 'P', machineId: 'm', label: 'l' })
+ expect(ops.groupRemove).toHaveBeenCalledWith('2')
+ expect(ops.devicesRemove).toHaveBeenCalledWith('P')
+ expect(ops.devicesDismiss).toHaveBeenCalledWith({ baseline: true })
+ expect(ops.devicesRebaseline).toHaveBeenCalledWith(true, { seq: 2, hash: 'h' })
+ expect(await w.link.ops.wifi({ op: 'pair', device: 'dev', code: 'C' })).toEqual({ result: { devices: [] } })
+ expect(ops.wifi).toHaveBeenCalledWith({ op: 'pair', device: 'dev', code: 'C', id: '' })
+ })
+
+ it('opens a window\'s session on another machine, carries it both ways, and fails it as the pool did', async () => {
+ const w = wire()
+ w.connect()
+ const { windowRelay, sessions } = w.gateways[0]
+ const sink = { sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) }
+ const onClosed = vi.fn()
+ const session = await w.link.windowRelay.acquire('m2', 'prod', { type: 'machine_select' }, sink, onClosed)
+ expect(windowRelay.acquire).toHaveBeenCalledWith('m2', 'prod', { type: 'machine_select' }, expect.anything(), expect.any(Function))
+ await session.send({ type: 'agents_list' })
+ await session.sendBinary(clear)
+ expect(sessions[0].send).toHaveBeenCalledWith({ type: 'agents_list' })
+ expect(sessions[0].sendBinary).toHaveBeenCalledWith(clear)
+ // What the other machine sends the window comes back through the core to it.
+ const [, , , poolSink, poolClosed] = windowRelay.acquire.mock.calls[0] as unknown as [string, string, unknown, { sendFrame(f: unknown): boolean; sendBinary(b: Uint8Array): boolean }, (c: number, r: string) => void]
+ poolSink.sendFrame({ type: 'agents_list_result' })
+ expect(poolSink.sendBinary(Uint8Array.of(1, 2))).toBe(true)
+ expect(sink.sendFrame).toHaveBeenCalledWith({ type: 'agents_list_result' })
+ expect(sink.sendBinary).toHaveBeenCalledWith(Uint8Array.of(1, 2))
+ poolClosed(4404, 'NO_PEER_LINK')
+ expect(onClosed).toHaveBeenCalledWith(4404, 'NO_PEER_LINK')
+ // A background one the pool refuses fails with the pool's own words.
+ await expect(w.link.windowRelay.acquireIsolated('m3', 'prod', {}, sink, vi.fn())).rejects.toMatchObject({ message: 'NO_PEER_LINK', closeCode: 1011 })
+ w.link.windowRelay.invalidate('m2')
+ w.link.windowRelay.invalidateIsolated('m3')
+ expect(windowRelay.invalidate).toHaveBeenCalledWith('m2')
+ expect(windowRelay.invalidateIsolated).toHaveBeenCalledWith('m3')
+ // Another, detached by the window; a gateway that stops lets the rest go.
+ const second = await w.link.windowRelay.acquire('m4', 'prod', {}, sink, vi.fn())
+ second.detach()
+ expect(sessions[1].detach).toHaveBeenCalled()
+ await w.link.windowRelay.acquire('m5', 'prod', {}, sink, vi.fn())
+ w.disconnect()
+ expect(sessions[2].detach).toHaveBeenCalled()
+ })
+
+ it('refuses a window while it has not started, and drops what it cannot read', async () => {
+ const w = wire()
+ w.options().onConnected!({ query: async () => ({}), notice: (kind, payload = {}) => w.link.notice({ ...payload, kind }), sendBinary: () => true })
+ w.link.connected = () => {}
+ // The core's link has not said start: there is no pool to open on.
+ w.options().onEvent!({ kind: 'windowOpen', id: 'window-1', machineId: 'm2' })
+ await vi.waitFor(() => expect(w.heard.frame).not.toHaveBeenCalled())
+ w.options().onEvent!({ kind: 'broadcast', frame: { type: 'x' } })
+ w.options().onEvent!({ kind: 'mystery' })
+ w.options().onBinary!(Uint8Array.of(9))
+ expect(w.gateways).toHaveLength(0)
+ })
+})
diff --git a/cli/src/gateway/gatewayProcess.ts b/cli/src/gateway/gatewayProcess.ts
new file mode 100644
index 000000000..2f5b3cefc
--- /dev/null
+++ b/cli/src/gateway/gatewayProcess.ts
@@ -0,0 +1,252 @@
+/**
+ * The gateway in its own process (`harness __service gateway`; the core's side is core/gatewayLink.ts):
+ * the relay, the E2EE sessions and every key this machine holds, where a crash, a hang, a leak or a
+ * hostile frame costs the remote clients and nothing else (docs/design/2026-10-06-core-boundary-next.md,
+ * step 10, R2). Network, crypto and WebRTC in pure JavaScript all run here, off the core's event loop.
+ *
+ * It does nothing until a core takes its link and says `start`: a core that does not run the gateway out
+ * of its process (an older one, under a newer master) keeps its own relay, and two links to the backend
+ * for one machine would fight over its claim. Each `start` builds the gateway afresh (gateway/start.ts),
+ * and the core going away stops it: a core's restart is the relay's, as it always was, so a remote client
+ * that kept its socket opens a new session, as it did when both ran in one process.
+ */
+import type { GatewayAccount, GatewayEvents, WindowRelaySession } from '../core/api.js'
+import { AuthSessionError } from '../lib/authSession.js'
+import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcess } from '../services/process.js'
+import { startGateway, type StartedGateway } from './start.js'
+
+type Payload = Record<string, unknown>
+
+export interface GatewayServiceOptions {
+ dataDir: string
+ socketPath: string
+ machineId: string
+ token: string
+ /** Swapped in tests for one that does not touch the real socket or process. */
+ run?: typeof runServiceProcess
+ /** Swapped in tests for a gateway that dials nothing. */
+ start?: typeof startGateway
+}
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : '')
+const record = (value: unknown): Payload => (value && typeof value === 'object' && !Array.isArray(value) ? value as Payload : {})
+const SESSION_CODES = new Set(['MISSING', 'INVALID_REFRESH', 'UNAVAILABLE'])
+
+export function runGatewayService(options: GatewayServiceOptions): ServiceProcess {
+ let core: CoreConnection | null = null
+ let running: StartedGateway | null = null
+ /** The windows on the core's side working on other machines through this gateway, by the core's id. */
+ const windows = new Map<string, WindowRelaySession>()
+
+ const notice = (kind: string, payload: Payload = {}): void => { core?.notice?.(kind, payload) }
+ const events: GatewayEvents = {
+ frame: (connId, frame, transport, role) => notice('frame', { connId, frame, transport, role }),
+ binary: (connId, clear) => {
+ const local = encodeTerminalLocal(clear)
+ const bytes = local && encodeGatewayBinary(GatewayBinary.remote, connId, local)
+ if (bytes) core?.sendBinary?.(bytes)
+ },
+ client: (connId, client) => notice('client', { connId, client }),
+ disconnected: (connId) => notice('disconnected', { connId }),
+ observer: (connId, type, payload) => notice('observer', { connId, type, payload }),
+ toLocal: (connId, frame) => notice('toLocal', { connId, frame }),
+ status: (connected) => notice('status', { connected }),
+ linkDown: () => notice('linkDown'),
+ commanders: (count, active, recheck) => notice('commanders', { count, active, recheck: recheck === true }),
+ commanderJoined: () => notice('commanderJoined'),
+ meta: (meta) => notice('meta', { meta }),
+ notice: (backendNotice) => notice('notice', { notice: backendNotice }),
+ revoked: () => notice('revoked'),
+ busy: () => notice('busy'),
+ device: (connId, frame, opened) => notice('device', { connId, frame, opened }),
+ deviceRevoked: (identity) => notice('deviceRevoked', { identity }),
+ toWindows: (frame) => notice('toWindows', { frame }),
+ }
+
+ /** The account's tokens, from the core (`core.account`): a refusal comes back as the session's own error. */
+ const accessToken = async (opts: { force?: boolean; failedToken?: string } = {}): Promise<string> => {
+ if (!core) throw new AuthSessionError('not connected to the core', 'UNAVAILABLE')
+ const answer = await core.query('access_token', opts)
+ if (typeof answer.token === 'string') return answer.token
+ const code = SESSION_CODES.has(text(answer.code)) ? text(answer.code) as 'MISSING' | 'INVALID_REFRESH' | 'UNAVAILABLE' : 'UNAVAILABLE'
+ throw new AuthSessionError(text(answer.message) || 'the core could not hand out a token', code)
+ }
+
+ /** The gateway stopped: its link closed, its windows' sessions let go. Not waited on: what comes after it
+ * on the link (a new `start`) must not wait for the old link's goodbye. */
+ let pendingStart: Payload | null = null
+ const stop = (): void => {
+ pendingStart = null
+ const was = running
+ running = null
+ for (const session of windows.values()) session.detach()
+ windows.clear()
+ void was?.stop().catch((error: unknown) => console.warn(`[gateway] stopping: ${error instanceof Error ? error.message : String(error)}`))
+ }
+
+ const begin = (payload: Payload): void => {
+ stop()
+ const started = (options.start ?? startGateway)({
+ events,
+ machineId: text(payload.machineId),
+ computerId: text(payload.computerId),
+ autonomousEnv: text(payload.autonomousEnv) || 'prod',
+ signedIn: payload.signedIn === true,
+ tokens: { accessToken },
+ backend: async (method, path) => {
+ if (!core) return { status: 502, body: { success: false, error: { code: 'BACKEND_UNREACHABLE', message: 'not connected to the core' } } }
+ const answer = await core.query('backend', { method, path })
+ return { status: typeof answer.status === 'number' ? answer.status : 502, body: record(answer.body) }
+ },
+ account: (payload.account as GatewayAccount | null) ?? { machineId: null, signIn: null },
+ })
+ running = started
+ // Held first, so that nothing the link brings in is answered before the core is ready.
+ if (payload.requestsOpen === false) started.port.holdRequests()
+ started.port.localClients(Number(payload.localClients) || 0)
+ if (typeof payload.dashboardPort === 'number') started.ops.dashboardPort(payload.dashboardPort)
+ if (Array.isArray(payload.reachable)) started.ops.reachable(payload.reachable as string[])
+ if (payload.wifiService === true) started.ops.wifiService(true)
+ if (payload.dial === 'connect') started.port.connect()
+ else if (payload.dial === 'local') started.port.serveThisComputerOnly()
+ }
+
+ const openWindow = async (payload: Payload): Promise<void> => {
+ const id = text(payload.id)
+ const pool = running?.windowRelay
+ try {
+ if (!pool) throw new RelayConnectError('the relay is restarting', 1013)
+ const acquire = payload.isolated === true ? pool.acquireIsolated.bind(pool) : pool.acquire.bind(pool)
+ const session = await acquire(text(payload.machineId), text(payload.autonomousEnv), record(payload.frame), {
+ sendFrame: (frame) => { notice('windowFrame', { id, frame }); return true },
+ sendBinary: (bytes) => {
+ const framed = encodeGatewayBinary(GatewayBinary.window, id, bytes)
+ return !!framed && !!core?.sendBinary?.(framed)
+ },
+ }, (code, reason) => {
+ windows.delete(id)
+ notice('windowClosed', { id, code, reason })
+ })
+ windows.set(id, session)
+ notice('windowOpened', { id })
+ } catch (error) {
+ notice('windowFailed', {
+ id,
+ ...(error instanceof RelayConnectError && error.closeCode ? { code: error.closeCode } : {}),
+ reason: error instanceof Error ? error.message : 'relay failed',
+ })
+ }
+ }
+
+ /**
+ * What the core tells the gateway (`service_event`). Each is taken as it arrives, in order: the service
+ * link hands them on without waiting on the last, so nothing here waits either, or a later frame would
+ * overtake it. What takes time (a window's dial) runs on, and says when it is done.
+ */
+ const onEvent = (payload: Payload): void => {
+ const kind = text(payload.kind)
+ // The core says start as it takes the link, a frame before it says `connected`: started then, the first
+ // dial would ask the core for a token on a link this process does not know is up yet, and wait a second
+ // to try again. Started once it knows.
+ if (kind === 'start') { if (core) begin(payload); else pendingStart = payload; return }
+ if (kind === 'stop') { stop(); return }
+ if (kind === 'windowOpen') { void openWindow(payload); return }
+ const gateway = running
+ if (!gateway) return
+ const { port, ops } = gateway
+ const connId = text(payload.connId)
+ switch (kind) {
+ case 'connect': port.connect(); return
+ case 'thisComputerOnly': port.serveThisComputerOnly(); return
+ case 'hold': port.holdRequests(); return
+ case 'open': port.openRequests(); return
+ case 'broadcast': port.broadcast(record(payload.frame)); return
+ case 'commander': port.commander(record(payload.frame)); return
+ case 'user': port.user(record(payload.frame)); return
+ case 'reply': port.reply(connId, text(payload.type), payload.requestId, record(payload.payload)); return
+ case 'target': port.target(connId, text(payload.type), record(payload.payload)); return
+ case 'terminal': port.terminal(connId, text(payload.type), record(payload.payload)); return
+ case 'observer': port.observer(connId, text(payload.type), record(payload.payload)); return
+ case 'windowOpened': port.windowOpened(); return
+ case 'localClients': port.localClients(Number(payload.count) || 0); return
+ case 'localFrame': void port.local(connId, record(payload.frame)); return
+ case 'device': port.device(connId, text(payload.type), record(payload.payload)); return
+ case 'deviceClient': port.deviceClient(connId, typeof payload.identity === 'string' ? payload.identity : null); return
+ case 'dashboardPort': ops.dashboardPort(Number(payload.port)); return
+ case 'wifiService': ops.wifiService(payload.on === true); return
+ case 'revokeIdentity': ops.revokeIdentity(text(payload.identity)); return
+ case 'account': ops.account(payload.account as GatewayAccount); return
+ case 'reachable': ops.reachable(Array.isArray(payload.machineIds) ? payload.machineIds as string[] : null); return
+ case 'windowSend': void windows.get(text(payload.id))?.send(record(payload.frame)); return
+ case 'windowDetach': { const id = text(payload.id); windows.get(id)?.detach(); windows.delete(id); return }
+ case 'windowInvalidate':
+ if (payload.isolated === true) gateway.windowRelay.invalidateIsolated(text(payload.machineId))
+ else gateway.windowRelay.invalidate(text(payload.machineId))
+ return
+ default:
+ console.warn(`[gateway] an unknown event from the core was ignored: ${JSON.stringify(kind).slice(0, 80)}`)
+ }
+ }
+
+ /** The core's terminal bytes for a remote client, or for a window's session on another machine. */
+ const onBinary = (raw: Uint8Array): void => {
+ const decoded = decodeGatewayBinary(raw)
+ const clear = decoded && decodeTerminalLocal(decoded.bytes)
+ if (!decoded || !clear) return
+ if (decoded.kind === GatewayBinary.window) void windows.get(decoded.id)?.sendBinary(clear)
+ else running?.port.terminalBinary(decoded.id, clear)
+ }
+
+ /** The core's commands about the keys (`GatewayOps`), answered as their routes answer them. */
+ const ops = () => {
+ if (!running) throw new Error('the gateway has not started')
+ return running.ops
+ }
+ const requests = {
+ [GATEWAY_CALLS.status]: async () => ({ ...await ops().status() }),
+ [GATEWAY_CALLS.pair]: async (p: Payload) => ({ ...await ops().pair(text(p.code)) }),
+ [GATEWAY_CALLS.listPairs]: async () => ({ ...await ops().listPairs() }),
+ [GATEWAY_CALLS.revoke]: async (p: Payload) => ({ ...await ops().revoke(text(p.id)) }),
+ [GATEWAY_CALLS.revokeAll]: async () => ({ ...await ops().revokeAll() }),
+ [GATEWAY_CALLS.setRemotePassword]: async (p: Payload) => ({ ...await ops().setRemotePassword(text(p.password)) }),
+ [GATEWAY_CALLS.clearRemotePassword]: async () => ({ ...await ops().clearRemotePassword() }),
+ [GATEWAY_CALLS.remotePasswordStatus]: async () => ({ ...await ops().remotePasswordStatus() }),
+ [GATEWAY_CALLS.trustLinkedPeer]: async (p: Payload) => ({ ...await ops().trustLinkedPeer(record(p.peer) as { pub: string; machineId: string; label: string }) }),
+ [GATEWAY_CALLS.groupList]: async () => ({ ...await ops().groupList() }),
+ [GATEWAY_CALLS.groupSync]: async () => ({ ...await ops().groupSync() }),
+ [GATEWAY_CALLS.groupRemove]: async (p: Payload) => ({ ...await ops().groupRemove(text(p.selector)) }),
+ [GATEWAY_CALLS.devicesList]: async () => ({ ...await ops().devicesList() }),
+ [GATEWAY_CALLS.devicesRemove]: async (p: Payload) => ({ ...await ops().devicesRemove(text(p.pub)) }),
+ [GATEWAY_CALLS.devicesHistory]: async () => ({ ...await ops().devicesHistory() }),
+ [GATEWAY_CALLS.devicesDismiss]: async (p: Payload) => ({ ...await ops().devicesDismiss(record(p.body)) }),
+ [GATEWAY_CALLS.devicesRebaseline]: async (p: Payload) => ({
+ ...await ops().devicesRebaseline(p.confirm === true, p.head as { seq: number; hash: string } | undefined),
+ }),
+ [GATEWAY_CALLS.wifi]: async (p: Payload) => ({
+ ...await ops().wifi({ op: text(p.op) as 'discover' | 'pair' | 'pairStatus' | 'list' | 'revoke', device: text(p.device), code: text(p.code), id: text(p.id) }),
+ }),
+ }
+
+ return (options.run ?? runServiceProcess)({
+ name: 'gateway',
+ socketPath: options.socketPath,
+ machineId: options.machineId,
+ token: options.token,
+ requests,
+ onEvent,
+ onBinary,
+ onConnected: (connection) => {
+ core = connection
+ const start = pendingStart
+ pendingStart = null
+ if (start) begin(start)
+ },
+ onDisconnected: () => {
+ core = null
+ stop()
+ },
+ })
+}
diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.ts
new file mode 100644
index 000000000..5b6243e47
--- /dev/null
+++ b/cli/src/gateway/start.ts
@@ -0,0 +1,360 @@
+/**
+ * The gateway, started: everything that holds this machine's keys or speaks for them, built in one place
+ * so that it runs the same in the core's process (`HARNESSD_SERVICES=none`, or a master that does not run
+ * it) and in its own (gateway/gatewayProcess.ts). It is what `runForeground` wired by hand before the relay
+ * left the core (docs/design/2026-10-06-core-boundary-next.md, step 10, R2), moved as it was:
+ *
+ * - the relay (gateway/gateway.ts): the backend link, the E2EE manager and its sessions, P2P;
+ * - the windows' own sessions to the owner's other machines (lib/remoteRelay.ts `RemoteRelayPool`);
+ * - the trust group (lib/e2ee/groupSyncer.ts) and the account's device key log (deviceLogSyncer.ts);
+ * - the Wi-Fi device's direct links (lib/autonomous-device/direct.ts), which carry its E2EE sessions;
+ * - the daemon's own commands about the keys (`harness pair`, `unpair`, `group`, `devices`, …).
+ *
+ * The core gives it what it cannot hold itself: its events (`GatewayEvents`), the account's tokens and the
+ * backend's REST answers, both through `core.account` (a service holds no credential), and a few facts
+ * that it says again whenever they change (`GatewayOps.account`, `reachable`, …).
+ */
+import { renameSync } from 'node:fs'
+import { hostname } from 'node:os'
+import { join } from 'node:path'
+import { env } from '../config/env.js'
+import type { GatewayAccount, GatewayEvents, GatewayOps, HttpAnswer, WindowRelay } from '../core/api.js'
+import { AutonomousDeviceDirect } from '../lib/autonomous-device/direct.js'
+import { startDevicePart } from '../lib/autonomous-device/parts.js'
+import type { AuthSessionManager } from '../lib/authSession.js'
+import { thisDeviceLabel } from '../lib/daemonState.js'
+import { b64d, b64e, fingerprint } from '../lib/e2ee/core.js'
+import { DeviceLogStore } from '../lib/e2ee/deviceLogStore.js'
+import { DeviceLogSyncer, type DeviceLogFetched } from '../lib/e2ee/deviceLogSyncer.js'
+import { GroupSyncer, relayRequester, SELF_STAMP } from '../lib/e2ee/groupSyncer.js'
+import { MachinePeerStore } from '../lib/e2ee/machinePeers.js'
+import { E2eeStore } from '../lib/e2ee/store.js'
+import { TrustGroupStore, type GroupMember } from '../lib/e2ee/trustGroup.js'
+import { RemoteRelayPool } from '../lib/remoteRelay.js'
+import { RelayGateway } from './gateway.js'
+
+/** What the gateway needs of the core, in whichever process it runs. */
+export interface GatewayHost {
+ events: GatewayEvents
+ /** The id this daemon serves under: the account's machine id signed in, the computer's own signed out. */
+ machineId: string
+ computerId: string
+ autonomousEnv: string
+ /** Signed in when the core started: the trust group syncs, and the device key log registers this machine. */
+ signedIn: boolean
+ /** The account's tokens, as `core.account` hands them out; it never holds the session itself. */
+ tokens: Pick<AuthSessionManager, 'accessToken'>
+ /** A read of the backend's REST API under the account's session, as the core answers it. */
+ backend(method: 'GET', path: string): Promise<HttpAnswer>
+ /** The account's sign-in as it stood when the core started; `GatewayOps.account` says it again. */
+ account: GatewayAccount
+}
+
+export interface StartedGateway {
+ port: RelayGateway
+ ops: GatewayOps
+ windowRelay: WindowRelay
+ stop(): Promise<void>
+}
+
+/** Pairing errors as `harness pair` maps them to HTTP. */
+const PAIR_STATUS: Record<string, number> = {
+ NO_INTENT: 409, EXPIRED: 409, CODE_MISMATCH: 403, BACKEND_DOWN: 503,
+ RATE_LIMITED: 429, BUSY: 409, TIMEOUT: 504,
+}
+
+export function startGateway(host: GatewayHost): StartedGateway {
+ let account = host.account
+ let reachable: Set<string> | null = null
+ const gateway = new RelayGateway({
+ machineId: host.machineId, auth: host.tokens, computerId: host.computerId, autonomousEnv: host.autonomousEnv, core: host.events,
+ })
+
+ /** The identity this machine was removed under is never used again: the next start mints a new one. */
+ const spendIdentity = (): void => {
+ const identityFile = join(env.ADAPTER_DATA_DIR, 'e2e', 'identity.json')
+ try { renameSync(identityFile, `${identityFile}.removed-${Date.now()}`) } catch { /* already gone */ }
+ }
+ // Same on-disk identity `harness remote-password set`/`link connect` use (E2eeStore.init() is
+ // idempotent per file, so a separate in-memory instance here just reads the one this machine
+ // already has).
+ const relayIdentityStore = new E2eeStore()
+ relayIdentityStore.init()
+ const relayPeers = new MachinePeerStore()
+ // The trust group and the device key log are built below; the pool's callbacks reach them through these.
+ let groupSyncer: GroupSyncer | null = null
+ let devLogSyncer: DeviceLogSyncer | null = null
+ const relayPool = new RemoteRelayPool(
+ host.tokens,
+ env.BACKEND_WS_URL.replace(/\/$/, ''),
+ relayIdentityStore.getIdentity(),
+ relayPeers,
+ {
+ onSessionReady: (machineId) => groupSyncer?.sessionOpened(machineId),
+ // A machine the account's device key log names under this very key will trust us as soon as it
+ // reads the log: keep its pin through a few denials, and nudge it (and us) to read.
+ expectsTrust: (machineId, pub) => {
+ const m = devLogSyncer?.list().members.find((x) => x.pub === pub)
+ const expected = !!m && m.kind === 'machine' && m.machineId === machineId && !devLogSyncer?.suspendedKeys().includes(pub)
+ if (expected) void devLogSyncer?.refresh()
+ return expected
+ },
+ },
+ )
+ /** This machine as its trust group knows it — see groupSyncer.ts's SELF_STAMP for the stamp. */
+ const groupSelf = (): GroupMember => {
+ const machineId = account.machineId
+ return { pub: b64e(relayIdentityStore.getIdentity().pub), kind: 'machine', label: hostname(), at: SELF_STAMP, ...(machineId ? { machineId } : {}) }
+ }
+ // Every machine and phone linked to this one, directly or through another member, trusts every other:
+ // rosters are swapped over any session that opens, and pushed on whenever they change.
+ const syncer = new GroupSyncer({
+ store: new TrustGroupStore(),
+ peers: new MachinePeerStore(),
+ self: groupSelf,
+ trust: (peer) => gateway.trustPeer(peer),
+ untrust: (pub) => { gateway.untrustPeer(pub) },
+ paired: () => gateway.pairedPeers(),
+ request: relayRequester(relayPool, () => host.autonomousEnv),
+ dropSessions: (machineId) => { relayPool.invalidate(machineId); relayPool.invalidateIsolated(machineId) },
+ suspended: () => new Set(devLogSyncer?.suspendedKeys() ?? []),
+ // Only a list the backend answered says who is offline; otherwise try every member.
+ reachable: () => reachable,
+ log: (line) => console.log(line),
+ })
+ groupSyncer = syncer
+ gateway.groupSync = syncer
+ gateway.onPeerLinked = (peer) => syncer.linked(peer)
+ gateway.onUnpaired = (pub) => {
+ syncer.unpaired(pub)
+ // Unpairing a device here takes it out of the account's log too — or the log would trust it again.
+ void devLogSyncer?.remove(pub)
+ }
+ if (host.signedIn) syncer.start()
+ const devlog = new DeviceLogSyncer({
+ store: new DeviceLogStore(),
+ identity: () => { const id = relayIdentityStore.getIdentity(); return { pub: b64e(id.pub), priv: id.priv } },
+ self: () => ({ machineId: account.machineId, label: thisDeviceLabel() }),
+ // Which sign-in by hand this machine is under (minted by `harness login`, never a backend answer —
+ // the machine id is one): the device log can start over only when THIS changes.
+ signIn: () => account.signIn,
+ fetch: async (since) => {
+ const r = await host.backend('GET', `/api/device-keys?since=${since}`)
+ const data = r.status === 200 ? r.body.data as Partial<DeviceLogFetched> | undefined : undefined
+ const head = data?.head as { seq?: unknown; hash?: unknown } | undefined
+ if (!data || typeof data.acct !== 'string' || !Array.isArray(data.entries) || typeof head?.seq !== 'number'
+ || !Number.isSafeInteger(head.seq) || head.seq < 0 || typeof head.hash !== 'string') return null
+ return { acct: data.acct, head: { seq: head.seq, hash: head.hash }, entries: data.entries }
+ },
+ append: async (entry) => {
+ const p = await gateway.appendDeviceLog(entry as unknown as Record<string, unknown>)
+ if (!p) return null
+ const head = p.head as { seq?: unknown; hash?: unknown } | undefined
+ const parsedHead = typeof head?.seq === 'number' && typeof head.hash === 'string' ? { seq: head.seq, hash: head.hash } : undefined
+ if (typeof p.error === 'string') return { error: p.error, ...(parsedHead ? { head: parsedHead } : {}) }
+ return parsedHead ? { head: parsedHead } : null
+ },
+ adopt: (members) => syncer.adoptFromLog(members),
+ drop: (pub) => { syncer.remove(pub) },
+ // Snapshotted once, when this machine joins the log: what it already trusts then is never news.
+ trustedNow: () => [...new Set([
+ ...gateway.pairedPeers().map((p) => p.identityPub),
+ ...relayPeers.list().map((p) => p.pub),
+ ...syncer.roster().members.map((m) => m.pub),
+ ])],
+ tombstoned: (pub) => !!syncer.tombstoned(pub),
+ blocked: (pub) => !!syncer.isBlocked(pub),
+ announce: (m) => {
+ const fp = fingerprint(b64d(m.pub))
+ console.log(`[devlog] NEW DEVICE on this account: ${m.label || '(no name)'} (${m.kind}) ${fp} — not yours? harness devices remove ${fp}`)
+ host.events.toWindows({ type: 'device_key_added', payload: { pub: m.pub, label: m.label, kind: m.kind, machineId: m.machineId, at: m.addedAt, fingerprint: fp } })
+ },
+ removed: (n) => {
+ if (n.selfRemoved) console.log(`[devlog] ${n.label || '(no name)'} signed out of this account (${n.fingerprint})`)
+ else if (n.signerPending) console.log(`[devlog] ⚠ ${n.label || '(no name)'} (${n.fingerprint}) was removed by a NEW device you have not looked at: ${n.signerLabel || 'another device'} (${n.signerFingerprint}) — not yours? harness devices remove ${n.signerFingerprint}`)
+ else console.log(`[devlog] ${n.label || '(no name)'} (${n.fingerprint}) was removed from this account by ${n.signerLabel || 'another device'}`)
+ host.events.toWindows({ type: 'device_key_removed', payload: { ...n } })
+ },
+ conflict: (c) => {
+ host.events.toWindows({ type: 'device_conflict', payload: { pub: c.pub, label: c.label, fingerprint: c.fingerprint, addedAt: c.addedAt, afterJoin: c.afterJoin } })
+ },
+ suspend: (pubs) => syncer.suspend(pubs),
+ resume: () => syncer.resume(),
+ signedOut: () => {
+ // This machine's key was removed from the account: it is signed out, and comes back — after a
+ // new `harness login` — with a NEW key, which every other device announces as a new device.
+ console.log('[devlog] this machine was removed from the account\'s devices — signing out')
+ spendIdentity()
+ host.events.revoked()
+ },
+ changed: () => host.events.toWindows({ type: 'device_keys_changed', payload: {} }),
+ log: (line) => console.log(line),
+ })
+ devLogSyncer = devlog
+ syncer.devlog = devlog
+ // Removed while online: the backend's `machine_revoked` arrives before this machine reads the log, and
+ // stops it. The key is spent all the same, or the next `harness login` would come back under a banned
+ // key and be signed out again.
+ gateway.onDeviceRemoved = (pub) => {
+ if (pub === b64e(relayIdentityStore.getIdentity().pub)) spendIdentity()
+ }
+ // A removal of another key under this machine id — the earlier install a reinstall waits behind — is
+ // not this machine signed out: the log re-read that follows registers this key (deviceLogSyncer).
+ gateway.isOwnDeviceKey = (pub) => pub === b64e(relayIdentityStore.getIdentity().pub)
+ // A removal the trust group carried in — typically `harness group remove` on a machine that predates
+ // the log — goes into the log as well, signed by this machine, so a device that only reads the log
+ // stops trusting that key too. A key the log no longer has is left alone.
+ syncer.onDropped = (pub) => {
+ if (devlog.list().members.some((m) => m.pub === pub && !m.self)) void devlog.remove(pub)
+ }
+ gateway.onDeviceKeysChanged = () => { void devlog.refresh() }
+ let devlogTimer: ReturnType<typeof setInterval> | null = null
+ if (host.signedIn) {
+ // Every time the link comes up: a sign-in from before the log existed joins it with no one doing
+ // anything, and one that joined already only reads what it missed while offline.
+ gateway.onLinkUp = () => { void devlog.register() }
+ devlogTimer = setInterval(() => { void devlog.refresh() }, 10 * 60_000)
+ devlogTimer.unref()
+ }
+
+ // The Wi-Fi device's direct links, which carry its E2EE sessions: only while its service runs in the
+ // core, or a device it connected would be answered by nothing.
+ let direct: AutonomousDeviceDirect | undefined
+ gateway.onDirectDeviceRevoked = fp => direct?.revoked(fp)
+ const startDirect = (): void => {
+ if (direct) return
+ direct = startDevicePart('Wi-Fi device link', () => new AutonomousDeviceDirect({
+ machineId: host.machineId, label: hostname(),
+ receive: (connId, frame, pairing) => gateway.receiveDirectDevice(connId, frame, pairing),
+ attach: (connId, send) => gateway.attachDirectDevice(connId, send),
+ detach: connId => gateway.detachDirectDevice(connId),
+ pending: () => gateway.pendingPair(), pendingConnection: () => gateway.e2ee.pendingConnection(),
+ authenticatedFingerprint: connId => { const pub = gateway.e2ee.sessionIdentity(connId); return pub ? fingerprint(b64d(pub)) : null },
+ pairedFingerprint: connId => gateway.pairedDirectFingerprint(connId),
+ pair: code => gateway.pair(code), paired: () => gateway.listPairs(),
+ }, env.ADAPTER_DATA_DIR))
+ direct?.start()
+ }
+
+ /** A trust-group member by machine id, list number, or fingerprint (full or unique prefix). */
+ const findGroupMember = (selector: string): { ok: true; pub: string; label: string; fingerprint: string } | { ok: false; error: 'NOT_FOUND' | 'AMBIGUOUS' } => {
+ const members = new TrustGroupStore().list()
+ const norm = (v: string): string => v.toUpperCase().replace(/[·\s-]/g, '')
+ const byIndex = /^\d+$/.test(selector) ? members[Number(selector) - 1] : undefined
+ const byMachine = members.find((m) => m.machineId === selector)
+ const hit = byMachine ?? byIndex ?? (() => {
+ const matches = members.filter((m) => norm(m.fingerprint).startsWith(norm(selector)))
+ return matches.length > 1 ? 'AMBIGUOUS' as const : matches[0]
+ })()
+ if (hit === 'AMBIGUOUS') return { ok: false, error: 'AMBIGUOUS' }
+ if (!hit || !selector.trim()) return { ok: false, error: 'NOT_FOUND' }
+ return { ok: true, pub: hit.pub, label: hit.label, fingerprint: hit.fingerprint }
+ }
+ const refusal = (error: unknown): { refused: { code: string; message: string } } =>
+ ({ refused: { code: String((error as { code?: unknown }).code ?? 'INTERNAL'), message: error instanceof Error ? error.message : String(error) } })
+ const devicePairs = () => gateway.listPairs().filter((p) => p.role === 'device')
+
+ const ops: GatewayOps = {
+ status: async () => ({ fingerprint: gateway.fingerprint(), pairs: gateway.listPairs(), pending: gateway.pendingPair() as Record<string, unknown> | null }),
+ // `harness pair <code>` → run CPace toward the waiting browser; map the result to an HTTP outcome.
+ pair: async (code) => {
+ const r = await gateway.pair(code)
+ if (r.ok) return { status: 200, body: { label: r.label, fingerprint: r.fingerprint } }
+ return { status: PAIR_STATUS[r.error] ?? 400, body: { error: r.error } }
+ },
+ listPairs: async () => ({ status: 200, body: { pairs: gateway.listPairs() } }),
+ revoke: async (id) => {
+ const r = gateway.revoke(id)
+ if (r.ok) return { status: 200, body: { label: r.label, fingerprint: r.fingerprint } }
+ return { status: r.error === 'AMBIGUOUS' ? 409 : 404, body: { error: r.error } }
+ },
+ revokeAll: async () => ({ status: 200, body: gateway.revokeAll() }),
+ // `harness remote-password set|clear|status` — mutate/read the running daemon's live E2EE state
+ // directly, so `harness link connect` from another machine sees a just-set password immediately.
+ setRemotePassword: async (password) => ({ status: 200, body: await gateway.setRemotePassword(password) }),
+ clearRemotePassword: async () => { gateway.clearRemotePassword(); return { status: 200, body: { ok: true } } },
+ remotePasswordStatus: async () => ({ status: 200, body: gateway.remotePasswordStatus() }),
+ trustLinkedPeer: async (peer) => {
+ gateway.trustPeer({ ...peer, kind: 'machine' })
+ syncer.linked({ ...peer, kind: 'machine' })
+ return { status: 200, body: { ok: true } }
+ },
+ groupList: async () => ({ status: 200, body: { self: groupSelf(), members: new TrustGroupStore().list() } }),
+ groupSync: async () => { void syncer.syncAll(); return { status: 200, body: { ok: true } } },
+ groupRemove: async (selector) => {
+ const found = findGroupMember(selector)
+ if (!found.ok) return { status: found.error === 'AMBIGUOUS' ? 409 : 404, body: { error: found.error } }
+ syncer.remove(found.pub)
+ // And out of the device key log, or the next read of it would put the device back.
+ void devlog.remove(found.pub)
+ return { status: 200, body: { label: found.label, fingerprint: found.fingerprint } }
+ },
+ devicesList: async () => {
+ // When each key last opened a session, from the backend — a hint for removing apps not used in a
+ // long while. Without it the list is still the list.
+ const seen = await host.backend('GET', '/api/device-keys/seen').catch(() => null)
+ const lastSeen = seen?.status === 200 ? (seen.body.data as { seen?: unknown } | undefined)?.seen : undefined
+ return { status: 200, body: { ...devlog.list(), lastSeen: lastSeen && typeof lastSeen === 'object' ? lastSeen : {} } }
+ },
+ devicesRemove: async (pub) => {
+ syncer.remove(pub)
+ const r = await devlog.remove(pub)
+ if (r.ok) return { status: 200, body: { ok: true } }
+ const status = r.error === 'NOT_IN_LOG' ? 404 : r.error === 'UNAVAILABLE' ? 503 : 409
+ return { status, body: { error: r.error, ...(r.detail ? { detail: r.detail } : {}) } }
+ },
+ devicesHistory: async () => ({ status: 200, body: { ...(await devlog.history()) } }),
+ devicesDismiss: async (body) => { devlog.dismiss(body); return { status: 200, body: { ok: true } } },
+ devicesRebaseline: async (confirm, head) => {
+ const r = await devlog.rebaseline(confirm, head)
+ if (r && 'error' in r) return { status: 409, body: { error: r.error } }
+ return r ? { status: 200, body: { ...r, applied: confirm } } : { status: 502, body: { error: 'LOG_UNAVAILABLE' } }
+ },
+ wifi: async ({ op, device, code, id }) => {
+ try {
+ if (op === 'discover') {
+ if (!direct) throw Object.assign(new Error('The Wi-Fi device link is not running on this computer: its state could not be read. See the daemon\'s log.'), { code: 'UNAVAILABLE' })
+ return { result: { devices: await direct.discover() } }
+ }
+ if (op === 'pair') {
+ if (!direct) throw Object.assign(new Error('The Wi-Fi device link is not running on this computer: its state could not be read. See the daemon\'s log.'), { code: 'UNAVAILABLE' })
+ return { result: await direct.pair(String(device), String(code)) }
+ }
+ if (op === 'pairStatus') {
+ const pending = gateway.pendingPair()
+ return { result: pending?.role === 'device' ? { state: pending.active ? 'running' : 'waiting', pairId: pending.pairId, deviceLabel: pending.label, expiresAt: pending.expiresAt } : { state: 'idle' } }
+ }
+ if (op === 'list') return { result: { devices: devicePairs().map(p => ({ ...p, id: p.fingerprint })) } }
+ if (!devicePairs().some(p => p.fingerprint === id)) throw Object.assign(new Error('Device pairing not found'), { code: 'UNKNOWN_DEVICE' })
+ const result = gateway.revoke(String(id))
+ if (!result.ok) throw Object.assign(new Error(result.error), { code: result.error })
+ return { result: { revoked: 1 } }
+ } catch (error) { return refusal(error) }
+ },
+ dashboardPort: (port) => gateway.setDashboardPort(port),
+ wifiService: (on) => {
+ if (on) { startDirect(); return }
+ direct?.stop()
+ direct = undefined
+ },
+ revokeIdentity: (identity) => { gateway.e2ee.revoke(fingerprint(b64d(identity))) },
+ account: (next) => {
+ account = next
+ if (host.signedIn) void devlog.register()
+ },
+ reachable: (machineIds) => { reachable = machineIds ? new Set(machineIds) : null },
+ }
+
+ return {
+ port: gateway,
+ ops,
+ windowRelay: relayPool,
+ stop: async () => {
+ if (devlogTimer) clearInterval(devlogTimer)
+ syncer.stop()
+ direct?.stop()
+ relayPool.close()
+ await gateway.stop()
+ },
+ }
+}
diff --git a/cli/src/gateway/upstream.ts b/cli/src/gateway/upstream.ts
index 67d67cafc..1466e610e 100644
--- a/cli/src/gateway/upstream.ts
+++ b/cli/src/gateway/upstream.ts
@@ -79,7 +79,7 @@ export interface UpstreamEvents {
export interface UpstreamOptions {
machineId: string
/** The daemon's session; without one (isolated unit tests only), `machineId` is the token. */
- auth?: AuthSessionManager
+ auth?: Pick<AuthSessionManager, 'accessToken'>
computerId?: string
autonomousEnv?: string
events: UpstreamEvents
@@ -90,7 +90,7 @@ export class UpstreamLink {
private connecting = false
/** A 401 on the upgrade is being answered with a token refresh; that refresh owns the next connect. */
private retryingAuth = false
- private readonly auth: AuthSessionManager
+ private readonly auth: Pick<AuthSessionManager, 'accessToken'>
/** Constructor-without-auth is retained for isolated unit tests only. */
private readonly testToken?: string
private readonly url: string
diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.ts
index b91126f08..3f5f5e934 100644
--- a/cli/src/harnessd/services.ts
+++ b/cli/src/harnessd/services.ts
@@ -317,6 +317,10 @@ export const SERVICE_HOSTS: Readonly<Record<string, ServiceHostSpec>> = {
edge: { services: ['workspaces', 'usage', 'monitor', 'projects'], heapLimitMiB: 384, rssLimitMiB: 768 },
// The prompt scopes hold a few drafts and fingerprints per agent: small, bounded state.
teams: { services: ['teams'], heapLimitMiB: 256, rssLimitMiB: 512 },
+ // The relay and its E2EE (gateway/gatewayProcess.ts): the backend link, every remote client's session,
+ // the terminals' WebRTC channels and their queues. Network, crypto and pure-JS WebRTC, the attack surface,
+ // where a fault costs the remote clients and nothing else (docs/design/2026-10-06-core-boundary-next.md).
+ gateway: { services: ['gateway'], heapLimitMiB: 512, rssLimitMiB: 1_024 },
}
/** Every service this build can run outside the core's process: what `HARNESSD_SERVICES` names. */
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index 18320b0cc..68818f0f5 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -101,25 +101,25 @@ export interface HookServerHandlers {
/** `harness pair <code>` from a second CLI process: run CPace toward the waiting browser. */
onPair?: (code: string) => Promise<PairOutcome>
/** `harness pairings` — list E2EE-paired browsers. */
- onListPairs?: () => PairOutcome
+ onListPairs?: () => PairOutcome | Promise<PairOutcome>
/** `harness unpair <id>` — unpair one browser (by fingerprint/prefix/index). */
- onRevoke?: (id: string) => PairOutcome
+ onRevoke?: (id: string) => PairOutcome | Promise<PairOutcome>
/** `harness unpair --all` — unpair every browser. */
- onRevokeAll?: () => PairOutcome
+ onRevokeAll?: () => PairOutcome | Promise<PairOutcome>
/** `harness remote-password set` — stretch + persist a new persistent remote password on the
* running daemon's live E2EE state. */
onSetRemotePassword?: (password: string) => Promise<PairOutcome>
/** `harness remote-password clear` — remove the persistent remote password. */
- onClearRemotePassword?: () => PairOutcome
+ onClearRemotePassword?: () => PairOutcome | Promise<PairOutcome>
/** `harness remote-password status` — whether one is set, and its fingerprint. */
- onRemotePasswordStatus?: () => PairOutcome
+ onRemotePasswordStatus?: () => PairOutcome | Promise<PairOutcome>
/** `harness link connect` — the machine this one just linked pinned it back, so trust that machine
* here too (the mutual half of the link). Goes through the daemon: it holds paired.json in memory. */
- onTrustLinkedPeer?: (peer: { pub: string; machineId: string; label: string }) => PairOutcome
+ onTrustLinkedPeer?: (peer: { pub: string; machineId: string; label: string }) => PairOutcome | Promise<PairOutcome>
/** `harness group list|sync|remove` — the trust group this machine belongs to (groupSyncer.ts). */
- onGroupList?: () => PairOutcome
- onGroupSync?: () => PairOutcome
- onGroupRemove?: (selector: string) => PairOutcome
+ onGroupList?: () => PairOutcome | Promise<PairOutcome>
+ onGroupSync?: () => PairOutcome | Promise<PairOutcome>
+ onGroupRemove?: (selector: string) => PairOutcome | Promise<PairOutcome>
/** `harness devices list|remove|rebaseline` and the window's Devices list — the account's device key
* log as this machine verified it (lib/e2ee/deviceLogSyncer.ts). */
onDevicesList?: () => Promise<PairOutcome>
@@ -128,7 +128,7 @@ export interface HookServerHandlers {
/** `harness devices history` and the window's History — every add and remove, as this machine verified it. */
onDevicesHistory?: () => Promise<PairOutcome>
/** `harness devices dismiss` and the window's "It's mine" / "Got it" — mark new devices as seen. */
- onDevicesDismiss?: (body: { pub?: string; pubs?: string[]; baseline?: boolean }) => PairOutcome
+ onDevicesDismiss?: (body: { pub?: string; pubs?: string[]; baseline?: boolean }) => PairOutcome | Promise<PairOutcome>
/** Local dashboard status snapshot (GET /api/status). */
onStatus?: () => Record<string, unknown> | Promise<Record<string, unknown>>
/** Recent adapter log tail (GET /api/logs). */
@@ -686,7 +686,7 @@ export function startHookServer(
if (req.method === 'POST' && url === '/api/remote-password/clear') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onClearRemotePassword) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onClearRemotePassword(); json(out.status, out.body); return
+ const out = await handlers.onClearRemotePassword(); json(out.status, out.body); return
}
// `harness link connect` → trust the machine just linked back, on the daemon's live E2EE state.
@@ -698,20 +698,20 @@ export function startHookServer(
const isKey = typeof body.pub === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(body.pub) // 32-byte Ed25519, base64
if (!isKey || typeof body.machineId !== 'string' || !/^[a-f0-9]{32}$/.test(body.machineId)) { json(400, { error: 'BAD_PEER' }); return }
const label = typeof body.label === 'string' && body.label.trim() ? body.label.trim().slice(0, 60) : body.machineId
- const out = handlers.onTrustLinkedPeer({ pub: body.pub as string, machineId: body.machineId, label })
+ const out = await handlers.onTrustLinkedPeer({ pub: body.pub as string, machineId: body.machineId, label })
json(out.status, out.body); return
}
// `harness group list` → the trust group's members. Read-only (keys and labels, no secrets).
if (req.method === 'GET' && url === '/api/group') {
if (!handlers.onGroupList) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onGroupList(); json(out.status, out.body); return
+ const out = await handlers.onGroupList(); json(out.status, out.body); return
}
// `harness group sync` → compare rosters with every reachable member now.
if (req.method === 'POST' && url === '/api/group/sync') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onGroupSync) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onGroupSync(); json(out.status, out.body); return
+ const out = await handlers.onGroupSync(); json(out.status, out.body); return
}
// `harness group remove <id|#|fp>` / `harness link unlink` → drop a member everywhere.
if (req.method === 'POST' && url === '/api/group/remove') {
@@ -720,7 +720,7 @@ export function startHookServer(
let body: { selector?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
if (typeof body.selector !== 'string' || !body.selector.trim()) { json(400, { error: 'MISSING_SELECTOR' }); return }
- const out = handlers.onGroupRemove(body.selector.trim()); json(out.status, out.body); return
+ const out = await handlers.onGroupRemove(body.selector.trim()); json(out.status, out.body); return
}
// `harness devices list` / the window's Devices list → the account's devices, as this machine's
@@ -775,7 +775,7 @@ export function startHookServer(
// The keys a window displayed, so a key accepted since the window read the list is not cleared unseen.
if (body.pubs !== undefined && (!Array.isArray(body.pubs) || body.pubs.length > 256
|| body.pubs.some((k) => typeof k !== 'string' || !k || k.length > 256))) { json(400, { error: 'BAD_PUBS' }); return }
- const out = handlers.onDevicesDismiss({
+ const out = await handlers.onDevicesDismiss({
...(typeof body.pub === 'string' ? { pub: body.pub } : {}),
...(Array.isArray(body.pubs) ? { pubs: body.pubs as string[] } : {}),
...(body.baseline === true ? { baseline: true } : {}),
@@ -786,7 +786,7 @@ export function startHookServer(
// gating tier as /api/pairs.
if (req.method === 'GET' && url === '/api/remote-password/status') {
if (!handlers.onRemotePasswordStatus) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onRemotePasswordStatus(); json(out.status, out.body); return
+ const out = await handlers.onRemotePasswordStatus(); json(out.status, out.body); return
}
// Local GUI clients (e.g. the desktop app): read the full machine list / rename or delete one /
@@ -873,7 +873,7 @@ export function startHookServer(
// `harness pairings` — list paired browsers.
if (req.method === 'GET' && url === '/api/pairs') {
if (!handlers.onListPairs) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onListPairs(); json(out.status, out.body); return
+ const out = await handlers.onListPairs(); json(out.status, out.body); return
}
// `harness unpair <id>` — unpair one browser; signals it (if online) to re-pair.
@@ -883,14 +883,14 @@ export function startHookServer(
let body: { id?: string }
try { body = JSON.parse(await readBody(req)) as { id?: string } } catch { json(400, { error: 'bad json' }); return }
if (!body.id) { json(400, { error: 'MISSING_ID' }); return }
- const out = handlers.onRevoke(body.id); json(out.status, out.body); return
+ const out = await handlers.onRevoke(body.id); json(out.status, out.body); return
}
// `harness unpair --all` — unpair every browser.
if (req.method === 'POST' && url === '/api/revoke-all') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onRevokeAll) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = handlers.onRevokeAll(); json(out.status, out.body); return
+ const out = await handlers.onRevokeAll(); json(out.status, out.body); return
}
json(404, { error: 'not found' })
diff --git a/cli/src/lib/autonomous-device/overGateway.ts b/cli/src/lib/autonomous-device/overGateway.ts
new file mode 100644
index 000000000..019f6c188
--- /dev/null
+++ b/cli/src/lib/autonomous-device/overGateway.ts
@@ -0,0 +1,58 @@
+/**
+ * The Wi-Fi device's application protocol (./relay.ts), over sessions the gateway holds (gateway/gateway.ts).
+ *
+ * The relay was written against the E2EE manager it shared a process with: it read a session's identity
+ * and role, opened a request, sealed an answer. The manager is the gateway's now, in a process of its own
+ * by default (docs/design/2026-10-06-core-boundary-next.md, step 10, R2), and the device service the relay
+ * answers for stays beside the agents. So the relay sees the sessions through what the gateway registered
+ * (`RemoteClient`), gets each request already opened by the session that sealed it, and hands its answers
+ * to the gateway to seal: its own code, and so what a device sees of it, is unchanged.
+ */
+import type { RemoteClient } from '../../core/api.js'
+import { AutonomousDeviceRelay } from './relay.js'
+import type { AutonomousDeviceFrame, AutonomousDeviceService } from './service.js'
+
+export interface DeviceRelayOverGateway {
+ /** A request as it arrived and as the gateway opened it (null when it would not open). */
+ handle(connId: string, frame: Record<string, unknown>, opened: Record<string, unknown> | null): Promise<void>
+ drop(connId: string): void
+ revoke(identity: string): void
+ /** Sessions on a direct link that said hello. */
+ directSessions(): number
+ connected(): boolean
+ emit(frame: AutonomousDeviceFrame, deviceId?: string): void
+}
+
+export function deviceRelayOverGateway(deps: {
+ /** A session the gateway registered, by connection. */
+ client(connId: string): RemoteClient | undefined
+ /** Seal and send to one session (`GatewayPort.device`). */
+ send(connId: string, type: string, payload: Record<string, unknown>): void
+ service: AutonomousDeviceService
+ machineId: string
+ onReady(): void
+ onRemoteRevoke(identity: string): void
+ onClient(connId: string, identity: string | null): void
+}): DeviceRelayOverGateway {
+ let opened: Record<string, unknown> | null = null
+ const sessions = {
+ sessionIdentity: (connId: string) => deps.client(connId)?.identity ?? null,
+ sessionRole: (connId: string) => deps.client(connId)?.role ?? null,
+ // The relay opens a request once, before its first await: the gateway opened it already.
+ unwrapDown: () => { const frame = opened; opened = null; return frame },
+ wrapTarget: (connId: string, type: string, payload: Record<string, unknown>) => (deps.client(connId) ? { type, payload } : null),
+ }
+ const relay = new AutonomousDeviceRelay(sessions, (connId, frame) => deps.send(connId, String(frame.type), frame.payload as Record<string, unknown>),
+ deps.service, deps.machineId, deps.onReady, deps.onRemoteRevoke, deps.onClient)
+ return {
+ handle: async (connId, frame, frameOpened) => {
+ opened = frameOpened
+ try { await relay.handle(connId, frame) } finally { opened = null }
+ },
+ drop: (connId) => relay.drop(connId),
+ revoke: (identity) => relay.revoke(identity),
+ directSessions: () => relay.count((connId) => deps.client(connId)?.direct === true),
+ connected: () => relay.connected(),
+ emit: (frame, deviceId) => relay.emit(frame, deviceId),
+ }
+}
diff --git a/cli/src/lib/autonomous-device/relay.ts b/cli/src/lib/autonomous-device/relay.ts
index 03c99133b..785112755 100644
--- a/cli/src/lib/autonomous-device/relay.ts
+++ b/cli/src/lib/autonomous-device/relay.ts
@@ -1,5 +1,5 @@
-import { isWrapped } from '../e2ee/core.js'
import type { E2eeManager } from '../e2ee/manager.js'
+import { isWrapped } from '../relayFrames.js'
import { deviceDump } from './dump.js'
import { type AutonomousDeviceService, type AutonomousDeviceFrame } from './service.js'
@@ -10,7 +10,11 @@ export class AutonomousDeviceRelay {
constructor(private readonly crypto: Pick<E2eeManager, 'sessionIdentity' | 'sessionRole' | 'unwrapDown' | 'wrapTarget'>,
private readonly send: (connId: string, frame: Frame) => void,
private readonly service: AutonomousDeviceService, private readonly machineId: string, private readonly onReady?: () => void,
- private readonly onRemoteRevoke?: (identity: string) => void) {}
+ private readonly onRemoteRevoke?: (identity: string) => void,
+ /** Which identity's app said hello on a session, and when it left: the gateway tells such a device it was
+ * unpaired while its session still stands, which an unpairing in the gateway's process cannot wait for
+ * this relay to do (gateway/gateway.ts). Observation only. */
+ private readonly onClient?: (connId: string, identity: string | null) => void) {}
count(include: (connId: string) => boolean = () => true): number { return [...this.clients].filter(([id, client]) => include(id) && this.crypto.sessionIdentity(id) === client.identity && this.crypto.sessionRole(id) === 'device').length }
connected(): boolean { return this.count() > 0 }
private sendTo(connId: string, identity: string, type: string, payload: Frame): void {
@@ -32,6 +36,7 @@ export class AutonomousDeviceRelay {
if (req.proto !== 1 || typeof req.requestId !== 'string') { reply({ type: 'hello_result', requestId: req.requestId, error: { code: 'PROTO_UNSUPPORTED', message: 'Protocol 1 required' } }); return }
const current = this.clients.get(connId)
this.clients.set(connId, current?.identity === identity ? current : { identity, tokens: 20, at: Date.now(), active: 0 })
+ this.onClient?.(connId, identity)
const resume = req.resume as { serverInstanceId?: unknown; cursor?: unknown } | undefined
reply({ type: 'hello_result', requestId: req.requestId, proto: 1, machineId: this.machineId, serverInstanceId: this.service.serverInstanceId, capabilities: this.service.capabilities, ...this.service.resume(resume) })
this.service.replay(resume, event => this.sendEvent(connId, identity, event))
@@ -78,6 +83,7 @@ export class AutonomousDeviceRelay {
drop(connId: string): void {
const client = this.clients.get(connId)
this.clients.delete(connId)
+ if (client) this.onClient?.(connId, null)
if (client && ![...this.clients.values()].some(c => c.identity === client.identity)) this.service.deviceOffline(client.identity)
}
/** App-side revoke: tell the device while its authenticated session still exists (the E2eeManager drops
@@ -87,6 +93,7 @@ export class AutonomousDeviceRelay {
for (const [connId, client] of this.clients) if (client.identity === identity) {
try { this.sendTo(connId, identity, 'autonomous_device_event', { type: 'pair.revoke', machineId: this.machineId }) } catch { /* Local removal must proceed regardless. */ }
this.clients.delete(connId)
+ this.onClient?.(connId, null)
}
this.service.revoke(identity)
}
diff --git a/cli/src/lib/e2ee/applicationFrames.ts b/cli/src/lib/e2ee/applicationFrames.ts
index 6be131cf3..b4f4e86c9 100644
--- a/cli/src/lib/e2ee/applicationFrames.ts
+++ b/cli/src/lib/e2ee/applicationFrames.ts
@@ -13,7 +13,11 @@ import { ENCRYPTED_RPC_RESULT_TYPES, isEncryptedDownType } from './core.js'
import { SHARE_REQUEST_TYPES, SHARE_RESULT_TYPES } from '../../sharing/protocol.js'
import { VIEWER_DOWN_TYPES } from '../viewerWire.js'
import { TEAM_REQUEST_TYPES, TEAM_RESULT_TYPES } from '../../teams/wire.js'
-export const OWNER_COMMAND_TYPES = new Set(['command_bar', 'route_task', 'route_send'])
+import { OWNER_COMMAND_TYPES, PAIR_REQUESTS, PLATE_REQUEST, PLATE_RESULT, rpcResultType } from '../relayFrames.js'
+
+// The ones the core reads too, to dispatch a request and name its reply, live with its other frame rules
+// (lib/relayFrames.ts), which load no cipher; this stays the one place every extension is listed.
+export { OWNER_COMMAND_TYPES, PAIR_REQUESTS, PLATE_REQUEST, PLATE_RESULT, rpcResultType }
const FLEET_REQUESTS = new Set(['grid_fleet_capabilities', 'grid_fleet_run', 'grid_fleet_cancel',
'grid_fleet_models_list', 'grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop'])
@@ -24,8 +28,6 @@ const MACHINE_RESULTS = new Set([...MACHINE_REQUESTS].map(type => `${type}_resul
/** The pair brain, machine to machine (daemons/BRAIN.md). A watch carries question text and recaps; the
* writes (answer, send, stop, start, pause, resume) act on a harness through the owning machine's floor
* (pair/owner.ts). Sealed both ways, always: the relay sees the outer type only. */
-export const PAIR_REQUESTS = new Set(['pair_watch', 'pair_journal', 'pair_read', 'pair_list',
- 'pair_answer', 'pair_send', 'pair_stop', 'pair_start', 'pair_pause', 'pair_resume'])
export const PAIR_RESULTS = new Set([...PAIR_REQUESTS].map(type => `${type}_result`))
/** Pushed to one watcher with the daemon's `wrapTarget` (pairwise, that connection only), never broadcast. */
export const PAIR_PUSHES = new Set(['pair_event'])
@@ -35,12 +37,8 @@ const LOCAL_PAIR_RESULT = 'pair_result'
/** An individual's art for the phone (pair/plateService.ts; a window asks `daemon_plate_get` over the Unix
* socket instead). Sealed both ways, answered to that connection alone. Its reply is `pair_plate`, not
* `pair_plate_get_result`: see rpcResultType. */
-export const PLATE_REQUEST = 'pair_plate_get'
-export const PLATE_RESULT = 'pair_plate'
export const isPairFrameType = (type: string): boolean =>
PAIR_REQUESTS.has(type) || PAIR_RESULTS.has(type) || PAIR_PUSHES.has(type) || type === PLATE_REQUEST || type === PLATE_RESULT
-/** The reply's type for a request: `<type>_result`, except the plate's `pair_plate`. */
-export const rpcResultType = (type: string): string => type === PLATE_REQUEST ? PLATE_RESULT : `${type}_result`
/**
* Whether a `pair_*` frame that arrived through the relay may be believed. `RelaySessionCrypto` passes a
* never-wrapped frame straight through (control frames are plaintext), so without this the relay could
diff --git a/cli/src/lib/e2ee/manager.test.ts b/cli/src/lib/e2ee/manager.test.ts
index c8db6ee23..e6b453544 100644
--- a/cli/src/lib/e2ee/manager.test.ts
+++ b/cli/src/lib/e2ee/manager.test.ts
@@ -649,7 +649,7 @@ describe('a sealed frame for a session this process never had', () => {
describe('terminal bytes sealed for a session this process never had', () => {
const keystrokes = async (counter: number) => {
- const { sealTerminalBinary } = await import('../terminalBinary.js')
+ const { sealTerminalBinary } = await import('./terminalSeal.js')
return sealTerminalBinary(new Uint8Array(32).fill(9), counter, { kind: 1, streamId: '00112233-4455-6677-8899-aabbccddeeff', seq: 1, bytes: new TextEncoder().encode('ls\r'), compressed: false })!
}
diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.ts
index 8ea7e5b6e..2a9131696 100644
--- a/cli/src/lib/e2ee/manager.ts
+++ b/cli/src/lib/e2ee/manager.ts
@@ -16,13 +16,8 @@
* The relay never sees plaintext user content: only ciphertext envelopes + public PAKE messages.
*/
import * as C from './core.js'
-import {
- deriveTerminalBinaryKey,
- openTerminalBinary,
- parseTerminalBinaryEnvelope,
- sealTerminalBinary,
- type TerminalBinaryClear,
-} from '../terminalBinary.js'
+import { parseTerminalBinaryEnvelope, type TerminalBinaryClear } from '../terminalBinary.js'
+import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary } from './terminalSeal.js'
import { E2eeStore, type PeerKind } from './store.js'
import { pwCpaceGenerator, pwContext } from './passwordPake.js'
import { ReplayWindow } from './replayWindow.js'
diff --git a/cli/src/lib/e2ee/relayClient.ts b/cli/src/lib/e2ee/relayClient.ts
index f3f418b8d..ed82eaca2 100644
--- a/cli/src/lib/e2ee/relayClient.ts
+++ b/cli/src/lib/e2ee/relayClient.ts
@@ -12,7 +12,8 @@
import { WebSocket } from 'ws'
import * as C from './core.js'
import { encryptDownFrameFor } from './applicationFrames.js'
-import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary, type TerminalBinaryClear } from '../terminalBinary.js'
+import type { TerminalBinaryClear } from '../terminalBinary.js'
+import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary } from './terminalSeal.js'
import { pwCpaceGenerator, pwContext, stretchPassword } from './passwordPake.js'
import { ReplayWindow } from './replayWindow.js'
diff --git a/cli/src/lib/e2ee/terminalSeal.ts b/cli/src/lib/e2ee/terminalSeal.ts
new file mode 100644
index 000000000..39ac66a11
--- /dev/null
+++ b/cli/src/lib/e2ee/terminalSeal.ts
@@ -0,0 +1,57 @@
+/**
+ * Sealing and opening the terminal's binary frames, with a session's key: the gateway's half of
+ * lib/terminalBinary.ts, which frames them. Apart from it so that the core, which frames bytes for the
+ * windows on this computer, loads no cipher (docs/design/2026-10-06-core-boundary-next.md, step 10).
+ */
+import { hkdf } from '@noble/hashes/hkdf'
+import { sha256 } from '@noble/hashes/sha2'
+import { aeadOpen, aeadSeal, utf8 } from './core.js'
+import {
+ decodeTerminalPlain,
+ encodeTerminalPlain,
+ flagsFor,
+ MAGIC,
+ maxCiphertextBytesFor,
+ parseTerminalBinaryEnvelope,
+ TERMINAL_BINARY_HEADER_BYTES,
+ TERMINAL_BINARY_VERSION,
+ type TerminalBinaryClear,
+} from '../terminalBinary.js'
+
+const TERMINAL_KEY_INFO = utf8('harness-terminal-binary-v3')
+
+/** Keep binary terminal nonces independent from JSON control-frame nonces. */
+export function deriveTerminalBinaryKey(sessionKey: Uint8Array): Uint8Array {
+ return hkdf(sha256, sessionKey, new Uint8Array(), TERMINAL_KEY_INFO, 32)
+}
+
+export function sealTerminalBinary(key: Uint8Array, counter: number, frame: TerminalBinaryClear): Uint8Array | null {
+ if (!Number.isSafeInteger(counter) || counter < 0) return null
+ const plaintext = encodeTerminalPlain(frame)
+ if (!plaintext) return null
+ const flags = flagsFor(frame)
+ const header = new Uint8Array(TERMINAL_BINARY_HEADER_BYTES)
+ header.set(MAGIC, 0)
+ header[4] = TERMINAL_BINARY_VERSION
+ header[5] = frame.kind
+ header[6] = flags
+ const view = new DataView(header.buffer)
+ view.setBigUint64(8, BigInt(counter), false)
+ const ciphertext = aeadSeal(key, counter, header.subarray(0, 16), plaintext)
+ if (ciphertext.length > maxCiphertextBytesFor(frame.kind)) return null
+ view.setUint32(16, ciphertext.length, false)
+ const out = new Uint8Array(header.length + ciphertext.length)
+ out.set(header)
+ out.set(ciphertext, header.length)
+ return out
+}
+
+export function openTerminalBinary(key: Uint8Array, raw: Uint8Array): { counter: number; frame: TerminalBinaryClear } | null {
+ const envelope = parseTerminalBinaryEnvelope(raw)
+ if (!envelope) return null
+ const plaintext = aeadOpen(key, envelope.counter, envelope.aad, envelope.ciphertext)
+ if (!plaintext) return null
+ const frame = decodeTerminalPlain(envelope.kind, envelope.flags, plaintext)
+ return frame ? { counter: envelope.counter, frame } : null
+}
+
diff --git a/cli/src/lib/gatewayWire.ts b/cli/src/lib/gatewayWire.ts
new file mode 100644
index 000000000..41bce3846
--- /dev/null
+++ b/cli/src/lib/gatewayWire.ts
@@ -0,0 +1,63 @@
+/**
+ * How the core and the gateway in its own process speak (core/gatewayLink.ts, gateway/gatewayProcess.ts):
+ * the service link every service has (core/serviceLinks.ts), carrying the core's frames for remote clients
+ * one way and what the remote clients sent, and what the backend said, the other. All of it in the clear:
+ * the link is the core's local socket, which only the master's token opens.
+ *
+ * JSON frames are `service_event` (core → gateway) and `service_notice` (gateway → core), each with a
+ * `kind`. Terminal bytes travel as binary frames, framed here: a byte saying whose they are, the id of the
+ * connection or window they belong to, and the terminal's own local framing (lib/terminalBinary.ts).
+ */
+/** Whose bytes a binary frame carries. */
+export const enum GatewayBinary {
+ /** A remote client's terminal, in the local framing (lib/terminalBinary.ts `encodeTerminalLocal`): to it
+ * (core → gateway) or from it (gateway → core). */
+ remote = 1,
+ /** A window here working on another machine through the gateway (`WindowRelay`): its terminal's bytes. */
+ window = 2,
+}
+
+/** The longest id a binary frame carries: a backend connection id, a Wi-Fi device's, or a window's. */
+const MAX_ID_BYTES = 256
+
+export function encodeGatewayBinary(kind: GatewayBinary, id: string, bytes: Uint8Array): Uint8Array | null {
+ const idBytes = new TextEncoder().encode(id)
+ if (idBytes.length === 0 || idBytes.length > MAX_ID_BYTES) return null
+ const out = new Uint8Array(3 + idBytes.length + bytes.length)
+ out[0] = kind
+ out[1] = idBytes.length >> 8
+ out[2] = idBytes.length & 0xff
+ out.set(idBytes, 3)
+ out.set(bytes, 3 + idBytes.length)
+ return out
+}
+
+export function decodeGatewayBinary(raw: Uint8Array): { kind: GatewayBinary; id: string; bytes: Uint8Array } | null {
+ if (raw.length < 3 || (raw[0] !== GatewayBinary.remote && raw[0] !== GatewayBinary.window)) return null
+ const length = (raw[1] << 8) | raw[2]
+ if (length === 0 || length > MAX_ID_BYTES || raw.length < 3 + length) return null
+ return { kind: raw[0], id: new TextDecoder().decode(raw.subarray(3, 3 + length)), bytes: raw.subarray(3 + length) }
+}
+
+/** The requests the core asks the gateway's process (`serviceLinks.call`), answered under `<type>_result`:
+ * one per `GatewayOps` member that answers. */
+export const GATEWAY_CALLS = {
+ status: 'gateway_status',
+ pair: 'gateway_pair',
+ listPairs: 'gateway_list_pairs',
+ revoke: 'gateway_revoke',
+ revokeAll: 'gateway_revoke_all',
+ setRemotePassword: 'gateway_set_remote_password',
+ clearRemotePassword: 'gateway_clear_remote_password',
+ remotePasswordStatus: 'gateway_remote_password_status',
+ trustLinkedPeer: 'gateway_trust_linked_peer',
+ groupList: 'gateway_group_list',
+ groupSync: 'gateway_group_sync',
+ groupRemove: 'gateway_group_remove',
+ devicesList: 'gateway_devices_list',
+ devicesRemove: 'gateway_devices_remove',
+ devicesHistory: 'gateway_devices_history',
+ devicesDismiss: 'gateway_devices_dismiss',
+ devicesRebaseline: 'gateway_devices_rebaseline',
+ wifi: 'gateway_wifi',
+} as const
diff --git a/cli/src/lib/ownerCommands.ts b/cli/src/lib/ownerCommands.ts
index 9640016ed..7a8cd33b7 100644
--- a/cli/src/lib/ownerCommands.ts
+++ b/cli/src/lib/ownerCommands.ts
@@ -1,7 +1,7 @@
import { CommandBarError, commandBarService, type CommandBarService } from './commandBar.js'
import type { LocalWsServerOptions } from '../localWsServer.js'
-import { OWNER_COMMAND_TYPES } from './e2ee/applicationFrames.js'
-export { OWNER_COMMAND_TYPES } from './e2ee/applicationFrames.js'
+import { OWNER_COMMAND_TYPES } from './relayFrames.js'
+export { OWNER_COMMAND_TYPES } from './relayFrames.js'
/** The same decisions and task delivery as the desktop, behind the paired-owner boundary.
* A decision never executes an action. The client still reviews and commits the selected action. */
diff --git a/cli/src/lib/relayFrames.ts b/cli/src/lib/relayFrames.ts
index 963f4e158..8389c7176 100644
--- a/cli/src/lib/relayFrames.ts
+++ b/cli/src/lib/relayFrames.ts
@@ -52,3 +52,37 @@ export function logSafeType(type: string): string {
* client's directly, a window's on this computer when the core hands it over (`GatewayPort.local`).
*/
export const GATEWAY_REQUEST_TYPES = new Set(['device_e2ee_pair', 'phone_pair', 'e2ee_pairings_list', 'e2ee_pairing_unpair', 'e2ee_pairings_unpair_all'])
+
+/** A window's connection to another machine could not be made: why, and the close code to tell it. Here and
+ * not with the relay pool, so the local socket can tell one apart without loading the pool. */
+export class RelayConnectError extends Error {
+ constructor(message: string, readonly closeCode?: number) {
+ super(message)
+ this.name = 'RelayConnectError'
+ }
+}
+
+/**
+ * Frames only THIS machine's own daemon says to its own windows (the device key log's notices). A
+ * remote machine is not that daemon: if its frame reached the local app as-is, the app would show a
+ * "new device" / "removed by" band as though this machine had verified it. Dropped on the way in,
+ * sealed or not.
+ */
+export const DAEMON_LOCAL_ONLY_TYPES: ReadonlySet<string> = new Set(['device_key_added', 'device_key_removed', 'device_conflict', 'device_keys_changed'])
+
+/** The owner's commands from the window's command bar and ⌘K, sealed and the owner's only (lib/ownerCommands.ts). */
+export const OWNER_COMMAND_TYPES = new Set(['command_bar', 'route_task', 'route_send'])
+/** The pair brain, machine to machine (daemons/BRAIN.md): retired, and refused (lib/e2ee/applicationFrames.ts). */
+export const PAIR_REQUESTS = new Set(['pair_watch', 'pair_journal', 'pair_read', 'pair_list',
+ 'pair_answer', 'pair_send', 'pair_stop', 'pair_start', 'pair_pause', 'pair_resume'])
+/** An individual's art for the phone: retired, and refused. Its reply is `pair_plate`, not `pair_plate_get_result`. */
+export const PLATE_REQUEST = 'pair_plate_get'
+export const PLATE_RESULT = 'pair_plate'
+/** The reply's type for a request: `<type>_result`, except the plate's `pair_plate`. */
+export const rpcResultType = (type: string): string => type === PLATE_REQUEST ? PLATE_RESULT : `${type}_result`
+
+/** Whether a payload is a sealed envelope (`{ __e2e }`): the same test as lib/e2ee/core.ts `isWrapped`, which
+ * must stay byte-identical with the browser's copy and brings the ciphers with it. */
+export function isWrapped(payload: unknown): payload is { __e2e: Record<string, unknown> } {
+ return !!payload && typeof payload === 'object' && '__e2e' in (payload as Record<string, unknown>)
+}
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.ts
index a05c64516..7cb983b38 100644
--- a/cli/src/lib/remoteRelay.ts
+++ b/cli/src/lib/remoteRelay.ts
@@ -19,6 +19,9 @@ import type { Frame, LocalClientSink } from '../backendSocket.js'
import type { AuthSessionManager } from './authSession.js'
import { b64d, type Identity } from './e2ee/core.js'
import { sid } from './log.js'
+import { DAEMON_LOCAL_ONLY_TYPES, RelayConnectError } from './relayFrames.js'
+
+export { DAEMON_LOCAL_ONLY_TYPES, RelayConnectError }
import type { MachinePeerStore } from './e2ee/machinePeers.js'
import { RelaySessionCrypto } from './e2ee/relayClient.js'
import { encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from './terminalBinary.js'
@@ -92,12 +95,6 @@ const P2P_UPGRADE_ATTEMPT_TIMEOUT_MS = 15_000
const P2P_UPGRADE_DRAIN_TIMEOUT_MS = 5_000
const P2P_PROMOTE_ACK_TIMEOUT_MS = 5_000
-export class RelayConnectError extends Error {
- constructor(message: string, readonly closeCode?: number) {
- super(message)
- this.name = 'RelayConnectError'
- }
-}
function binaryBytes(raw: RawData): Uint8Array {
if (Buffer.isBuffer(raw)) return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
@@ -106,13 +103,6 @@ function binaryBytes(raw: RawData): Uint8Array {
return new Uint8Array()
}
-/**
- * Frames only THIS machine's own daemon says to its own windows (the device key log's notices). A
- * remote machine is not that daemon: if its frame reached the local app as-is, the app would show a
- * "new device" / "removed by" band as though this machine had verified it. Dropped on the way in,
- * sealed or not.
- */
-export const DAEMON_LOCAL_ONLY_TYPES: ReadonlySet<string> = new Set(['device_key_added', 'device_key_removed', 'device_conflict', 'device_keys_changed'])
/** One local client attached to a pooled upstream: where its frames go, and what to tell it on close. */
interface AttachedClient {
@@ -285,7 +275,7 @@ export class RemoteRelayPool {
private readonly groupSeen = new Map<string, Map<string, number>>()
constructor(
- private readonly auth: AuthSessionManager,
+ private readonly auth: Pick<AuthSessionManager, 'accessToken'>,
private readonly backendWsBase: string,
private readonly selfIdentity: Identity,
private readonly peers: MachinePeerStore,
@@ -390,6 +380,13 @@ export class RemoteRelayPool {
try { entry.ws.terminate() } catch { /* already gone */ }
}
+ /** Every session this pool holds, ended, for a gateway that is going (its core went away, or it is
+ * stopping): the windows on them are told by whoever holds their sockets, the core's local socket. */
+ close(): void {
+ for (const machineId of [...this.entries.keys()]) this.invalidate(machineId)
+ for (const machineId of [...this.idleIsolated.keys()]) this.invalidateIsolated(machineId)
+ }
+
/** Attach `sink` to the (possibly newly-created, possibly reused) upstream connection for
* `machineId`. `selectFrame` is the local client's own `machine_select` frame, forwarded upstream
* verbatim on a fresh connect — backend only reads its `.machineId`, so the local protocol's extra
diff --git a/cli/src/lib/terminalBinary.spec.ts b/cli/src/lib/terminalBinary.spec.ts
index 82c5dc0e8..3f2a94a3a 100644
--- a/cli/src/lib/terminalBinary.spec.ts
+++ b/cli/src/lib/terminalBinary.spec.ts
@@ -1,11 +1,9 @@
import { describe, expect, it } from 'vitest'
+import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary } from './e2ee/terminalSeal.js'
import {
- deriveTerminalBinaryKey,
decodeTerminalLocal,
encodeTerminalLocal,
- openTerminalBinary,
parseTerminalBinaryEnvelope,
- sealTerminalBinary,
TerminalBinaryKind,
TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES,
TERMINAL_BINARY_MAX_CIPHERTEXT_BYTES,
diff --git a/cli/src/lib/terminalBinary.ts b/cli/src/lib/terminalBinary.ts
index f01cb3ebc..b414d7fdb 100644
--- a/cli/src/lib/terminalBinary.ts
+++ b/cli/src/lib/terminalBinary.ts
@@ -1,6 +1,9 @@
-import { aeadOpen, aeadSeal, utf8 } from './e2ee/core.js'
-import { hkdf } from '@noble/hashes/hkdf'
-import { sha256 } from '@noble/hashes/sha2'
+/**
+ * The terminal's binary framing: the plain frame a window on this computer gets (`encodeTerminalLocal`),
+ * the envelope a sealed one travels in, and the hop prefix the relay routes by. The sealing itself is the
+ * gateway's (lib/e2ee/terminalSeal.ts): the core frames bytes for its windows and never holds a key.
+ */
+const utf8 = (s: string): Uint8Array => new TextEncoder().encode(s)
export const TERMINAL_BINARY_VERSION = 3
export const TERMINAL_BINARY_HEADER_BYTES = 20
@@ -72,19 +75,13 @@ export interface TerminalBinaryEnvelope {
aad: Uint8Array
}
-const MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4d) // HTRM
+export const MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4d) // HTRM
const HOP_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x48) // HTRH
const LOCAL_MAGIC = Uint8Array.of(0x48, 0x54, 0x52, 0x4c) // HTRL
const FLAG_ZLIB = 1
const FLAG_SWARM = 2
const canCarrySwarm = (kind: TerminalBinaryKind): boolean => kind === TerminalBinaryKind.input || kind === TerminalBinaryKind.paste
-const flagsFor = (frame: TerminalBinaryClear): number => (frame.compressed ? FLAG_ZLIB : 0) | (frame.tabId !== undefined ? FLAG_SWARM : 0)
-const TERMINAL_KEY_INFO = utf8('harness-terminal-binary-v3')
-
-/** Keep binary terminal nonces independent from JSON control-frame nonces. */
-export function deriveTerminalBinaryKey(sessionKey: Uint8Array): Uint8Array {
- return hkdf(sha256, sessionKey, new Uint8Array(), TERMINAL_KEY_INFO, 32)
-}
+export const flagsFor = (frame: TerminalBinaryClear): number => (frame.compressed ? FLAG_ZLIB : 0) | (frame.tabId !== undefined ? FLAG_SWARM : 0)
function safeU64(view: DataView, offset: number): number | null {
const value = view.getBigUint64(offset, false)
@@ -125,7 +122,7 @@ export function terminalBinaryType(kind: TerminalBinaryKind): string {
/** The seal/parse/encode/decode size ceiling for [kind] — paste, imagePaste and pasteFile each get
* a much larger one; see TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES /
* TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES / TERMINAL_BINARY_PASTE_FILE_MAX_CIPHERTEXT_BYTES. */
-function maxCiphertextBytesFor(kind: TerminalBinaryKind): number {
+export function maxCiphertextBytesFor(kind: TerminalBinaryKind): number {
if (kind === TerminalBinaryKind.paste) return TERMINAL_BINARY_PASTE_MAX_CIPHERTEXT_BYTES
if (kind === TerminalBinaryKind.imagePaste) return TERMINAL_BINARY_IMAGE_PASTE_MAX_CIPHERTEXT_BYTES
if (kind === TerminalBinaryKind.pasteFile) return TERMINAL_BINARY_PASTE_FILE_MAX_CIPHERTEXT_BYTES
@@ -216,36 +213,6 @@ export function parseTerminalBinaryEnvelope(raw: Uint8Array): TerminalBinaryEnve
}
}
-export function sealTerminalBinary(key: Uint8Array, counter: number, frame: TerminalBinaryClear): Uint8Array | null {
- if (!Number.isSafeInteger(counter) || counter < 0) return null
- const plaintext = encodeTerminalPlain(frame)
- if (!plaintext) return null
- const flags = flagsFor(frame)
- const header = new Uint8Array(TERMINAL_BINARY_HEADER_BYTES)
- header.set(MAGIC, 0)
- header[4] = TERMINAL_BINARY_VERSION
- header[5] = frame.kind
- header[6] = flags
- const view = new DataView(header.buffer)
- view.setBigUint64(8, BigInt(counter), false)
- const ciphertext = aeadSeal(key, counter, header.subarray(0, 16), plaintext)
- if (ciphertext.length > maxCiphertextBytesFor(frame.kind)) return null
- view.setUint32(16, ciphertext.length, false)
- const out = new Uint8Array(header.length + ciphertext.length)
- out.set(header)
- out.set(ciphertext, header.length)
- return out
-}
-
-export function openTerminalBinary(key: Uint8Array, raw: Uint8Array): { counter: number; frame: TerminalBinaryClear } | null {
- const envelope = parseTerminalBinaryEnvelope(raw)
- if (!envelope) return null
- const plaintext = aeadOpen(key, envelope.counter, envelope.aad, envelope.ciphertext)
- if (!plaintext) return null
- const frame = decodeTerminalPlain(envelope.kind, envelope.flags, plaintext)
- return frame ? { counter: envelope.counter, frame } : null
-}
-
/** Plain terminal framing for the authenticated loopback desktop transport. */
export function encodeTerminalLocal(frame: TerminalBinaryClear): Uint8Array | null {
const payload = encodeTerminalPlain(frame)
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index b2887f3af..1e5fd653e 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -1044,11 +1044,14 @@ describe('local CLI WebSocket', () => {
it('takes the core\'s own services by their token, whatever machine id they name', async () => {
// A signed-in core serves under its account's machine id; its services name this computer's.
const accepted: string[] = []
+ const receiveBinary = vi.fn()
+ let buffered: (() => number) | undefined
const services = {
- accept: (service: string, token: string) => {
+ accept: (service: string, token: string, sink: { buffered(): number }) => {
if (token !== 'boot-token') return null
accepted.push(service)
- return { receive: vi.fn(), closed: vi.fn() }
+ buffered = sink.buffered
+ return { receive: vi.fn(), receiveBinary, closed: vi.fn() }
},
}
const url = await start(new FakeBackend(), { services })
@@ -1061,6 +1064,11 @@ describe('local CLI WebSocket', () => {
}))
await expect(connected).resolves.toMatchObject({ type: 'connected', payload: { machineId, service: 'search' } })
expect(accepted).toEqual(['search'])
+ // A service that carries terminals (the gateway) sends bytes on its link, and the core can ask how many
+ // of its own wait on the socket to it.
+ ws.send(Uint8Array.of(1, 2, 3))
+ await vi.waitFor(() => expect(receiveBinary).toHaveBeenCalledWith(new Uint8Array([1, 2, 3])))
+ expect(buffered?.()).toBe(0)
ws.close()
// The token is the check: a wrong one is refused, whichever machine id it names.
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index b6417fd1a..e5e468021 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -15,7 +15,8 @@ import {
TERMINAL_LOCAL_PASTE_MAX_PAYLOAD_BYTES,
type TerminalBinaryClear,
} from './lib/terminalBinary.js'
-import { RelayConnectError, type RelaySession, type RemoteRelayPool } from './lib/remoteRelay.js'
+import { RelayConnectError } from './lib/relayFrames.js'
+import type { WindowRelay, WindowRelaySession } from './core/api.js'
// Reserved retired feature frames: transport refusals only, no optional implementation.
const DAEMON_IN_TYPES = new Set(['daemon_act', 'daemon_presence', 'daemon_talk', 'daemon_open', 'daemon_shown', 'daemon_confirm'])
const DAEMON_PLATE_GET = 'daemon_plate_get'
@@ -51,7 +52,7 @@ export interface LocalWsServerOptions {
localSocketServer?: http.Server | null
/** Serves a `machine_select` for any OTHER machine this signed-in user owns, by relaying to
* backend's `/api/web-ws` — see lib/remoteRelay.ts. Omit to keep today's own-machine-only behavior. */
- relayPool?: RemoteRelayPool
+ relayPool?: WindowRelay
shareRelay?: HarnessShareRelay
autonomousEnv?: string
/**
@@ -115,7 +116,8 @@ export interface LocalWsServerOptions {
/** The core's end of its out-of-process services (core/serviceLinks.ts): a `machine_select` with
* `role: "service"` is handed here, and the connection is the service's from then on. */
services?: {
- accept(service: string, token: string, sink: LocalClientSink, close: (code: number, reason: string) => void): { receive(frame: Frame): void; closed(): void } | null
+ accept(service: string, token: string, sink: LocalClientSink & { buffered(): number }, close: (code: number, reason: string) => void):
+ { receive(frame: Frame): void; receiveBinary(bytes: Uint8Array): void; closed(): void } | null
}
/**
* The window answering a `voice_route_request` — words spoken into the dial that IT was asked to route.
@@ -330,13 +332,13 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// Which machine THIS connection is bound to. The app opens one local socket per machine, so it is
// fixed for the life of the connection — set once, beside `selected`.
let boundMachineId: string | null = null
- let relay: RelaySession | null = null
+ let relay: WindowRelaySession | null = null
/** Whether this connection ever reported a tile roster — only then is clearing it ours to do. */
let sentPanes = false
let sentSwarms = false
let chain = Promise.resolve()
/** Set when this connection is one of the core's services, not a window. */
- let serviceLink: { receive(frame: Frame): void; closed(): void } | null = null
+ let serviceLink: { receive(frame: Frame): void; receiveBinary(bytes: Uint8Array): void; closed(): void } | null = null
const sink: LocalClientSink = {
sendFrame: (frame) => {
@@ -391,7 +393,7 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// account's machine id while a service names this computer's, and matching them refused every
// service of every signed-in daemon (found by the release rehearsal, signed in).
if (payload.role === 'service') {
- const link = options.services?.accept(String(payload.service ?? ''), String(payload.token ?? ''), sink, close) ?? null
+ const link = options.services?.accept(String(payload.service ?? ''), String(payload.token ?? ''), { ...sink, buffered: () => ws.bufferedAmount }, close) ?? null
if (!link) { close(4401, 'service refused'); return }
serviceLink = link
selected = true
@@ -462,7 +464,8 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
chain = chain.then(() => {
if (!selected) return selectMachine(raw, isBinary)
if (serviceLink) {
- const frame = isBinary ? null : jsonFrame(raw)
+ if (isBinary) { serviceLink.receiveBinary(binaryBytes(raw)); return }
+ const frame = jsonFrame(raw)
if (!frame) { close(4400, 'invalid json frame'); return }
serviceLink.receive(frame)
return
diff --git a/cli/src/serviceProcess.ts b/cli/src/serviceProcess.ts
index 8a4752193..082724a06 100644
--- a/cli/src/serviceProcess.ts
+++ b/cli/src/serviceProcess.ts
@@ -33,6 +33,7 @@ export const SERVICE_RUNNERS: ReadonlyMap<string, () => Promise<Runner>> = new M
['projects', async () => (await import('./services/projectsProcess.js')).runProjectsService],
['store', async () => (await import('./services/storeProcess.js')).runStoreService],
['teams', async () => (await import('./services/teamsProcess.js')).runTeamsService],
+ ['gateway', async () => (await import('./gateway/gatewayProcess.js')).runGatewayService],
])
export interface ServiceProcessDeps {
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index f9bf34ab6..bdd244129 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -93,6 +93,11 @@ all inside the core's process (for debugging or a quick way back).
when to sweep. A command that destroys something is never held or replayed, and what it must know
(the folders in use) is asked for when it starts, never sent ahead where it could go stale.
`e2e/workspacesProcess.e2e.ts` proves it.
+- A service that is transport rather than requests: the gateway (src/gateway/gatewayProcess.ts,
+ src/core/gatewayLink.ts) carries every remote client's traffic, so it tells the core without asking
+ (`service_notice`) and carries terminal bytes as binary frames on its link. The core drops what would
+ pile up on a gateway that reads nothing, and the gateway gone is the relay gone: every remote client
+ with it, never a window on this computer. `e2e/gatewayProcess.e2e.ts` proves it, with a phone.
- State built from every change must get every change exactly once. The teams show how
(`src/services/teamsProcess.ts`, `src/core/teamsLink.ts`): the core numbers each change and keeps it
until the process acknowledges it; on each connection the process says what it applied and gets
diff --git a/cli/src/services/inline.spec.ts b/cli/src/services/inline.spec.ts
index 350868e79..6db81e4ae 100644
--- a/cli/src/services/inline.spec.ts
+++ b/cli/src/services/inline.spec.ts
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest'
+import { startGateway } from '../gateway/start.js'
import * as inline from './inline.js'
import { startMonitor } from './monitor.js'
import { startProjects } from './projects.js'
@@ -10,6 +11,6 @@ import { startWorkspaces } from './workspaces.js'
describe('the services the core runs in its own process only when they do not run in theirs', () => {
it('are their own starts, unchanged: the same services either way', () => {
- expect({ ...inline }).toEqual({ startMonitor, startProjects, startSearch, startStore, startUsage, startViewers, startWorkspaces })
+ expect({ ...inline }).toEqual({ startGateway, startMonitor, startProjects, startSearch, startStore, startUsage, startViewers, startWorkspaces })
})
})
diff --git a/cli/src/services/inline.ts b/cli/src/services/inline.ts
index 93c73d047..2d933f96b 100644
--- a/cli/src/services/inline.ts
+++ b/cli/src/services/inline.ts
@@ -3,6 +3,8 @@
* when they run in the core's instead: with `HARNESSD_SERVICES=none` (debugging, or a quick way back), a
* subset named, a master too old to run them, or no master at all (`harness start -f`).
*
+ * The gateway (gateway/start.ts) is here too: the relay and its keys, run in the core's process the same way.
+ *
* The core imports this module only then, and only dynamically (core/main.ts): what it reaches is the
* services' own code, which the core's process then never loads by default. That is how a service in its
* own process leaves the core's import closure, which src/architecture.spec.ts holds to a budget and
@@ -10,6 +12,7 @@
* and its test"). The core still routes these services' requests and holds their fallbacks: both are
* declared in core/api.ts, which it loads either way.
*/
+export { startGateway } from '../gateway/start.js'
export { startMonitor } from './monitor.js'
export { startProjects } from './projects.js'
export { startSearch } from './search.js'
diff --git a/cli/src/services/process.spec.ts b/cli/src/services/process.spec.ts
index 5fd5f83b8..eefc66071 100644
--- a/cli/src/services/process.spec.ts
+++ b/cli/src/services/process.spec.ts
@@ -8,11 +8,13 @@ import { hostServices, LEAVE_GRACE_MS, REFUSED, runServiceProcess, serviceFaults
class FakeSocket extends EventEmitter {
readyState: number = WebSocket.CONNECTING
readonly sent: Array<{ type: string; payload: Record<string, unknown> }> = []
+ readonly binary: Uint8Array[] = []
closed = false
constructor(readonly url: string, private readonly failSend = false) { super() }
- send(data: string): void {
+ send(data: string | Uint8Array): void {
if (this.failSend) throw new Error('gone')
- this.sent.push(JSON.parse(data))
+ if (typeof data === 'string') this.sent.push(JSON.parse(data))
+ else this.binary.push(data)
}
close(): void { this.closed = true }
open(): void { this.readyState = WebSocket.OPEN; this.emit('open') }
@@ -232,6 +234,60 @@ describe('a service in its own process', () => {
await expect(core!.query('agents')).rejects.toThrow('not connected to the core')
})
+ it('tells the core without asking, carries bytes both ways, and hears when the core goes (the gateway)', () => {
+ const onBinary = vi.fn()
+ const onDisconnected = vi.fn()
+ let core: Parameters<NonNullable<ServiceProcessOptions['onConnected']>>[0] | null = null
+ run({ onBinary, onDisconnected, onConnected: (connection) => { core = connection } })
+ // A socket that never got as far as the core taking it: its end is not a disconnection.
+ socket().drop()
+ expect(onDisconnected).not.toHaveBeenCalled()
+ vi.advanceTimersByTime(100)
+ socket().open()
+ socket().say({ type: 'connected', payload: { service: 'gateway' } })
+ core!.notice!('status', { connected: true })
+ core!.notice!('linkDown')
+ expect(socket().sent.slice(1)).toEqual([
+ { type: 'service_notice', payload: { connected: true, kind: 'status' } },
+ { type: 'service_notice', payload: { kind: 'linkDown' } },
+ ])
+ expect(core!.sendBinary!(Uint8Array.of(1, 2))).toBe(true)
+ expect(socket().binary).toEqual([Uint8Array.of(1, 2)])
+ socket().emit('message', Buffer.from([3, 4]), true)
+ socket().emit('message', [Buffer.from([5]), Buffer.from([6])], true)
+ expect(onBinary.mock.calls).toEqual([[new Uint8Array([3, 4])], [new Uint8Array([5, 6])]])
+ // A binary frame its handler cannot take is logged, and the link goes on.
+ onBinary.mockImplementationOnce(() => { throw new Error('bad bytes') })
+ socket().emit('message', Buffer.from([7]), true)
+ expect(lines).toContain('[service search] binary frame failed · bad bytes')
+ socket().drop()
+ expect(onDisconnected).toHaveBeenCalledOnce()
+ // Gone: bytes cannot be sent, and a notice is dropped rather than thrown.
+ expect(core!.sendBinary!(Uint8Array.of(9))).toBe(false)
+ core!.notice!('linkDown')
+ // A disconnection its handler cannot take is logged too.
+ onDisconnected.mockImplementationOnce(() => { throw new Error('stuck') })
+ vi.advanceTimersByTime(200)
+ socket().open()
+ socket().say({ type: 'connected', payload: {} })
+ socket().drop()
+ expect(lines).toContain('[service search] disconnect failed · stuck')
+ // A socket that refuses the bytes as they are written: not sent.
+ vi.advanceTimersByTime(400)
+ const failing = new FakeSocket('x', true)
+ Object.assign(socket(), { send: failing.send.bind(failing) })
+ socket().open()
+ socket().say({ type: 'connected', payload: {} })
+ expect(core!.sendBinary!(Uint8Array.of(1))).toBe(false)
+ })
+
+ it('a binary frame with nobody to hear it is dropped', () => {
+ run()
+ socket().open()
+ socket().emit('message', Buffer.from([1]), true)
+ expect(lines).toEqual([])
+ })
+
it('reconnects with a backoff that doubles and caps while the core is away, and resets once connected', () => {
const service = run()
socket().drop()
diff --git a/cli/src/services/process.ts b/cli/src/services/process.ts
index edcb4e8af..36101134f 100644
--- a/cli/src/services/process.ts
+++ b/cli/src/services/process.ts
@@ -21,6 +21,11 @@ type Payload = Record<string, unknown>
export interface CoreConnection {
/** Ask the core something (`service_query`); rejects when the connection goes before it answers. */
query(query: string, payload?: Payload): Promise<Payload>
+ /** Tell the core something without asking (`service_notice`): the gateway's remote clients and what
+ * they sent. Dropped when the connection is going. */
+ notice?(kind: string, payload?: Payload): void
+ /** Bytes for the core (a remote client's terminal, from the gateway); false when the connection is going. */
+ sendBinary?(bytes: Uint8Array): boolean
}
export interface ServiceProcessOptions {
@@ -36,6 +41,10 @@ export interface ServiceProcessOptions {
onEvent?: (payload: Payload) => void | Promise<unknown>
/** Each time it is connected to a core: the first time, and after every core restart. */
onConnected?: (core: CoreConnection) => void
+ /** Each time that connection ends: what was the core's to hear is gone with it. */
+ onDisconnected?: () => void
+ /** A binary frame from the core (a remote client's terminal, for the gateway). A throw is logged. */
+ onBinary?: (bytes: Uint8Array) => void
env?: NodeJS.ProcessEnv
connect?: (url: string) => WebSocket
log?: (line: string) => void
@@ -173,6 +182,8 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
let socket: WebSocket | null = null
let reconnectTimer: ReturnType<typeof setTimeout> | null = null
let queries = 0
+ /** The core took this connection (`connected`): only then does its end mean the service was cut off. */
+ let opened = false
const pending = new Map<string, { resolve: (payload: Payload) => void; reject: (error: Error) => void }>()
const send = (frame: { type: string; payload: Payload }): void => {
@@ -186,14 +197,25 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
pending.set(requestId, { resolve, reject })
send({ type: 'service_query', payload: { ...payload, query, requestId } })
}),
+ notice: (kind, payload = {}) => send({ type: 'service_notice', payload: { ...payload, kind } }),
+ sendBinary: (bytes) => {
+ if (!socket || socket.readyState !== WebSocket.OPEN) return false
+ try { socket.send(bytes, { binary: true }); return true } catch { return false }
+ },
}
- const onFrame = (raw: WebSocket.RawData): void => {
+ const onFrame = (raw: WebSocket.RawData, isBinary = false): void => {
+ if (isBinary) {
+ try { options.onBinary?.(raw instanceof Buffer ? new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength) : new Uint8Array(Buffer.concat(raw as Buffer[]))) }
+ catch (error) { log(`[service ${options.name}] binary frame failed · ${describe(error)}`) }
+ return
+ }
let frame: { type?: unknown; payload?: Payload; asker?: { local?: unknown; owner?: unknown } }
try { frame = JSON.parse(raw.toString()) as typeof frame } catch { return }
const payload = frame.payload ?? {}
if (frame.type === 'connected') {
backoff = initialBackoffMs
+ opened = true
log(`[service ${options.name}] connected to the core`)
options.onConnected?.(core)
return
@@ -247,12 +269,17 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
machineId: options.machineId, localProtocolVersion: 1, role: 'service', service: options.name, token: options.token,
} })
})
- ws.on('message', onFrame)
+ ws.on('message', (raw, isBinary) => onFrame(raw, isBinary))
ws.on('error', () => { /* `close` follows, and reconnects */ })
ws.on('close', (code: number) => {
// A new socket is dialled only after this one closes, so this is always the current one.
+ const wasOpen = socket === ws && opened
socket = null
+ opened = false
for (const [id, waiting] of pending) { pending.delete(id); waiting.reject(new Error('the core went away')) }
+ if (wasOpen) {
+ try { options.onDisconnected?.() } catch (error) { log(`[service ${options.name}] disconnect failed · ${describe(error)}`) }
+ }
if (stopped) return
// Refused: this core does not run the service out of its process, as a core from before it did under
// a newer master, for as long as the two differ. Asked again every few seconds, it only filled both
diff --git a/cli/src/sharing/relay.ts b/cli/src/sharing/relay.ts
index 09c8bf5e9..f2f5d7ac7 100644
--- a/cli/src/sharing/relay.ts
+++ b/cli/src/sharing/relay.ts
@@ -2,7 +2,8 @@ import { WebSocket } from 'ws'
import { b64e, newEphemeral } from '../lib/e2ee/core.js'
import type { AuthSessionManager } from '../lib/authSession.js'
import type { Frame, LocalClientSink } from '../backendSocket.js'
-import { DAEMON_LOCAL_ONLY_TYPES, type RelaySession } from '../lib/remoteRelay.js'
+import type { RelaySession } from '../lib/remoteRelay.js'
+import { DAEMON_LOCAL_ONLY_TYPES } from '../lib/relayFrames.js'
import { recipientHandshake, type ObserverCipher } from './crypto.js'
import { BACKEND_IDLE_DEADLINE_MS, watchSocketLiveness } from '../lib/wsLiveness.js'